Skills/python-dev/SKILL.md

name, description, version, user-invocable

name	description	version	user-invocable
python-dev	Apply this skill whenever writing, editing, generating, or reviewing Python code. Favor small, typed, idiomatic changes that fit the existing codebase and finish with lint, type checks, and relevant tests passing. Use `REFERENCE.md` only when deeper guidance is needed.	3.1.0	false

Python Development

Use this skill for any task that creates or changes Python code.

Operating Mode

• Match the repository's existing style and architecture before introducing new patterns.
• Prefer the smallest correct change over broad refactors.
• Keep code easy to read: flat control flow, clear names, limited indirection.
• Do not force framework choices or house style upgrades into unrelated work.
• Do not add compatibility layers, feature flags, or speculative abstractions unless required.
• If an API or library detail is uncertain, check current docs before coding.

Defaults

• Add from __future__ import annotations to new Python modules.
• Fully annotate public functions and important variables.
• Prefer precise types over broad ones.
• Use X | Y and X | None syntax.
• Avoid Any; if unavoidable, keep it narrow and explain why.
• Use TYPE_CHECKING for type-only imports when it improves runtime imports or avoids cycles.
• Prefer simple functions and dataclasses unless the codebase clearly wants a heavier OO design.
• Use classes for durable domain concepts or stateful collaborators, not by default.
• Prefer composition over inheritance.
• Keep responsibilities separated: domain logic, data access, and interface code should stay distinct.
• Do not place business logic directly in route handlers, CLI commands, or persistence code.
• Validate untrusted input at the boundary.
• Prefer Pydantic for external input, config, or data crossing trust boundaries.
• Prefer @dataclass(slots=True) for internal structured data.
• Use frozen=True when immutability is a natural fit.
• Prefer pathlib over os.path.
• Prefer f-strings.
• Prefer standard idioms like comprehensions, enumerate, zip, and context managers where appropriate.
• Use guard clauses to reduce nesting.
• Avoid mutable default arguments, bare except:, and type(x) == T checks.

Error Handling

• Raise specific exceptions with useful messages.
• Keep try blocks narrow.
• Preserve context with raise ... from exc when re-raising.
• Do not swallow exceptions silently.
• Log at system boundaries or orchestration layers, not deep inside pure domain logic.

Async

• Use async only for real I/O-bound workflows.
• Do not call blocking I/O directly from coroutines.
• Keep sync and async boundaries explicit.

Security

• Never hardcode secrets, tokens, or credentials.
• Validate external input before using it.
• Avoid dangerous calls unless explicitly justified: eval, exec, pickle.loads, yaml.load, shell=True, os.system.
• Do not build shell commands from raw user input.
• Avoid logging secrets or sensitive user data.

Testing

• Add or update tests for behavior you change.
• Prefer unit tests for pure logic and integration tests for persistence or external boundaries.
• Use parametrization to cover multiple cases succinctly.
• Mock at external boundaries, not inside the core logic under test, unless the repo uses a different testing style.

Tooling

• Use uv for Python dependency and tool execution when the project uses it.
• Run formatters, linters, and type checks after Python changes.
• Default verification flow: format, lint, type-check, then run relevant tests.
• If the repo uses different commands, follow the repo.

Completion Checklist

Before finishing Python work, make sure:

• the change matches existing project patterns
• code is fully typed to the repo's standard
• untrusted input is validated at the boundary
• logic is kept in the right layer
• ruff is clean
• mypy is clean
• relevant tests pass
• no secrets or risky calls were introduced without justification

Reference

See REFERENCE.md for optional deeper guidance on typing, architecture, async patterns, testing, security, and review heuristics.