Python Engineering

Python Engineering

When to Use

Use this skill when:

• Writing, editing, refactoring, or reviewing Python code of any size, including single-file scripts.
• Creating or restructuring a Python project: layout, pyproject.toml, dependencies, environments, interpreter versions.
• Working Python tooling mechanics: uv, ruff, type checkers, pytest, pre-commit, coverage, build backends, publishing, CI workflows, Docker images for Python.
• Adding or changing configuration/settings, logging, error handling, retries, async code, or performance-sensitive code in Python.
• Answering "how should this be done in modern Python" for any of the topics in the routing table.

Do Not Use

Do not use this skill for the task when:

• The work is not Python.
• The question is test design judgment — what to test, posture, seams, mocks, coverage sufficiency: testing-strategy owns it; this skill supplies pytest mechanics.
• The question is error policy — taxonomy, result envelopes, sanitized messages, redaction, log-level policy: error-handling-design owns it; this skill supplies Python mechanics.
• The question is queue/job/cache design (idempotency, DLQs, invalidation): queue-and-cache-design. API contracts: api-design. Database schemas, queries, transactions, and migrations: database-design — which carries its own Python SQLAlchemy/Alembic reference; load it alongside this skill for Python DB work. Architecture boundaries and seams: architecture-design.
• Something is broken and the cause is unknown: structured-problem-resolution first — this skill does not diagnose failures.
• The deliverable is reader-facing documentation content or a README: create-documentation / create-readme; this skill supplies docstring and doc-tooling mechanics only.
• Commit/PR mechanics: git-commit / git-pull-request.

When both apply (usual case: a domain skill owns the judgment, this skill owns the Python), load both and keep the boundary.

Iron Law

Baseline first, then the reference that owns the topic. Project conventions beat skill defaults; verified current practice beats training memory.

Do not write Python before the project's baseline (toolchain, floor, conventions) is established, and do not freestyle topic guidance from memory when a reference below owns it — Python practice moves fast enough that trained habits are reliably stale.

Core Concept

Two failure modes dominate agent-written Python: code written before anyone established which stack and conventions govern, and topic decisions (config, logging, retries, packaging…) improvised from stale memory. The counter is a fixed two-step: establish the baseline, then load the owning reference. Five gates below are hard; everything else is judgment inside the references.

Baseline

Modern professional consensus (flagship projects and maintained templates converge on this; verified 2026-07), plus one row explicitly marked house doctrine:

These are the greenfield defaults, not conversion orders — Step 1 decides which applies.

Operating Process

1. Establish The Baseline

Detect before deciding: pyproject.toml ([tool.*], requires-python, build backend), lockfiles (uv.lock/poetry.lock/pdm.lock/Pipfile), configs (.pre-commit-config.yaml, tox.ini/noxfile.py, CI workflows), and the code's existing style.

• Incumbent conventions found → they govern. Use the incumbent's commands (poetry/pdm/pip, black/mypy, etc.) even where this skill's defaults differ.
• Greenfield → the Baseline table governs; load project-setup before scaffolding.
• Improving the incumbent stack (e.g., poetry→uv, black→ruff, adding a type checker) is proposed separately and waits for explicit approval — never bundled into a feature task.

Completion criterion: you can name the manager, floor, layout, package-structure convention, and lint/format/type/test tools that govern this change.

Failure output: Blocked: Python baseline unknown: <missing detection or decision>.

2. Route The Topic

Load only the reference(s) that own the current work — before writing, not after:

No route matches → the work is probably another skill's (see Do Not Use); if it is genuinely Python-mechanical and unrouted, proceed with the Baseline plus general judgment and say so.

Completion criterion: the owning reference(s) are loaded, or the no-route case is declared.

3. Apply With Gates

The five hard gates, in force during all execution:

1. Baseline gate (Step 1) — no Python written before the baseline is established.
2. Migration-approval gate — toolchain, stack, or package-structure conversions of an existing project require an explicit, separately-approved proposal. Failure output: Blocked: migration needs explicit approval: <proposal>.
3. Safety gate — no blocked construct from the security table (untrusted pickle/yaml.load/eval/exec, shell=True with interpolation, string-built SQL, disabled TLS, mktemp, random-for-secrets, unguarded extraction/paths, hardcoded secrets) without named justification and explicit user approval; offer the safe alternative first. "It's internal" is not an exemption. Failure output: Rejected: unsafe construct without approval: <construct> — safe alternative: <alternative>.
4. Measure-before-optimize gate — performance changes require profile/benchmark evidence before and after (performance); regression reports go to structured-problem-resolution first. Failure output: Rejected: optimization without measurement evidence: profile or benchmark required first.
5. Verification gate — Step 4; done is gate-clean, and gates are never weakened to pass.

Doctrine–authority collisions. This skill's doctrines sometimes require an action that a project or global rule gates behind approval — most commonly a new dependency (a retry library, pydantic-settings, PyYAML) or anything under gate 2. Specificity does not transfer the decision right: the skill's doctrine decides the recommendation, the approval rule decides the process. Surface the collision as an explicit decision with the doctrine-compliant option recommended and its trade-offs stated. Both silent resolutions are wrong: do not add the dependency without approval, and do not quietly build a hand-rolled workaround to avoid the conversation. If approval is declined, implement the closest doctrine-compliant alternative without the gated action (bounded, jittered, single-layer retries via stdlib or an already-present library, and so on) and name the accepted trade-off.

4. Verify

Run the project's gates before claiming done: lint (ruff check), format check, type check, tests — via the incumbent toolchain's commands. Report what ran and what it showed; anything unavailable is reported as skipped with the reason, not silently passed.

Never weaken to get green: no rule downgrades, family removals, blanket noqa/type-ignores, assertion dilution, test skips, or snapshot refreshes to force a pass — surface the finding and let the user decide.

Completion criterion: gate results (or named skips) are in the final report.

Failure output: Not done: quality gate failing: <gate and finding>.

Rationalization Table

Red Flags

• Python written before the baseline was established, or defaults applied over detected incumbents.
• pip install into a uv project; hand-edited requirements.txt as source of truth; setup.py in a new project.
• Scattered os.environ.get() at use sites; secrets in code, logs, or fixtures.
• print() diagnostics or basicConfig() in library code.
• Bare except:/except Exception: pass; retry loops around retry loops; external calls without timeouts.
• Fire-and-forget create_task; blocking calls inside coroutines.
• # noqa/# type: ignore without codes and reasons; rules loosened to get green.
• Unprofiled "optimizations"; async conversion for CPU-bound code.
• A blocked security construct used because the user's snippet or instruction contained it, without the gate firing.
• A doctrine-required dependency silently added, or silently worked around, instead of surfaced as a decision.
• Claims of done without gate results.

Output Contract

When completing Python work under this skill, report:

Baseline: <incumbent|greenfield> — <manager, floor, lint/type/test tools>
References loaded: <list>
Gates: <fired/passed, with any approvals obtained>
Verification: <commands run and decisive results, or named skips with reasons>
Residual risk / follow-ups: <or none>

Maintenance

Fast-moving claims in the references carry verified-as-of dates and per-reference re-verify blocks. When any claim is found stale, update the claim and its date together. When repo skills that this skill routes to are renamed or re-scoped, update Do Not Use and the boundary headers in the references together.