python-engineering

Performs holistic code review after feature implementation. Checks design quality, typed-boundary compliance, testing adequacy, and maintainability.

Creates, enhances, and reviews Python CLI code using Typer and Rich — use for CLI tools, scripts with progress bars or tables, async processing, modernizing existing CLIs, or any Python implementation task.

Produces architecture specifications for Python CLI applications — 11-section design-first specs covering Executive Summary, Architecture Overview, Technology Stack, Component Design, Data Architecture, Type System Design, Security Architecture, Testing Architecture, Distribution Architecture, ADRs, and Scalability Strategy. Activates on architecture planning requests for new CLI tools or major feature additions. Produces WHAT to build (interfaces, schemas, contracts); python-cli-architect handles the HOW (implementation).

Creates, reviews, or modernizes Python 3.11+ pytest test suites. Expert in fixture design, parametrization, hypothesis property-based tests, and coverage strategy.

Semantic search over Python codebases for finding relevant patterns, implementations, and usage examples.

Use when analyzing failing test cases to determine whether failures indicate genuine bugs or test implementation issues. Activates on "analyze failing tests", "debug test failures", "investigate test errors", or when provided with specific failing test names or output. Applies balanced investigative reasoning — does not auto-fix tests without establishing root cause.

Use when building async APIs, concurrent systems, or I/O-bound Python applications requiring non-blocking operations. Covers asyncio, async/await patterns, task scheduling, synchronization primitives, and high-performance concurrent programming.

Use when improving Python code quality through focused cleanup, smell investigation, modernization, and typed-boundary hardening. Invoke for refactoring tasks, dead code removal, or modernization passes.

Use when reviewing pytest test suites for coverage, isolation, mock usage, naming conventions, or completeness. Activates on requests like "review test coverage", "audit test quality", or "check tests for completeness". Performs thorough checklist-driven review for test isolation, mock correctness, AAA pattern adherence, and naming standards.

Use when creating a new feature task with structured tracking, phases, and documentation. Activates on "create a feature task", "set up development tracking", or "plan a feature implementation" requests. Produces a comprehensive feature development task with acceptance criteria, phase breakdown, and tracking artifacts ready for SAM pipeline execution.

Use when debugging Python failures using a structured investigation workflow focused on reproduction, boundary assumptions, and root-cause isolation. Activate for tracebacks, test failures, or unexpected behavior.

Use when working with Hatchling — configuring build system setup, pyproject.toml metadata, dependencies, entry points, build hooks, version management, wheel and sdist builds, package distribution, setuptools migration, or troubleshooting Hatchling build errors. Covers PEP 517/518/621/660 standards.

Use when running or guiding deterministic Python quality checks, including linting, typing, test, and policy validation workflows. Invoke for ruff, ty, or pre-commit checks.

Comprehensive guide for creating and managing MkDocs documentation projects with Material theme. Includes official CLI command reference with complete parameters and arguments, and mkdocs.yml configuration reference with all available settings and valid values. Use when working with MkDocs projects including site initialization, mkdocs.yml configuration, Material theme customization, plugin integration, or building static documentation sites from Markdown files.

Reference guide for Python 3.11+ patterns with PEP citations. Use when reviewing code for modernization opportunities, writing new Python 3.11+ code to ensure modern patterns, refactoring legacy code to current idioms, or learning about specific PEPs and features.

Use when orchestrating a multi-step Python engineering workflow from a user-supplied task description. Invoke to coordinate planning, implementation, testing, and validation across skills.

Use when setting up automated code quality checks on git commit, configuring .pre-commit-config.yaml, implementing git hooks for formatting or linting, creating prepare-commit-msg hooks, or distributing a tool as a pre-commit hook. Covers pre-commit and prek for multi-language projects.

Use when creating a README for a Python package, preparing for PyPI publication, fixing README rendering errors found by twine check, choosing between README.md and README.rst, or configuring the readme field in pyproject.toml. Generates professional, PyPI-compliant README files.

Knowledge base of cross-platform compatibility tips, tricks, and helper patterns for Python scripts targeting Windows, Linux, macOS, CLI, TUI (Rich/Textual), and GUI environments. Use when writing Python scripts that must run on multiple platforms, when Rich or Typer output breaks on Windows, when dealing with Unicode/encoding issues, terminal detection, path separators, or console color support. Covers: stdout/stderr encoding guards, ANSI escape handling, Windows console quirks, terminal capability detection, and portable I/O patterns.

Guided workflow for adding new features to Python projects. Use when planning a new feature implementation, when adding functionality with proper test coverage, or when following TDD to build features incrementally.

Python CLI application development with Typer and Rich. Activates on Typer, Rich, CLI tools, progress bars, terminal output, Annotated syntax, or command-line application requests. Covers app structure, parameter types, subcommands, async patterns, and testing with CliRunner.

Python engineering foundation for all projects. Activates automatically on any Python task — establishes coding standards, SOLID guidance, typing policy, testing defaults, tooling expectations, and code smell detection as design signals. Routes to specialist skills for TDD, CLI, web, data, or constrained environments.

Python data, ETL, analysis, and scientific workflows with maintainable module boundaries and explicit validation at ingress points. Activates on pandas, numpy, scipy, jupyter, notebooks, ETL pipelines, tabular data ingestion, or scientific processing code.

Configure pyproject.toml and Python packaging for distribution. Use when setting up a new Python package, when configuring build tools and dependencies, or when preparing a project for PyPI publishing.

Set up CI/CD pipeline for Python package publishing to PyPI. Use when preparing to publish a package, when setting up automated releases, or when configuring GitHub Actions or GitLab CI for Python projects.

Python work in constrained, dependency-restricted, or legacy environments. Activates on "stdlib-only", "airgapped", "no dependencies", "no internet", "restricted environment", or confirmed Python 3.10 targets where third-party packages are prohibited.

Test-driven development workflow for Python. Activates on "TDD", "write tests first", "red-green-refactor", or tasks requiring test-first implementation with pytest. Guides design-first interfaces, failing tests, and implementation to pass.

Use when designing pytest test suite architecture, planning test coverage strategy, or reviewing test structure for Python 3.11+ projects. Activates on "design a test strategy", "plan test coverage", "create test architecture", or when TDD/BDD/property-based testing patterns are mentioned. Guides fixture design, parametrization, async testing, and mutation testing coverage decisions.

Python testing patterns with pytest, pytest-mock, hypothesis, and coverage strategy. Load when writing tests, designing fixtures, or setting up coverage. Activated on test phases, parametrization, async testing, property-based testing, and mutation testing decisions.

Python tooling expertise for uv, Hatchling, ty type checker, pre-commit, TOML editing, and PyPI packaging. Activates on uv commands, pyproject.toml configuration, type checker setup, build system, git hooks, packaging, or release workflows.

Selects and applies the strongest valid Python typing strategy for the current project. Use when designing models, validating external data, addressing type checker failures, reducing Any usage, defining boundaries, or choosing between stdlib typing, Pydantic, and Hypothesis-based boundary testing.

Python web and API development with strong request boundaries, typed validation, and maintainable service design. Activates on FastAPI, Starlette, Django, Flask, HTTP endpoints, request models, authentication flows, or web framework tasks.

Use when reviewing Python changes for design quality, typed-boundary compliance, testing adequacy, and maintainability. Invoke for code review, PR review, or quality assessment.

Validate Python shebangs and PEP 723 inline script metadata. Use when checking if Python files have correct shebangs based on their dependency requirements, when fixing incorrect shebang patterns, or when adding PEP 723 script blocks to standalone scripts with external dependencies.

Implementation phase for stinkysnake workflow. Use when tests are written and plan is ready. Implements functions following the modernization plan, runs tests until passing.

Use as the routing layer for Python engineering tasks — matches task descriptions against trigger lists and activates specialist skills before starting work. Covers Typer, Rich, Textual, FastMCP/MCP, ty type checker, uv, Hatchling, TOML editing, pre-commit/prek, async Python, PyPI packaging, complex linting, technical debt modernization, testing, feature workflows, and stdlib scripting.

Progressive Python quality improvement with static analysis, type refinement, modernization planning, plan review, and test-driven implementation. Use when addressing technical debt, eliminating Any types, applying modern Python patterns, or refactoring for better design.

Use when encountering failing tests, diagnosing test errors, or establishing a systematic approach to test failure investigation. Activates on "test failure analysis", "debugging tests", or "why tests fail" requests. Establishes the mindset that treats test failures as valuable diagnostic signals requiring root-cause investigation — not automatic code fixes or test dismissal.

Use when building Textual TUI apps — creating widgets, laying out screens, handling events, managing reactivity, testing with Pilot, or running background workers. Covers App lifecycle, CSS styling, screen stack, reactive attributes, custom messages, actions, bindings, and the Worker API.

Use when reading or writing pyproject.toml or .toml config files in Python, editing TOML while preserving comments and formatting, designing configuration file formats for Python tools, working with tomlkit or tomllib, or implementing atomic config file updates.

Use when working with ty — running Python type checks, configuring ty.toml or pyproject.toml, suppressing diagnostics, interpreting error codes, targeting Python versions, or integrating ty with editors and CI. Covers CLI flags, configuration schema, rule severity, suppression comments, environment discovery, module resolution, and all installation methods.

Use when building Typer/Rich CLI applications or reviewing existing CLI code for correctness. Activates on requests involving Rich table rendering, console output handling, testing Rich-formatted output, or Typer command wiring. Prevents common AI mistakes — Rich table wrapping in non-TTY contexts, incorrect stderr/stdout separation, and integration pitfalls. Load alongside the typer and rich API reference skills.

Use when building CLI applications with Typer — creating commands, defining arguments and options, composing subcommands, testing with CliRunner, or using advanced features like callbacks and autocompletion. Covers app creation, parameter types, subcommand composition, testing patterns, and output utilities.

Use when working with Astral's uv — managing Python project dependencies, creating PEP 723 scripts, installing tools, managing Python versions, configuring package indexes, or migrating from pip/poetry. Covers project initialization, virtual environments, workspace configuration, and CI/CD integration.