Skills Reference

create-python-project

Scaffolds a new Python project from the ByteCode Solutions blueprint template.

Invocation

/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:

   git clone https://gitlab.com/bytecode-solutions/templates/blueprint-python.git <project-name>
   

4. Confirms success and shows the resulting directory structure.

Frontmatter

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

/run-linters <package>

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:

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 <package>

2. ruff check <package>

3. mypy --explicit-package-bases <package>

4. pyright <package>

5. pylint <package>

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

Field	Value
disable-model-invocation	true, must be invoked explicitly; Claude will not trigger it automatically
argument-hint	<package>
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

/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=<patterns>" 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 <test_id> → 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

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

/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=<patterns>" from the detected patterns and runs:

     pytest tests/unit tests/integration --cov --cov-report=term-missing \
       --override-ini="python_files=<patterns>"
     

   • 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

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

/run-security <package>

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:

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 <package>: scans <package> 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

Field	Value
disable-model-invocation	true, must be invoked explicitly; Claude will not trigger it automatically
argument-hint	<package>
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

/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:

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:

  <python-version> -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/<task-slug>.

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 <package> 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 <package>: linters and type checkers across the full package.

2. /run-security <package>: 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

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