agent-skills

Create a new single-purpose Agent Skill folder that reaches review-ready with a clear trigger, risk-appropriate validation, concise positive and negative examples, and explicit roles for all local files. Use this when asked to draft or scaffold a new Agent Skill for this repository.

Review a review-ready Agent Skill folder for required core files, complexity-gated sections, YAML-body alignment, risk-appropriate validation, concise positive and negative examples, declared local file roles, single responsibility, portability, independence, and explicit trigger clarity. Use this when a skill draft is ready to be approved or sent back for rework.

Provide the canonical structure for a review-ready, portable, single-purpose Agent Skill in this repository, including complexity-gated sections and risk-based validation guidance. Use this when asked for the standard shape of a new skill or when building a new skill manually from a template.

Generate or backfill the minimum v1 spec document set for one explicit `spec-name` using only the local templates, while preserving existing authored content and refusing out-of-scope outputs.

Build one minimal task-specific handoff package for a real subAgent dispatch without carrying unrelated history, registry hints, or workflow reconstruction.

Enforce a strict release gate for PR readiness, version-source synchronization, tagging safety, emergency exceptions, and release repair guidance without bypassing core quality checks.

Route the next allowed role after one explicit subAgent result, or stop, without encoding full workflows, registries, or runtime semantics.

Query step status (pending/done) in plan/<topic>/<topic>.step.md with minimal token cost and explicit blocking when incomplete.

Project the canonical `skills/` library into a caller-specified platform root by running the local CLI in dry-run mode by default and only enabling writes with explicit `--apply` and `--force`.

Design or review public Python function and method signatures for safe defaults, clear parameter ordering, and explicit call-site contracts.

Choose and design general Python async/await code with explicit async boundaries, structured concurrency, and clear cancellation and async-protocol behavior.

Freeze Python async planning decisions before implementation when a topic introduces async boundary, lifecycle, concurrency, failure, or cancellation risk.

Author a review-ready greenfield `blueprint.md` contract for a new or baseline-only Python repository, reusing the locked blueprint v1 schema already consumed by `python-project-init-greenfield`.

Review an authored greenfield `blueprint.md` contract against the locked blueprint v1 schema before `python-project-init-greenfield` execution begins.

Design or review ordinary Python classes with clear public surfaces, disciplined instance state, thin constructors, and limited use of properties and name mangling.

Review Python code quality across typing, lint, readability, error handling, anti-patterns, test quality, and observability. Use this after python-implementation-review has already approved the implementation against the plan.

Choose clear Python comprehensions and know when explicit loops or map/filter are more readable. Use this when drafting or reviewing list, dict, set comprehensions, generator expressions, and readability boundaries.

Choose and design synchronous Python context managers for resource lifetime and temporary state restoration. Use this when drafting or reviewing `with` usage, `@contextmanager` versus class-based design, setup/cleanup failure handling, and ambient-state restoration.

Choose clear general-purpose Python branching patterns. Use this when drafting or reviewing `if/elif`, `match/case`, guard clauses, and truthiness rules.

Choose clear Python data-model methods. Use this when deciding whether an ordinary class should define foundational dunder methods, expose base container protocols, or rely on dataclass-generated behavior.

Choose and design ordinary Python decorators that preserve signature transparency, keep behavior explicit, and avoid hiding lifetime-driven work.

Choose and design Python attribute access mechanisms using the least-powerful-sufficient ladder — from plain attributes through @property, @cached_property, custom descriptors, and attribute hook methods — with strict discouragement of __getattr__, __setattr__, and __getattribute__.

Write clear, contract-first docstrings using Google Style format with explicit intent and boundaries

Design or review general Python exception handling. Use this when choosing custom errors, translation boundaries, chaining, and when failures should propagate.

Choose clear Python iteration patterns. Use this when deciding whether code should return a concrete collection versus a generator, or when designing generator functions, generator expressions, and custom iterator classes.

Review a Python implementation against its approved plan to confirm all Implementation Steps are complete, no scope has crept beyond Non-goals, the Public Contract is unchanged, and the Test Plan cases are present. Run BEFORE python-code-review.

Design or review reusable Python library/package architecture with theme isolation, a side-effect-free `core`, and facade/client composition for multi-theme libraries and SDK-style packages.

Choose the right general-purpose Python construct for structured data and contracts. Use this when drafting or reviewing whether code should use Enum, dataclass, ABC, or Protocol.

Design or review regular Python package and module boundaries with explicit public surfaces, disciplined re-exports, safe imports, and clear internal-module contracts.

Define or normalize Python naming conventions for identifiers, files, folders, and visibility boundaries. Use this when drafting or reviewing Python code style rules centered on names.

Defines Python operator overloading rules for binary arithmetic contracts, reflected operator pairing, in-place return semantics, unary operator purity, comparison ordering consistency, and the NotImplemented dispatch protocol.

Design or review conservative Python package layouts with `src/`, `pyproject.toml`, clear library-vs-CLI placement, and tests that exercise packaged code rather than local-path accidents.

Create an executable Python implementation plan that freezes scope, contracts, decisions, affected files, tests, and validation commands before coding begins. Not a todo list — an implementation contract that executor can follow and reviewer can verify.

Review a Python *.plan.md for executability — verifying all 13 required sections, decision completeness, explicit async trigger or exemption citation, async-planning coverage when triggered, step precision, test specificity, and validation coverage before implementation begins.

Configures pre-commit hooks for uv-based Python projects by producing a valid `.pre-commit-config.yaml` with the canonical hook set. Use this when a uv Python project needs pre-commit setup or an existing config needs hooks merged in.

Create a governed Python project baseline from a locked `blueprint.md` contract. Use this when a greenfield repository needs its first uv-aligned structure, copied Agent Skills, and a closed acceptance handoff through the canonical `sense-env-scaffold` CLI path.

Retrofit an existing Python repository from a locked Retrofit V2 `retrofit-plan.md`, with risk-alignment blocking, mandatory human gates, destructive preview for HIGH-risk plans, and acceptance handoff through `sense_env.py`.

Append missing ruff, pyright, and pytest configuration sections to an existing pyproject.toml without overwriting existing settings.

Author a review-ready Retrofit V2 `retrofit-plan.md` for an existing Python repository, with locked section order, machine-readable migration risk metadata, and strict separation between planning strategy and runtime gate decisions.

Review an authored Retrofit V2 `retrofit-plan.md` contract against the locked section order, machine-readable risk metadata, supported sensing assertion kinds, authoring-versus-executor boundaries, and locatability before `python-project-retrofit` execution begins.