Specialist Skill Routing

Scan your task description against the triggers below. For every match, call Skill(skill="...") before writing any architecture, plan, or code. Multiple matches → load all matching skills.

CLI Framework — Typer

Triggers: typer.Typer(), typer.run(), @app.command, @app.callback, typer.Option, typer.Argument, Annotated[int, typer.Option()], Typer subcommands, app.add_typer(), CliRunner, typer.echo, typer.style, typer.secho, typer.Exit, typer.Abort, typer.confirm, typer.launch, autocompletion

Skill(skill="python-engineering:typer")

Covers: app creation with typer.Typer() and typer.run(), CLI arguments and options (Annotated form), parameter types (enums, paths, dates, UUIDs, custom), subcommand composition with add_typer(), testing with typer.testing.CliRunner, output/colors/progress bars, callbacks, context, autocompletion, packaging.

Terminal UI — Rich

Triggers: rich.console.Console, rich.table.Table, rich.progress.track, rich.progress.Progress, rich.panel.Panel, rich.tree.Tree, rich.live.Live, rich.syntax.Syntax, rich.markdown.Markdown, rich.logging.RichHandler, rich.traceback.install, rich.print, Rich markup tags, rich.columns.Columns, rich.layout.Layout, rich.json.JSON, rich.pretty.pprint, __rich_console__, __rich__, __rich_repr__

Skill(skill="python-engineering:python3-cli")

Covers: Console class and markup syntax, style strings and color formats, renderables (Panel, Table, Tree, Columns, Layout), Progress and Live displays, Text class, Syntax/Markdown/Pretty/JSON rendering, RichHandler for stdlib logging, Traceback installation, __rich_console__ and __rich_repr__ protocols, RegexHighlighter.

TUI Framework — Textual

Triggers: textual.app.App, textual.widget.Widget, textual.screen.Screen, ComposeResult, compose(), mount(), query(), query_one(), textual.reactive.reactive, textual.css, @on, @work, run_worker, run_test, Textual CSS, Textual events, Textual workers, pytest-textual-snapshot

Skill(skill="python-engineering:textual")

Covers: App lifecycle (run/exit/suspend), screen stack (push/pop/switch/modes), custom and builtin widgets, Line API, layout types (vertical/horizontal/grid), CSS selectors and pseudo-classes, events and message bubbling, custom messages, actions and key bindings, reactive attributes (watch/validate/compute/data binding), testing with Pilot API, snapshot testing, Workers and @work decorator.

Typer + Rich Best Practices

Triggers: non-TTY output handling, table width measurement, Rich output in CI/piped environments, testing Rich-formatted CLI output, Console(force_terminal=True), Console(width=N), Console(file=StringIO()), console.capture(), export_text()

Skill(skill="python-engineering:typer-and-rich")

Covers: non-TTY Console behavior (width defaults, color stripping, environment variables), Measurement protocol for renderable width, Progress/Live without TTY, testing Rich output in pytest (capture, export, snapshot), CliRunner with Rich, common assertion mistakes.

CLI UI/UX Design — 7-Stage Workflow

Triggers — before implementation: designing CLI user experience, CLI display patterns, output consistency across commands, user-facing output design, CLI information architecture, shape brief, register decision (brand-cli vs product-cli), PRODUCT.md interview, DESIGN.TUI.md setup

Triggers — during implementation: questionary, questionary.select, questionary.text, questionary.confirm, questionary.checkbox, questionary.prompt, interactive prompts, progress bars, spinners, status indicators, tables, panels, dashboard layout, splash screens, animated welcome sequences, PyFiglet banners

Triggers — evaluation and post-implementation: CLI UX review, critique of existing CLI display code, UX heuristic evaluation, AI-slop check, accessibility review (NO_COLOR, non-TTY fallback, colour-blind safety), pre-ship polish pass, terminal-emulator portability check, column-alignment verification

Skill(skill="python-engineering:designing-ui-for-cli")

Load before writing display/output/interaction code AND before declaring display work done. Runs a 7-stage discipline: Context → Register → Shape brief (user-confirmed gate) → Implement → Critique (Nielsen /40 + AI-slop) → Audit (P0–P3 severity) → Polish (22-item checklist). Any P0 audit finding blocks ship.

Covers: per-project design system contracts (PRODUCT.md, DESIGN.TUI.md), colour strategy (Restrained → Drenched), theme via scene-sentence method, register-specific permissions and bans, shape brief with confirmation gate, Nielsen heuristic critique, 5-dimension audit, 22-item polish checklist, Textual/Rich/Typer/Questionary/PyFiglet patterns.

MCP / FastMCP

Triggers: building an MCP server, FastMCP(), @mcp.tool, @mcp.resource, MCP tools/resources/prompts, MCP transports (stdio/HTTP/SSE), server composition (mount()), MCP auth, MCP client, deploying an MCP server, migrating from FastMCP v2

Skill(skill="fastmcp-creator:fastmcp-creator")

Also activate for:

• Writing tests for an MCP server → Skill(skill="fastmcp-creator:fastmcp-python-tests")
• Using fastmcp list / fastmcp call / fastmcp discover CLI → Skill(skill="fastmcp-creator:fastmcp-client-cli")

After loading, follow the trigger matrix inside that skill to load only the reference files relevant to your specific task.

Type Checking — ty

Triggers: ty check, ty.toml, [tool.ty] in pyproject.toml, suppressing ty diagnostics, ty rule names and severity levels, ty environment/module resolution, unresolved imports in ty, migrating from mypy or pyright to ty, integrating ty with editors or CI

Skill(skill="python-engineering:ty")

Covers: CLI flags, configuration schema, rule levels (error/warn/ignore), suppression comments (ty: ignore, type: ignore), virtual environment discovery, Python version targeting, installation, VS Code/Neovim/Zed/PyCharm integration, troubleshooting.

Does NOT cover: deep mypy or pyright configuration (follow the project's pyproject.toml when the repo already uses those tools — do not force ty). For annotation patterns shared across checkers, see python3-typing skill. Does not replace a dedicated typing tutorial for writing annotations from scratch.

Package Management — uv

Triggers: uv add, uv run, uv build, uv publish, uv sync, uv lock, uvx, PEP 723 inline script metadata, managing Python versions with uv, configuring package indexes or private registries, workspace configuration ([tool.uv.workspace]), migrating from pip/poetry/conda, CI/CD with astral-sh/setup-uv, Docker with uv, uv venv, dependency groups, uv tool install

Skill(skill="python-engineering:uv")

Key facts — do not guess these from training data:

• uv venv refuses to overwrite existing environments since 0.10.0 — pass --clear
• Use uv run not source .venv/bin/activate
• Use uv add not uv pip install for project dependencies
• uv sync --frozen for CI; uv sync --locked to fail if lockfile is stale
• PEP 723 shebang: #!/usr/bin/env -S uv --quiet run --active --script

Build Backend — Hatchling

Triggers: [build-system] using hatchling, hatch_build.py, [tool.hatchling], wheel/sdist configuration, build hooks, hatch-vcs version management, force-include patterns, editable installs with hatchling, setuptools migration to hatchling

Skill(skill="python-engineering:hatchling")

Covers: PEP 517/518/621/660, project metadata, wheel and sdist targets, build hooks interface, version sources, file selection with glob patterns, VCS integration, plugin architecture.

TOML Editing (comment-preserving)

Triggers: Python code that reads AND writes pyproject.toml or any .toml file, preserving comments and formatting during modification, tomlkit library, atomic config file updates

Skill(skill="python-engineering:toml-python")

Use tomlkit (not tomllib) when writing or modifying TOML. tomllib is stdlib but read-only. Always open files in text mode ('r'/'w'), not binary.

Pre-commit / prek Git Hooks

Triggers: .pre-commit-config.yaml, prek install, pre-commit install, adding or modifying git hooks, prepare-commit-msg hooks, distributing a tool as a pre-commit hook, detecting which hook tool is installed

Skill(skill="python-engineering:pre-commit")

Key fact: prek is a drop-in Rust replacement for pre-commit — same config file, identical CLI. Detect which is installed by reading .git/hooks/pre-commit line 2.

Async / Concurrent Python

Triggers: asyncio, async def, await, concurrent I/O operations, aiohttp, anyio, trio, WebSocket servers, async background tasks, async queues, async database access, concurrent HTTP requests, async FastAPI

Skill(skill="python-engineering:async-python-patterns")

PyPI Packaging

Triggers: configuring pyproject.toml for distribution, preparing a package for PyPI, entry points, optional dependencies, PEP 517/518/621

Skill(skill="python-engineering:python3-packaging")

For CI/CD pipeline to automate PyPI publishing (GitHub Actions or GitLab CI):

Skill(skill="python-engineering:python3-publish-release-pipeline")

For README files that render correctly on PyPI (twine check, Markdown vs RST choice, readme field in pyproject.toml):

Skill(skill="python-engineering:pypi-readme-creator")

Complex Linting Resolution

Triggers: more than 3 ruff/mypy/basedpyright/pyright errors requiring root-cause analysis, type flow analysis across multiple files, deciding whether to suppress vs fix a diagnostic, linting errors you cannot resolve with standard patterns

Skill(skill="holistic-linting:holistic-linting")

This skill behaves differently for orchestrators vs sub-agents. Orchestrators delegate to linting-root-cause-resolver agent; sub-agents run formatters and linters directly on touched files before completing.

Technical Debt / Modernization

Triggers: eliminating Any types across a module, removing legacy typing imports (Optional[X], Union[X, Y], List[X], Dict[K, V]), refactoring for Protocol usage, progressive quality improvement across multiple files

Skill(skill="python-engineering:stinkysnake")

Multi-phase workflow: static analysis → type analysis → modernization planning → plan review → test-driven implementation. Load before planning a refactor, not mid-implementation.

Triggers: applying modern Python 3.11+ patterns, learning about PEPs (585, 604, 695), finding modern alternatives for old code

Skill(skill="python-engineering:modernpython")

Script Execution & Shebangs

Triggers: validating script shebangs, PEP 723 inline metadata, creating standalone executable Python scripts

Skill(skill="python-engineering:shebangpython")

Stdlib-Only / Restricted Environment Scripts

Triggers: writing Python scripts with no external dependencies, restricted environment scripting, refactoring a script from third-party libraries to stdlib-only

Skill(skill="python-engineering:python3-stdlib-only")

Development Workflows

Triggers: creating a structured feature development task, setting up feature tracking

Skill(skill="python-engineering:create-feature-task")

Triggers: guided feature addition with acceptance criteria, TDD workflow, MoSCoW prioritization

Skill(skill="python-engineering:python3-add-feature")

Implementation & Refactoring Loop

Triggers: implementing functions following a modernization plan, running tests iteratively until passing, executing the implementation phase of a refactor

Skill(skill="python-engineering:snakepolish")

Code Review & Quality Audits

Triggers: reviewing Python code for quality issues, auditing code before merge, checking pattern compliance, verifying architecture standards

Skill(skill="python-engineering:review")

Note: If you are an orchestrator reviewing a completed feature, use the code-reviewer agent instead.

Testing & Coverage

Triggers: auditing test quality, reviewing test coverage, checking for missing edge cases

Skill(skill="python-engineering:comprehensive-test-review")

Triggers: investigating failing tests, debugging test failures, analyzing pytest output

Skill(skill="python-engineering:analyze-test-failures")

Triggers: designing test architecture, test pyramid strategy, fixture hierarchy, mutation testing

Skill(skill="python-engineering:python3-test-design")

Triggers: determining whether a test failure is a bug or test implementation issue, dual-hypothesis investigation

Skill(skill="python-engineering:test-failure-mindset")

Agent Routing (For Orchestrators)

If you are an orchestrator agent, delegate to these specialized agents based on the task phase:

• Architecture/Planning: Agent(subagent_type="python-engineering:python-cli-design-spec")
• Writing Tests: Agent(subagent_type="python-engineering:python-pytest-architect")
• Implementation: Agent(subagent_type="python-engineering:python-cli-architect")
• Post-Implementation Review: Agent(subagent_type="python-engineering:code-reviewer")