#988: Split PTB maintenance guidance from packaged skill

.agents/skills/maintain-ptb/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: maintain-ptb
+description: "Maintain and extend the Exasol Python Toolbox repository itself. Covers PTB source code, Nox sessions, configuration, workflow templates, packaged agent skills, tests, documentation, and the project template."
+---
+
+# Maintain Exasol Python Toolbox
+
+Use this skill for changes to the `python-toolbox` repository. Use the packaged
+`exasol-python-toolbox` skill in downstream projects that consume PTB.
+
+## Task routing
+
+Select the reference that matches the task:
+
+- To locate implementation, templates, tests, or documentation, read
+  `references/source-routing.md`.
+- To change PTB design, source code, Nox sessions, workflow templates, the
+  project template, or packaged skills, read `references/coding-guidelines.md`.
+
+## Maintenance rules
+
+- Read the implementation and its tests before changing or explaining exact
+  behavior.
+- Preserve the standard PTB task interface used by downstream projects.
+- Run `project:check` when a change affects shared behavior, CI, or release
+  readiness.
+- Update tests, user documentation, and `doc/changes/unreleased.md` with public
+  behavior changes.
+- Keep repository-maintenance guidance in this local skill. Limit skills below
+  `exasol/toolbox/skills/` to downstream usage guidance.

.agents/skills/maintain-ptb/references/coding-guidelines.md

@@ -0,0 +1,43 @@
+# Coding Guidelines for PTB Maintenance
+
+PTB is a development dependency and a task interface for Exasol Python
+projects. Preserve the conventions that let projects use the same commands and
+automation.
+
+Use `doc/design.rst` for PTB design principles. Use the matching user-guide
+feature page for current public behavior.
+
+## Design rules
+
+- Treat PTB as development tooling. Keep PTB imports in development code.
+- Prefer conventions. Add configuration when a project needs behavior beyond
+  the convention.
+- Use `pyproject.toml` for static tool configuration.
+- Use `noxconfig.py` and `PROJECT_CONFIG` for dynamic project configuration.
+- Use plugin hooks or explicit extension points for project-specific work.
+- Keep GitHub workflows as orchestration. Put shared task logic in Python
+  functions or Nox sessions.
+- Add PTB features in response to concrete project needs. Move project logic
+  into PTB when multiple projects need the same behavior.
+- Define user-facing Nox sessions in `exasol/toolbox/nox/`. Put reusable logic
+  below `exasol/toolbox/util/` in functions that receive the Nox `Session` when
+  needed.
+
+## Generated projects and workflows
+
+- Check generated workflows after workflow-template changes. Generate them
+  when the source template, configuration, or patch intentionally changes
+  their output.
+- Update the project-template tests when a change affects newly created
+  projects.
+
+## Agent skills
+
+- Put downstream runtime skills below `exasol/toolbox/skills/`. The
+  `skills:install` session installs every skill in that package into consuming
+  projects.
+- Put PTB repository skills below `.agents/skills/` so they remain local to the
+  repository.
+- Limit packaged skills to downstream workflows and public PTB interfaces.
+- Cover packaged-skill changes with evaluation cases, packaging tests,
+  installation tests, and user documentation.

.agents/skills/maintain-ptb/references/source-routing.md

@@ -0,0 +1,95 @@
+# PTB Maintainer Source Routing
+
+Use this reference to find the source file for exact PTB behavior. Read the
+implementation and related tests before changing or explaining it.
+
+## Project entry points
+
+- `pyproject.toml`: package data, dependencies, and tool configuration.
+- `noxfile.py`: local Nox entry point.
+- `noxconfig.py`: PTB's `PROJECT_CONFIG` and release hooks.
+- `README.rst`: project overview.
+- `doc/design.rst`: PTB design rules.
+
+## Configuration
+
+- `exasol/toolbox/config.py`: `BaseConfig`, computed configuration fields,
+  supported versions, paths, workflow variables, and plugin validation.
+- `exasol/toolbox/nox/plugin.py`: Nox plugin hooks.
+
+## Nox session modules
+
+- `exasol/toolbox/nox/_artifacts.py`: artifact validation, copy, and Sonar
+  upload sessions.
+- `exasol/toolbox/nox/_dependencies.py`: dependency, vulnerability, license,
+  and SBOM sessions.
+- `exasol/toolbox/nox/_documentation.py`: documentation, links, and changelog
+  sessions.
+- `exasol/toolbox/nox/_format.py`: format fix and check sessions.
+- `exasol/toolbox/nox/_lint.py`: code, typing, and security lint sessions.
+- `exasol/toolbox/nox/_matrix.py`: matrix output sessions for CI.
+- `exasol/toolbox/nox/_package.py`: package validation.
+- `exasol/toolbox/nox/_release.py`: release preparation, update, and trigger
+  sessions.
+- `exasol/toolbox/nox/_skills.py`: packaged-skill validation and installation
+  sessions.
+- `exasol/toolbox/nox/_test.py`: unit, integration, and coverage sessions.
+- `exasol/toolbox/nox/_workflow.py`: workflow check, generation, and audit
+  sessions.
+
+## Nox support files
+
+- `exasol/toolbox/nox/_shared.py`: historical shared helpers. Put new reusable
+  logic below `exasol/toolbox/util/` when more than one session needs it.
+- `exasol/toolbox/nox/tasks.py`: exported session list. Import new session
+  modules here so downstream `noxfile.py` files can import the standard tasks.
+  Implement sessions in dedicated `_*.py` modules.
+
+## Packaged and repository-local skills
+
+- `.agents/skills/`: repository-local maintenance skills.
+- `exasol/toolbox/skills/`: skills packaged in the wheel and installed into
+  downstream projects.
+- `exasol/toolbox/util/skill_eval.py`: evaluation-case models.
+- `exasol/toolbox/util/skills.py`: skill discovery, validation, and
+  installation helpers.
+- `test/resources/skills/`: evaluation cases for packaged skills.
+- `test/unit/skills_test.py`: package, installation, and skill-specific tests.
+- `test/unit/util/skill_test.py`: shared validation and installation tests.
+
+## Tools and reusable logic
+
+- `exasol/toolbox/tools/issue.py`: issue-template CLI.
+- `exasol/toolbox/tools/replace_version.py`: version replacement helpers.
+- `exasol/toolbox/tools/security.py`: security issue conversion and creation.
+- `exasol/toolbox/tools/tbx.py`: CLI root.
+- `exasol/toolbox/tools/template.py`: template list, show, diff, install, and
+  update helpers.
+- `exasol/toolbox/util/dependencies/`: dependency audit, licenses, changes,
+  vulnerability tracking, and updates.
+- `exasol/toolbox/util/git.py`: Git helpers.
+- `exasol/toolbox/util/release/`: changelog, release notes, and Cookiecutter
+  version helpers.
+- `exasol/toolbox/util/version.py`: version parsing and upgrades.
+
+## Workflows, documentation, and templates
+
+- `exasol/toolbox/templates/github/workflows/`: packaged workflow templates.
+- `exasol/toolbox/templates/github/`: other packaged GitHub templates and
+  zizmor configuration.
+- `exasol/toolbox/util/workflows/`: workflow rendering, patching, validation,
+  and custom-workflow extraction.
+- `.workflow-patcher.yml`: workflow patch configuration for this repository.
+- `.github/workflows/`: generated repository workflows.
+- `.github/actions/`: repository GitHub actions.
+- `doc/user_guide/`: user tasks and feature documentation.
+- `doc/developer_guide/`: maintainer and plugin documentation.
+- `doc/api/`: API documentation entry points.
+- `doc/changes/`: changelog files.
+- `project-template/`: Cookiecutter template for new PTB projects.
+
+## Tests
+
+- `test/unit/`: unit tests for PTB behavior.
+- `test/integration/`: integration tests.
+- `test/integration/project-template/`: generated-project tests.

doc/changes/unreleased.md

@@ -1,3 +1,7 @@
 # Unreleased
 
 ## Summary
+
+## Refactoring
+
+* #988: Split PTB repository maintenance guidance from the packaged skill.

doc/developer_guide/agent_skills.rst

@@ -3,6 +3,18 @@
 Testing Agent Skills
 ====================
 
+Repository-local maintainer skill
+---------------------------------
+
+The ``.agents/skills/maintain-ptb`` skill contains source routing and
+development rules for maintaining this repository. The ``skills:install``
+session copies skills from ``exasol/toolbox/skills`` and keeps this skill local
+to the repository.
+
+Keep downstream PTB usage guidance in the packaged
+``exasol-python-toolbox`` skill. Place PTB implementation paths and repository
+maintenance rules in the repository-local maintainer skill.
+
 Packaged Skills
 ---------------
 

doc/user_guide/features/agent_skills/index.rst

@@ -24,7 +24,9 @@ skill names with this list in mind.
        docstrings, user-facing documentation, and runtime behavior.
    * - ``exasol-python-toolbox``
      - Guides agents in using PTB setup, Nox sessions, checks, workflows,
-       updates, releases, and configuration.
+       updates, releases, and configuration in a consuming project. PTB
+       repository maintenance guidance stays in the repository-local
+       ``maintain-ptb`` skill.
 
 Run the validation with: