Python Developer Agent Skill Suite

Composable agent skills for senior-level Python development. Each skill owns one responsibility and hands off to others through explicit contracts, so no single skill tries to be architect, implementer, reviewer, tester, security auditor, performance engineer, and production engineer at once.

Current version: 0.1.0 (see CHANGELOG.md).

Skill Map

Skill	Responsibility
python-agent-orchestrator	Routes work across the suite, defines handoff contracts
python-senior-architect	Architecture analysis, design, ADRs, plans, migration strategy
python-coder	Bounded implementation from a plan or clear request
python-reviewer	Code and PR review for correctness, regressions, maintainability
python-testing	Test strategy, fixtures, regression and contract coverage
python-security	Auth, secrets, injection, SSRF, dependencies, tenant isolation
python-performance	Profiling, database and async bottlenecks, caching, throughput
python-production	Deployment, observability, rollback, incidents, operational readiness
python-dependency-analyzer	Import graphs, cycles, layer violations, dependency health
python-architecture-scanner	Enforces layer contracts, forbidden-import rules, CI gates
python-data-architect	Persistence, data models, migrations, warehouses, pipelines
python-async-architect	Event loops, workers, queues, backpressure, messaging

Layout

Each skill lives in its own directory:

python-<name>/
├── SKILL.md          # instructions loaded by the host agent
├── references/       # depth material, pulled in on demand
├── templates/        # reusable output files
├── scripts/          # deterministic tooling
├── examples/         # illustrative outputs
└── agents/           # host-specific agent definitions

Top-level docs:

• PYTHON_AGENT_SKILL_SUITE.md — routing philosophy and recommended flows.
• PYTHON_SENIOR_ARCHITECT_SKILL_DESIGN.md — design rationale for the architect skill.
• INSTALL.md — per-host installation guide (opencode, Claude Code, Codex CLI, Kilo Code, Trae).
• examples/billing-feature-walkthrough.md — end-to-end artifact example across skills.
• evals/ — golden scenarios for measuring skill quality.
• scripts/validate_suite.py — consistency validation.
• CHANGELOG.md — version history.

Usage

1. Load the python-agent-orchestrator skill when a request spans roles or the right skill is unclear.
2. Otherwise load the matching specialist skill directly.
3. Follow each skill's handoff contract when moving between skills.

To install the suite into a specific host (opencode, Claude Code, Codex CLI, Kilo Code, Trae), see INSTALL.md. The agents/ folder in each skill holds host-specific agent definitions (for example OpenAI Agents SDK openai.yaml); for hosts without a dedicated definition, point the skill loader at the directory SKILL.md.

Validation

Run the suite consistency check:

python3 scripts/validate_suite.py

Testing

Unit tests cover the deterministic tooling (import graph, architecture report, layer rules, async-blocking detection, suite validator, and the eval judge). They use only the standard library:

python3 -m unittest discover -s tests -v

Redirect the bytecode cache so test runs do not pollute the tree:

PYTHONPYCACHEPREFIX=/tmp/opencode/pycache python3 -m unittest discover -s tests

Evals And LLM-As-Judge

evals/ holds golden scenarios per skill. To score a skill output against a scenario:

1. Run the skill against the scenario prompt and save its output, for example out/<skill>/<scenario>.md.
2. Judge it with an LLM-as-judge (requires LLM_API_KEY):

python3 scripts/judge_eval.py --skill python-coder --scenario coder-bugfix-idempotent --response out/python-coder/coder-bugfix-idempotent.md

3. Batch-judge a whole eval file (or all skills) with scripts/run_evals.py:

python3 scripts/run_evals.py --skill python-senior-architect --responses out/
python3 scripts/run_evals.py --responses out/

Judge configuration via environment (any OpenAI-compatible endpoint works — OpenAI, DeepSeek, Mistral, Ollama, vLLM, ...):

export LLM_API_KEY=...            # key your endpoint expects (required)
export LLM_BASE_URL=...           # e.g. https://api.deepseek.com/v1 (required)
export LLM_MODEL=...              # e.g. deepseek-chat (required)

OPENAI_API_KEY is accepted as a fallback key only. See evals/README.md for the format.

Individual tooling can be run directly:

python3 python-dependency-analyzer/scripts/import_graph.py <root>
python3 python-senior-architect/scripts/architecture_report.py <root> --domain-names <pkg...>
python3 python-architecture-scanner/scripts/check_layer_rules.py --config contract.json <root>
python3 python-async-architect/scripts/detect_async_blocking.py <root>
python3 scripts/sync_pyast_utils.py          # regenerate bundled shared-module fallbacks
python3 scripts/sync_pyast_utils.py --check  # verify fallbacks; exit non-zero on drift

The scripts share python-dependency-analyzer/scripts/pyast_utils.py for filesystem and AST scanning (stdlib only). Cross-skill scripts resolve the canonical copy when the suite is installed as a whole and fall back to a byte-identical bundled copy in their own skill, so a skill installed on its own still runs; scripts/validate_suite.py enforces the stdlib-only rule, that every bundled fallback matches the canonical module, and that no framework keyword belongs to more than one category. Regenerate fallbacks with python3 scripts/sync_pyast_utils.py rather than editing them by hand. Specialist overlap (for example performance vs async architect, or dependency analyzer vs architecture scanner) is governed by a machine-checked concern ownership map in python-agent-orchestrator/references/concern-ownership.md.

The stdlib-only rule applies to the suite's shipped scripts for portability. When a skill needs deeper evidence, its agent may call optional analysis tools that exist in the shell (bandit, ruff, networkx, pydeps, import-linter, ...); those are best-effort and must degrade gracefully — fall back to the suite scripts or repository inspection rather than fabricating a tool's output. See the "Deterministic vs Agent Tooling" policy in PYTHON_SENIOR_ARCHITECT_SKILL_DESIGN.md.

Roadmap

• Core skill set (orchestrator, architect, coder, reviewer, testing, security, performance, production, dependency-analyzer).
• Optional specialists: architecture scanner, data architect, async architect.
• Architect structure materialized (references, templates, scripts, examples, agent config).
• Suite validation script.
• Eval scenarios.
• Deeper references for testing, security, performance, production.
• Versioned releases and changelog.
• First release cut and tagged.

License

MIT