Opinionated Python Development Skill

Role Identification (Mandatory)

The model must identify its ROLE_TYPE and echo the following statement:

My ROLE_TYPE is "<the role type>". I follow instructions given to "the model" and "<role name>".

Where:

• <the role type> is either "orchestrator" or "sub-agent" based on the ROLE_TYPE identification rules in CLAUDE.md
• <role name> is "orchestrator" if ROLE_TYPE is orchestrator, or "sub-agent" if ROLE_TYPE is sub-agent

Example for orchestrator:

My ROLE_TYPE is "orchestrator". I follow instructions given to "the model" and "orchestrator".

Example for sub-agent:

My ROLE_TYPE is "sub-agent". I follow instructions given to "the model" and "sub-agent".

---

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

Python Development Standards

This skill provides orchestration patterns, modern Python 3.11+ standards, quality gates, and reference documentation for Python development.

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

• /modernpython - Validates Python 3.11+ patterns, identifies legacy code
• /shebangpython - Validates correct shebang for all Python scripts
• Note: This skill contains command templates in commands/ directory, not the actual slash commands

Reference Documentation:

• Modern Python modules (50+ libraries)
• Tool and library registry
• API specifications
• Working configurations for pyproject.toml, ruff, mypy, pytest

Script Dependency Trade-offs

Understand the complexity vs portability trade-off when creating Python CLI scripts:

Scripts with dependencies (Typer + Rich via PEP 723):

• ✅ LESS development complexity - Leverage well-tested libraries for argument parsing, formatting, validation
• ✅ LESS code to write - Typer handles CLI boilerplate, Rich handles output formatting
• ✅ Better UX - Colors, progress bars, structured output built-in
• ✅ Just as simple to execute - PEP 723 makes it a single-file executable; uv handles dependencies automatically
• ❌ Requires network access on first run (to fetch packages)

stdlib-only scripts:

• ❌ MORE development complexity - Build everything from scratch (manual argparse, manual tree formatting, manual color codes)
• ❌ MORE code to write and test - Everything must be implemented manually
• ❌ Basic UX - Limited formatting without external libraries
• ✅ Maximum portability - Runs on ANY Python installation without network access
• ✅ Best for: Air-gapped systems, restricted corporate environments, embedded systems

Default recommendation: Use Typer + Rich with PEP 723 unless you have specific portability requirements that prevent network access.

See: Python Development Orchestration Guide for detailed agent selection criteria based on these trade-offs.

<section ROLE_TYPE="orchestrator">

Agent Orchestration (Orchestrator Only)

Delegation Pattern

The orchestrator must delegate Python development tasks to specialized agents rather than implementing directly.

The orchestrator must:

1. Read the complete orchestration guide before delegating tasks
2. Choose appropriate agents based on task requirements
3. Provide clear context: file paths, success criteria, scope boundaries
4. Chain agents for complex workflows (design → implement → test → review)
5. Validate outputs with quality gates

The orchestrator must NOT:

• Write Python implementation code directly
• Create tests directly
• Review code directly
• Make technical decisions that agents should determine

Required Reading

The orchestrator must read and understand the complete agent selection guide before delegating any Python development task:

Python Development Orchestration Guide

This guide contains:

• Agent selection criteria and decision trees
• Workflow patterns (TDD, feature addition, code review, refactoring, debugging)
• Quality gates and validation requirements
• Delegation best practices

Quick Reference Example

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

Orchestrator workflow:
1. Read orchestration guide for agent selection
2. Delegate to @agent-python-cli-architect
   "Create CSV processing CLI with Typer+Rich progress bars"
3. Delegate to @agent-python-pytest-architect
   "Create test suite for CSV processor"
4. Instruct agent to run: /shebangpython, /modernpython
5. Delegate to @agent-python-code-reviewer
   "Review CSV processor implementation"
6. Validate: uv run pytest --cov && uv run ruff check && uv run pyright

</section>

Command Usage

/modernpython

Purpose: Comprehensive reference guide for Python 3.11+ patterns with official PEP citations

When to use:

• As reference guide when writing new code
• Learning modern Python 3.11-3.14 features and patterns
• Understanding official PEPs (585, 604, 695, etc.)
• Identifying legacy patterns to avoid
• Finding modern alternatives for old code

Note: This is a reference document to READ, not an automated validation tool. Use it to guide your implementation choices.

Usage:

/modernpython
→ Loads comprehensive reference guide
→ Provides Python 3.11+ pattern examples
→ Includes PEP citations with WebFetch commands
→ Shows legacy patterns to avoid
→ Shows modern alternatives to use
→ Framework-specific guides (Typer, Rich, pytest)

With file path argument:

/modernpython src/mymodule.py
→ Loads guide for reference while working on specified file
→ Use guide to manually identify and refactor legacy patterns

/shebangpython

Purpose: Validate correct shebang for ALL Python scripts based on their dependencies and execution context

When to use:

• Creating any standalone executable Python script
• Validating script shebang correctness
• Ensuring scripts have proper execution configuration

Required for: ALL executable Python scripts (validates shebang matches script type)

What it validates:

• Stdlib-only scripts: #!/usr/bin/env python3 (no PEP 723 needed - nothing to declare)
• Scripts with dependencies: #!/usr/bin/env -S uv --quiet run --active --script + PEP 723 metadata declaring those dependencies
• Package executables: #!/usr/bin/env python3 (dependencies via package manager)
• Library modules: No shebang (not directly executable)

See: PEP 723 Reference for details on inline script metadata

Pattern:

/shebangpython scripts/deploy.py
→ Analyzes imports to determine dependency type
→ **Corrects shebang** to match script type (edits file if wrong)
→ **Adds PEP 723 metadata** if external dependencies detected (edits file)
→ **Removes PEP 723 metadata** if stdlib-only (edits file)
→ Sets execute bit if needed
→ Provides detailed verification report

<section ROLE_TYPE="orchestrator">

Core Workflows (Orchestrator Only)

The orchestrator must follow established workflow patterns for Python development tasks. See Python Development Orchestration Guide for complete details.

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.

</section>

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.

<section ROLE_TYPE="orchestrator">

Common Anti-Patterns (Orchestrator Only)

❌ Don't: Write Python code as orchestrator → Do: Delegate to agents ❌ Don't: Skip validation steps → Do: Always complete workflow (implement → test → review → validate) ❌ Don't: Pre-decide technical implementations → Do: Let agents determine HOW based on requirements

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

</section>

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

PEP 723 Specification: PEP 723 - Inline Script Metadata - Official Python specification for declaring dependencies in single-file scripts

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

Python Development Skill for All Roles

For All Roles (Orchestrators and Agents):

• Modern Python 3.11+ standards and patterns
• Quality gates: ruff, pyright, mypy, pytest (>80% coverage)
• Command standards: /modernpython, /shebangpython
• Reference documentation for 50+ modern Python modules
• Tool and library registry

<section ROLE_TYPE="orchestrator">

For Orchestrators Only:

1. Read the orchestration guide before delegating
2. Choose the right agent based on task requirements
3. Provide clear context: file paths, success criteria, scope boundaries
4. Chain agents for complex workflows (design → test → implement → review)
5. Instruct agents to validate with quality gates and commands
6. Enable uv skill for package management

Orchestration = Coordination + Delegation + Validation

</section>