Python software engineering guidelines from real PR review patterns. This skill should be used when writing, reviewing, or refactoring Python code — especially dataclasses, service interfaces, error handling, and type annotations. Triggers on tasks involving Python modules, API design, data modeling, type safety, exception handling, or refactoring for maintainability. For asyncio and concurrency guidance, see the python-async-best-practices skill.
Intro in this page language first. The official description stays in its original wording; we do not rewrite SKILL.md.
What it does
Python software engineering guidelines from real PR review patterns. This skill should be used when writing, reviewing, or refactoring Python code — especially dataclasses, service interfaces, error handling, and type annotations. Triggers on tasks involving Python modules, API design, data modeling, type safety, exception handling, or refactoring for maintainability. For asyncio and concurrency guidance, see the python-async-best-practices skill.
When to use it
The official description does not include a separate “Use when”. Per the spec, agents activate this skill when the task matches keywords in that description.
How agents load it
Per Agent Skills progressive disclosure: name and description load at startup (~100 tokens); the full SKILL.md body loads when the skill activates; scripts/, references/, and assets/ load only as needed. This file's sections: Python Best Practices; When to Apply; Impact Levels; Python Version Baseline; Rule Categories by Priority; Quick Reference.
File analysis
File analysis: instruction-only skill (SKILL.md). The agent loads the full body when activated.
Python Best PracticesWhen to ApplyImpact LevelsPython Version BaselineRule Categories by PriorityQuick ReferenceData Modeling (`data-`)Error Handling (`error-`)Type Safety (`types-`)API Design (`api-`)Code Simplification (`simplify-`)Performance (`perf-`)
Python software engineering guidelines from real PR review patterns. This skill should be used when writing, reviewing, or refactoring Python code — especially dataclasses, service interfaces, error handling, and type annotations. Triggers on tasks involving Python modules, API design, data modeling, type safety, exception handling, or refactoring for maintainability. For asyncio and concurrency guidance, see the python-async-best-practices skill.
License
MIT
DiscoverThe client exposes names and descriptions to the agent.
ActivateYour request or the task context selects the skill and loads its instructions.
Load resourcesReferenced scripts, documentation and assets are used when needed.
Choose the target agent and installation scope, keep referenced package files, then verify the skill appears in the client's catalog.
Ask your Agent to install
Copy these instructions to a compatible agent and confirm the target directory matches your client.
Install the agent skill "python-best-practices" into my project. The full SKILL.md and official description are at https://zicq.com/en/skills/skl-ea18d84c61693501-Python-Best-Practices.html
Save it as .cursor/skills/python-best-practices/SKILL.md or .claude/skills/python-best-practices/SKILL.md and keep the frontmatter name and description exactly as-is.
The CLI lets you choose the agent interactively. The default scope is the project; use -g for user scope. Confirm package availability with the discovery command, then use npx skills list to inspect installed skills.
name: python-best-practices
description: Python software engineering guidelines from real PR review patterns. This skill should be used when writing, reviewing, or refactoring Python code — especially dataclasses, service interfaces, error handling, and type annotations. Triggers on tasks involving Python modules, API design, data modeling, type safety, exception handling, or refactoring for maintainability. For asyncio and concurrency guidance, see the python-async-best-practices skill.
license: MIT
metadata:
author: python-best-practices
version: "1.5.0"
pythonVersion: ">=3.11"
Python Best Practices
Guidelines for writing and reviewing Python. 75 rules across 8 categories, prioritized by impact.
A rule match is a signal, not a verdict. Most rules are design preferences for new code, not bugs to fix across the repo — check the rule's impact level before flagging in review or refactoring stable code.
Quick-reference lines are triggers, not licenses: before applying a rule as a review finding or a transformation, open the rule file and check its counter-signal — the marker-opened paragraph (**When ...** / **Scope:** / **Preserve ...**) saying when NOT to apply it.
When to Apply
Writing new Python modules, functions, classes, or data models
Reviewing code for correctness or type safety
Refactoring patterns in code that's being edited anyway
Avoid applying these rules as a blanket sweep across stable code — the churn rarely pays off.
Impact Levels
CRITICAL — prevents a real bug class (data corruption, swallowed cancellations, insecure defaults). Fix when found.
HIGH — meaningful correctness or maintainability win. Worth fixing in most contexts.
MEDIUM — good practice; clarity or drift prevention. Apply to new code; don't churn stable code.
LOW-MEDIUM / LOW — style or micro-optimizations. Apply opportunistically.
Python Version Baseline
Rules assume Python 3.11+. Rules depending on higher versions call it out inline:
warnings.deprecated() — 3.13+
zoneinfo — 3.9+
Union types in isinstance() — 3.10+
assert_never — 3.11+ (backport via typing_extensions)
PEP 695 type statement and generic syntax — 3.12+ (noted inline in types-modern-syntax)
Rules tagged applicability:pydantic are Pydantic-specific.
data-phased-composition — Group co-present optionals into one nested optional
data-encapsulate-mutable-state — Trap mutable state in the narrowest clear scope
data-sentinel-when-none-is-valid — Private sentinel when None is a meaningful value
data-newtype-for-ids — NewType('UserId', str) so IDs aren't interchangeable
data-delete-dead-variants — Remove union arms that aren't constructed
data-reject-bool-as-int — bool subclasses int; reject it explicitly before numeric checks
Error Handling (error-)
error-specific-exceptions — Catch specific types; never bare except: or except BaseException: (breaks Ctrl-C and async cancellation); except Exception: is cancellation-safe on 3.8+
error-context-managers — with / async with for files, locks, sessions
error-assert-debug-only — assert vanishes under -O; not for runtime contracts
error-validate-at-boundaries — Fail fast at system edges before expensive work
error-trust-validated-state — Trust immutable, locally-constructed state
error-consolidate-try-except — Merge blocks with the same catch and handling
error-assert-never-exhaustiveness — typing.assert_never for exhaustiveness
error-raise-from-for-chains — raise NewErr(...) from original to preserve causality
error-inherit-base-exceptions — New exceptions inherit existing bases for compatibility
error-log-exception-context — logger.exception(...) inside except; keep the traceback in the log
error-repr-in-messages — f"tool {name!r}" for identifiers in error text
error-match-types-not-messages — Classify by exception type and status code, never message substrings
Type Safety (types-)
types-fix-errors-not-ignore — Fix type errors; # type: ignore is a last resort
types-avoid-any — Protocols, TypeVars, unions over Any
types-typeddict-over-dict-any — TypedDict / dataclass when structure is known
types-literal-for-fixed-sets — Literal["a", "b"] for fixed strings
types-fix-types-not-cast — Fix the definition; cast() only when runtime genuinely narrows
types-isinstance-for-narrowing — isinstance() over hasattr / type(x).__name__
types-narrow-to-runtime-reality — Annotations match what control flow actually allows
types-trust-the-checker — Drop runtime checks the types already enforce
types-remove-redundant-optional — Drop | None when values are guaranteed present
types-type-checking-imports — if TYPE_CHECKING: for optional or heavy imports
types-modern-syntax — X | None, list[str]; not Optional / Union / typing.List
types-sequence-over-list-params — Sequence / Mapping for read-only params; list is invariant
API Design (api-)
api-required-before-optional — Required fields before optional (Python enforces this)
api-keyword-only-params — * marker for optional/config params
api-no-boolean-flag-params — Literal / Enum over True, False soup
api-immutable-transforms — Return new collections; don't mutate inputs
api-model-cohesion — Flat models; no duplicate or single-key-wrapped fields
api-underscore-for-private — _prefix for internals; exclude from __all__
api-deprecated-aliases — warnings.deprecated() (3.13+) for renamed APIs
api-no-private-access — Don't reach into _prefixed names from outside the module
api-instance-vs-module-fn — Pick the namespace that matches ownership
Code Simplification (simplify-)
simplify-early-return — Return early; don't nest the happy path
simplify-extract-after-duplication — Second copy is the decision point; third is the safe default
simplify-cached-property — @cached_property on immutable instances; not thread-safe
simplify-comprehensions — Comprehensions over for + .append()
simplify-any-all-builtins — any() / all() over manual flag + break
simplify-fallback-or — x or default when falsy values aren't semantic
simplify-flatten-nested-if — if cond1 and cond2: when no intervening code
simplify-inline-single-use-vars — Drop intermediates used once
simplify-remove-dead-code — Delete commented-out code; git preserves history
Performance (perf-)
perf-set-for-membership — set for repeated in checks
perf-dict-index-over-nested-loops — Build a dict for lookups
perf-lru-cache-pure-fns — functools.lru_cache / functools.cache on pure functions
perf-generator-over-list — Stream with generators when memory or latency matters
perf-combine-iterations — Fuse filter + map into one pass
perf-compile-regex-module-level — Compile static regex at module scope; matters in tight loops