Opinionated Python Development Skill

Orchestration guide for Python development using specialized agents and modern Python 3.11-3.14 patterns.

Skill Architecture

Bundled Resources (Included in This Skill)

Reference Documentation:

• Modern Python Modules - 50+ library guides with usage patterns and best practices
• Tool & Library Registry - Development tools catalog for linting, testing, and build automation
• API Reference - API specifications and integration guides
• Python Development Orchestration - Detailed workflow patterns for TDD, feature addition, refactoring, and code review

Command Templates and Guides (commands/):

• Reference material for creating slash commands (NOT the actual slash commands)
• Command templates and patterns for development
• Testing and development workflow guides
• See Commands README for details

Scripts and Assets:

• Example scripts demonstrating patterns
• Configuration templates and boilerplate

External Dependencies (Required - Not Bundled)

Agents (install to ~/.claude/agents/):

• @agent-python-cli-architect - Python CLI development with Typer and Rich
• @agent-python-pytest-architect - Test suite creation and planning
• @agent-python-code-reviewer - Post-implementation code review
• @agent-python-portable-script - Standalone stdlib-only script creation
• @agent-spec-architect - Architecture design
• @agent-spec-planner - Task breakdown and planning
• @agent-spec-analyst - Requirements gathering

Slash Commands (install to ~/.claude/commands/):

• /modernpython - Python 3.11+ pattern enforcement and legacy code detection
• /shebangpython - PEP 723 inline script metadata validation

System Tools (install via package manager or uv):

• uv - Python package and project manager (required)
• ruff - Linter and formatter
• pyright - Type checker (Microsoft)
• mypy - Static type checker
• pytest - Testing framework
• pre-commit - Git hook framework
• mutmut - Mutation testing (for critical code)
• bandit - Security scanner (for critical code)

Installation Notes:

• Agents and slash commands must be installed separately in their respective directories
• This skill provides orchestration guidance and references; agents perform actual implementation
• Use the uv skill for comprehensive uv documentation and package management guidance

Core Concepts

Agents vs Commands vs Skills

Agents (external - in ~/.claude/agents/):

• Specialized implementations that run independently with their own context
• Create, test, and review Python code
• Examples: python-cli-architect, python-pytest-architect, python-code-reviewer

Commands (external - in ~/.claude/commands/):

• Slash commands for standards enforcement: /modernpython, /shebangpython
• Applied by orchestrator to check compliance
• Note: This skill contains command templates in commands/, not the actual slash commands

Skills (this skill):

• Orchestration guides for coordinating agents and commands
• Workflow patterns (TDD, feature addition, code review, debugging)
• Decision trees for choosing the right agent
• Reference documentation and templates

Delegation Pattern

Orchestrator responsibilities:

1. Choose the appropriate agent for the task
2. Provide clear inputs and context
3. Chain agents for complex workflows
4. Validate outputs with quality gates
5. Apply standards with commands

Orchestrator does NOT:

• Write Python implementation code directly
• Create tests directly
• Review code directly

Instead, delegate to specialized agents.

Quick Start

Basic CLI Tool Development

1. User: "Build a CLI tool to process CSV files"

2. Orchestrator decides:
   - This needs CLI with rich output → use python-cli-architect
   - Will need tests → python-pytest-architect
   - Will need review → python-code-reviewer

3. Workflow:
   @agent-python-cli-architect
   "Create CSV processing CLI with Typer+Rich progress bars"
   Reference: ~/.claude/agents/python-cli-demo.py

   → Implementation created

   @agent-python-pytest-architect
   "Create test suite for CSV processor"

   → Tests created

   Apply standards:
   /shebangpython src/csv_processor.py
   /modernpython src/

   @agent-python-code-reviewer
   "Review CSV processor implementation"

   → Quality verified

4. Validate:
   uv run pytest --cov
   uv run ruff check
   uv run pyright

Agent Selection

python-cli-architect: User-facing CLI applications with Typer+Rich (progress bars, tables, panels)

python-portable-script: Stdlib-only scripts for maximum portability (argparse, pathlib)

python-pytest-architect: Comprehensive test suites with 80%+ coverage, property-based testing

python-code-reviewer: Code quality validation, pattern checking, standards enforcement

For detailed agent selection criteria, characteristics, and usage examples, see Agent Selection Guide in the orchestration guide.

Command Usage

/modernpython

Purpose: Apply Python 3.11+ modern patterns and check for legacy code

When to use:

• Starting new development (reference guide)
• Reviewing existing code for upgrades
• Checking for legacy typing imports (List, Dict, Optional, Union)
• Learning Python 3.11-3.14 features

Pattern:

/modernpython src/mymodule.py
→ Identifies legacy patterns
→ Suggests modern alternatives
→ References official PEPs

/shebangpython

Purpose: Validate PEP 723 inline script metadata compliance

When to use:

• Creating standalone scripts
• Validating script portability
• Checking dependency declarations

Required for: ALL standalone Python scripts with external dependencies

Pattern:

/shebangpython scripts/deploy.py
→ Validates shebang: #!/usr/bin/env -S uv --quiet run --active --script
→ Checks PEP 723 metadata block
→ Verifies dependencies declared

Core Workflows

For detailed step-by-step workflow patterns, see Python Development Orchestration Guide.

Workflow Overview

1. TDD (Test-Driven Development): Design → Write Tests → Implement → Review → Validate
2. Feature Addition: Requirements → Architecture → Plan → Implement → Test → Review
3. Code Review: Self-Review → Standards Check → Agent Review → Fix → Re-validate
4. Refactoring: Tests First → Refactor → Validate → Review
5. Debugging: Reproduce → Trace → Fix → Test → Review

Each workflow uses agent chaining with specific quality gates. See the orchestration guide for complete patterns, examples, and best practices.

Quality Gates

Every Python task must pass:

1. Linting: uv run ruff check (clean)
2. Type checking: uv run pyright and uv run mypy
3. Tests: uv run pytest (>80% coverage)
4. Modern patterns: /modernpython (no legacy typing)
5. Script compliance: /shebangpython (for standalone scripts)

For critical code (payments, auth, security):

• Coverage >95%
• Mutation testing: uv run mutmut run (>90% score)
• Security scan: uv run bandit -r src/

Integration

External Reference Example

Complete working example (external): ~/.claude/agents/python-cli-demo.py

This reference implementation demonstrates all recommended patterns:

• PEP 723 metadata with correct shebang
• Typer + Rich integration
• Modern Python 3.11+ (StrEnum, Protocol, TypeVar, Generics)
• Annotated syntax for CLI params
• Async processing
• Comprehensive docstrings

This file is not bundled with this skill and must be available in ~/.claude/agents/ separately. Use as reference when creating CLI tools.

Common Anti-Patterns

❌ Don't: Write Python code as orchestrator → Do: Delegate to @agent-python-cli-architect ❌ Don't: Skip validation steps → Do: Always complete workflow (implement → test → review → validate) ❌ Don't: Mix agent contexts → Do: Choose agent matching requirements (CLI tool = python-cli-architect, portable = python-portable-script)

For detailed anti-pattern examples and corrections, see Anti-Patterns section in the orchestration guide.

Detailed Documentation

Reference Documentation

Core Orchestration Guide: Python Development Orchestration - Detailed workflow patterns for TDD, feature addition, refactoring, and code review with comprehensive agent coordination strategies

Module Reference: Modern Python Modules - Comprehensive guide to 50+ modern Python libraries with deep-dive documentation for each module including usage patterns and best practices

Tool Registry: Tool & Library Registry - Catalog of development tools, their purposes, and usage patterns for linting, testing, and build automation

API Documentation: API Reference - API specifications, integration guides, and programmatic interface documentation

Navigating Large References

To find specific modules in modern-modules.md:

grep -i "^### " references/modern-modules.md

To search for tools by category in tool-library-registry.md:

grep -A 5 "^## " references/tool-library-registry.md

To locate workflow patterns in python-development-orchestration.md:

grep -i "^## " references/python-development-orchestration.md

External Commands

These slash commands are external dependencies installed in ~/.claude/commands/:

• /modernpython - Python 3.11+ patterns and PEP references
• /shebangpython - PEP 723 validation and shebang standards

Summary

This skill guides the orchestration of Python 3 development

1. Choose the right agent for each task
2. Provide clear context and inputs
3. Chain agents for complex workflows (design → test → implement → review)
4. Apply standards by telling the sub-agent to run /modernpython and /shebangpython against the file
5. Orchestrate sub-agents to validate with quality gates (pytest, ruff, pyright, mypy, pre-commit)
6. Enable uv skill for all package management

Orchestration = Coordination + Delegation + Validation