Skills Reference =============================================================================== create-python-project ------------------------------------------------------------------------------- Scaffolds a new Python project from the ByteCode Solutions blueprint template. **Invocation** .. code-block:: bash /create-python-project [project-name] The ``project-name`` argument is optional. If omitted, the skill will prompt for a name before proceeding. **Behavior** 1. Resolves the project name from the argument or by prompting the user. 2. Asks for the target parent directory (defaults to the current working directory). 3. Clones the blueprint template: .. code-block:: bash git clone https://gitlab.com/bytecode-solutions/templates/blueprint-python.git 4. Confirms success and shows the resulting directory structure. **Frontmatter** .. list-table:: :header-rows: 1 :widths: 30 70 * - Field - Value * - ``disable-model-invocation`` - ``true``, must be invoked explicitly; Claude will not trigger it automatically * - ``argument-hint`` - ``[project-name]`` * - ``allowed-tools`` - ``Bash(git clone *)``, ``Bash(mv *)`` run-linters ------------------------------------------------------------------------------- Runs all linters and type checkers on a Python package sequentially. **Invocation** .. code-block:: bash /run-linters The ``package`` argument is required and must be the name of the Python package or directory to analyse. **Pre-execution check** Before running any linter the skill checks that all five tools are installed: .. code-block:: bash pip freeze | grep -E "^(ty|ruff|mypy|pyright|pylint)==" If any tool is missing the skill stops and advises the user to either install the missing tools individually (e.g. ``pip install ruff mypy``) or install ``core-dev-tools``, which bundles all of them and is the default in the ByteCode Solutions ecosystem. **Behavior** Runs each tool one at a time in this order: 1. ``ty check `` 2. ``ruff check `` 3. ``mypy --explicit-package-bases `` 4. ``pyright `` 5. ``pylint `` If a tool exits with errors the skill stops immediately and asks the user whether they want to fix the issues before continuing. The ``tests/`` package is excluded, test code is not required to comply with linters and type checkers. **Frontmatter** .. list-table:: :header-rows: 1 :widths: 30 70 * - Field - Value * - ``disable-model-invocation`` - ``true``, must be invoked explicitly; Claude will not trigger it automatically * - ``argument-hint`` - ```` * - ``allowed-tools`` - ``Bash(pip freeze *)``, ``Bash(ty check *)``, ``Bash(ruff check *)``, ``Bash(mypy *)``, ``Bash(pyright *)``, ``Bash(pylint *)`` run-tests ------------------------------------------------------------------------------- Runs the project test suite, stops on failure, and iterates through fixes one by one. **Invocation** .. code-block:: bash /run-tests No arguments, the skill detects the available runner automatically. **Behavior** 1. Checks whether ``core-tests`` is installed and ``manager.py`` exists. If both are present, runs ``python manager.py run-tests``. 2. Otherwise falls back to ``pytest``: - Inspects ``tests/`` to detect the file naming convention (``test_*.py``, ``tests_*.py``, ``*_test.py``, etc.). - Builds ``--override-ini="python_files="`` from the detected patterns and runs ``pytest tests/unit tests/integration``. - After the first successful run, persists the discovered pattern to the project's ``CLAUDE.md`` so future invocations skip the inspection step. 3. If neither runner is available, stops and advises the user to install ``core-tests`` (the default in the ByteCode Solutions ecosystem) or ``pytest``. **Rules** - Functional tests are **never** executed. - Runs directly in the conversation, no agents or subagents. **On failure** If any tests fail the skill: 1. Parses the output to identify every failing test. 2. Reports the full list to the user. 3. Asks whether the user wants to fix the failures. 4. If yes, creates one task per failing test (``TaskCreate``), then works through them one by one: fix → re-run that test in isolation via ``pytest `` → mark the task complete → move to the next. Pytest is always used for isolated re-runs because ``manager.py run-tests`` does not support targeting a single test. **Frontmatter** .. list-table:: :header-rows: 1 :widths: 30 70 * - Field - Value * - ``disable-model-invocation`` - ``true``, must be invoked explicitly; Claude will not trigger it automatically * - ``allowed-tools`` - ``Bash(pip freeze *)``, ``Bash(python manager.py *)``, ``Bash(find tests *)``, ``Bash(pytest *)`` run-coverage ------------------------------------------------------------------------------- Runs test coverage, stops on failure, and iterates through fixes one by one. **Invocation** .. code-block:: bash /run-coverage No arguments, the skill detects the available runner automatically. **Behavior** 1. Checks whether ``core-tests`` is installed and ``manager.py`` exists. If both are present, runs ``python manager.py run-coverage``. 2. Otherwise falls back to ``pytest`` with ``pytest-cov``: - Inspects ``tests/`` to detect the file naming convention (``test_*.py``, ``tests_*.py``, ``*_test.py``, etc.). - Builds ``--override-ini="python_files="`` from the detected patterns and runs: .. code-block:: bash pytest tests/unit tests/integration --cov --cov-report=term-missing \ --override-ini="python_files=" - After the first successful run, persists the discovered pattern to the project's ``CLAUDE.md`` so future invocations skip the inspection step. 3. If neither runner is available, stops and advises the user to install ``core-tests`` (the default in the ByteCode Solutions ecosystem) or ``pytest`` with ``pytest-cov``. **Rules** - Functional tests are **never** executed. - Runs directly in the conversation, no agents or subagents. **Reporting** After a successful run the skill reports: - The **total coverage %** of the project. - Every module below **100 %**, listed with its individual percentage. If coverage is not 100 %, the skill asks the user whether they want to reach 100 %. If yes, it creates one task per under-covered file (``TaskCreate``) and works through them one by one: write or fix tests → re-run coverage for that module to verify → mark the task complete → move to the next. **On failure** If any tests fail during the coverage run, the ``/run-tests`` skill is invoked immediately, it owns failure identification, user confirmation, per-test task creation, and iterative fixing. **Frontmatter** .. list-table:: :header-rows: 1 :widths: 30 70 * - Field - Value * - ``disable-model-invocation`` - ``true``, must be invoked explicitly; Claude will not trigger it automatically * - ``allowed-tools`` - ``Bash(pip freeze *)``, ``Bash(python manager.py *)``, ``Bash(find tests *)``, ``Bash(pytest *)`` run-security ------------------------------------------------------------------------------- Runs security vulnerability checks on a Python package using ``bandit`` (static code analysis) and ``pip-audit`` (dependency CVE scanning). **Invocation** .. code-block:: bash /run-security The ``package`` argument is required and must be the name of the Python package or directory to analyse. **Pre-execution check** Before running any tool the skill checks that both are installed: .. code-block:: bash pip freeze | grep -E "^(bandit|pip-audit)==" If either tool is missing the skill stops and advises the user to either install the missing tools individually (e.g. ``pip install bandit pip-audit``) or install ``core-dev-tools``, which bundles all of them and is the default in the ecosystem. **Behavior** Runs each tool one at a time in this order: 1. ``bandit -r ``: scans ```` for insecure code patterns (hardcoded secrets, unsafe calls, known dangerous APIs, etc.). 2. ``pip-audit``: scans all installed dependencies against known CVEs. No package argument is needed; it covers the entire environment. If a tool exits with findings the skill stops immediately and asks the user whether they want to address the issues before continuing. **Frontmatter** .. list-table:: :header-rows: 1 :widths: 30 70 * - Field - Value * - ``disable-model-invocation`` - ``true``, must be invoked explicitly; Claude will not trigger it automatically * - ``argument-hint`` - ```` * - ``allowed-tools`` - ``Bash(pip freeze *)``, ``Bash(bandit *)``, ``Bash(pip-audit *)`` develop ------------------------------------------------------------------------------- Orchestrates a complete development task end-to-end: structured planning, multi-agent TDD implementation, and a final analysis pass. **Invocation** .. code-block:: bash /develop [task description] The ``task description`` argument is optional. If omitted, the skill uses the task already described in the conversation. **Principles** The following principles are applied throughout every phase: .. list-table:: :header-rows: 1 :widths: 15 85 * - Principle - Rule * - TDD - Write tests before implementation. No production code without a failing test first. Prefer ``unittest.TestCase`` subclasses; pytest-style functions only if the user requests them or the existing codebase already uses that convention. * - SOLID - Single responsibility per class; depend on abstractions, not concretions; open for extension, closed for modification. * - DRY - Every piece of knowledge has a single authoritative location. No duplicated logic. * - KISS - Prefer the simplest solution that satisfies the requirement. Complexity must be justified. * - YAGNI - Do not build what is not needed now. No speculative abstractions or future-proofing hooks. * - LoD - A component only calls methods on its immediate dependencies, never reaches through them to a third object. * - Imports - All ``import`` statements must be at the top of the file. Importing inside a function or method is forbidden, it hides circular dependencies and makes the dependency graph opaque. **Environment setup** Before any planning or implementation, the skill checks whether a ``.venv`` directory exists: - **If present**: all subsequent ``python``, ``pip``, and ``pytest`` calls use the venv (via ``. .venv/bin/activate &&`` prefix or direct ``.venv/bin/*`` paths). - **If absent**: asks the user which Python version to use, then creates and activates the virtual environment: .. code-block:: bash -m venv .venv . .venv/bin/activate && pip install --upgrade pip Then asks whether to install project dependencies (e.g. ``pip install -e .[dev]``) and runs the install if confirmed. All commands across every phase run inside the virtual environment. **Phase 1: Planning** Before proposing anything, the skill reads the existing codebase (``CLAUDE.md``, directory structure, relevant source files) to avoid designing in a vacuum. It then enters plan mode and: 1. Breaks the task into sub-problems. 2. For each sub-problem, identifies components, classes, interfaces, and dependencies; applies design patterns and documents the rationale. 3. When multiple valid design approaches exist, **stops and asks the user**, never picks autonomously. Follows this decision rule for composition vs. inheritance: - **is-a** relationship → inheritance (Liskov Substitution Principle holds). - **has-a** relationship → composition (delegation, no substitutability needed). - **Runtime behavior injection** → composition via Strategy, Decorator, or dependency injection. "Prefer composition over inheritance" is a guard against misuse, not a universal default. When the relationship is ambiguous, both options are presented and the user decides. 4. Uses ``WebSearch`` / ``WebFetch`` for any required technical clarification. 5. Creates ``PLAN.md`` at the project root with: problem statement, sub-problems, per-component interface (as Python abstract class or ``Protocol``), dependency graph, test strategy, and design notes. 6. Writes Python interface stubs (ABCs or ``typing.Protocol``) with full type annotations and one-line per-method docstrings, no implementation bodies. These are the contracts agents must implement exactly. The skill exits plan mode and **waits for the user to review and approve ``PLAN.md``** before proceeding to implementation. **Phase 2: Implementation** 1. Creates a feature branch: ``git checkout -b feature/``. 2. Reads ``PLAN.md`` to determine component dependency order: - **Independent components**: agents are spawned **in parallel**. - **Dependent components**: agents are spawned **sequentially**, after their dependencies are confirmed complete. 3. Each agent receives its stub file, its ``PLAN.md`` section, and the project context. Every agent must: - Write unit tests first (**TDD**: tests before implementation). - Implement the component until all tests pass. - Achieve **100 % unit test coverage** for its component. - Run ``/run-linters `` and fix all issues before reporting back. - Match the stub interface exactly (flag any deviation for approval). 4. If an agent cannot reach 100 % coverage or a linter-clean state, main Claude takes over and resolves the remaining issues inline. 5. After all agents complete, main Claude writes **integration tests** covering cross-component interactions and end-to-end flows, then runs the full suite. **Phase 3: Analysis** Runs sequentially in the main conversation (no agents): 1. ``/run-linters ``: linters and type checkers across the full package. 2. ``/run-security ``: bandit static analysis + pip-audit CVE scan. 3. ``/security-review``: built-in Claude Code security review of pending changes. 4. ``/review``: built-in Claude Code code review. After findings are addressed: - Creates a **single git commit** using `Conventional Commits `_ format (``feat``, ``fix``, ``refactor``, ``test``, ``docs``, ``chore``). - Creates ``DIAGRAM.md`` (Mermaid graph) if the task involved two or more components with notable relationships. - Reports to the user: per-component summary, total coverage, issues resolved, branch name and commit SHA. - Asks whether to open a pull request. **Rules** - Functional tests are **never** executed. - Each phase runs directly in the main conversation; agents are used only for per-component implementation in Phase 2. **Frontmatter** .. list-table:: :header-rows: 1 :widths: 30 70 * - Field - Value * - ``disable-model-invocation`` - ``true``, must be invoked explicitly; Claude will not trigger it automatically * - ``argument-hint`` - ``[task description]`` * - ``allowed-tools`` - ``Bash(git *)``, ``Bash(find *)``, ``Bash(ls *)``, ``Bash(pip freeze *)``, ``Bash(pytest *)``, ``Bash(python manager.py *)``, ``Bash(python* -m venv *)``, ``Agent``, ``WebSearch``, ``WebFetch``, ``TaskCreate``, ``TaskUpdate``, ``Read``, ``Edit``, ``Write``