Python Best Practices
Apply 70 prioritized Python engineering rules when an agent writes, reviews, or refactors your backend and scripts.
Overview
Python Best Practices is a journey-wide agent skill that applies 70 prioritized Python 3.11+ engineering rules whenever a solo builder needs consistent modeling, errors, and style before committing agent-written code.
Install
npx skills add https://github.com/nathan-gage/python-skills --skill python-best-practicesWhat is this skill?
- 70 observational rules across 8 categories prioritized from data modeling through naming and imports
- Each rule pairs incorrect vs correct examples with impact notes for agent pattern-matching
- Baseline assumes Python 3.11+ with explicit callouts when a rule needs 3.13 (e.g. warnings.deprecated)
- Frames matches as signals not automatic verdicts—preferences for new code rather than mass refactors
- Optimized abstract and TOC for AI agents maintaining or generating Python codebases
- 70 rules across 8 categories in version 1.3.0
- Baseline Python 3.11+ with inline notes when 3.13 behavior applies
Adoption & trust: 637 installs on skills.sh; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
Agent-generated Python drifts across types, error handling, and structure because there is no shared, prioritized rule set tuned for automated refactor and review.
Who is it for?
Solo builders using Claude Code or Cursor on Python 3.11+ backends who want agent output checked against a dense, prioritized rule catalog.
Skip if: Greenfield non-Python stacks, learners who only need tutorial pacing, or teams that want automatic mass rewrite of legacy modules against every stylistic preference.
When should I use this skill?
Maintaining, generating, or refactoring Python codebases where consistent patterns for modeling, errors, and imports matter.
What do I get? / Deliverables
After the skill runs, new and touched Python code aligns to categorized best-practice rules with cited patterns, reducing inconsistent APIs and hidden footguns before merge.
- Rule-aligned review or generation notes mapped to the 8 categories
- Incorrect vs correct code guidance for matched rules
- Prioritized fix list emphasizing high-impact data modeling and error-handling rules
Recommended Skills
Journey fit
Useful at every journey phase - explore requirements and options before committing to a direction.
Where it fits
Shape new FastAPI modules with explicit variants and NewType IDs before the first merge.
Run agent review on a PR that touches exception handling and mutable shared state.
Patch a production script under incident pressure without reintroducing dead variants or leaky globals.
Keep throwaway Python prototypes readable enough to promote into the main repo.
Maintain internal Python tooling that powers content or analytics jobs with consistent patterns.
How it compares
Use this procedural Python rule pack instead of asking the model for generic PEP-8 advice without prioritized data-modeling and error-handling guidance.
Common Questions / FAQ
Who is python-best-practices for?
It is for indie developers and agent-assisted maintainers of Python 3.11+ codebases who want consistent modeling, error handling, and naming when LLMs write or refactor code.
When should I use python-best-practices?
Use it during Build when authoring backends, during Ship review before merging risky Python changes, and during Operate when patching production scripts—whenever agent-written Python needs a shared quality bar.
Is python-best-practices safe to install?
Review the Security Audits panel on this Prism page; the skill is documentation-driven and does not inherently require network access, but grant filesystem scope only to repos you trust.
SKILL.md
READMESKILL.md - Python Best Practices
# Python Best Practices **Version 1.3.0** Python Best Practices April 2026 > **Note:** > This document is optimized for AI agents and LLMs that maintain, generate, > or refactor Python codebases. Humans may also find it useful, but the > guidance, examples, and framing prioritize consistency and pattern-matching > for AI-assisted workflows. --- ## Abstract Python software engineering guidelines for agent consumption. 70 rules across 8 categories, prioritized by impact from data modeling and error handling down to naming and import hygiene. Each rule is observational — it describes the pattern and what it costs, shows incorrect and correct code, and cites primary sources where the rule depends on language or library behavior. Rules assume Python 3.11+ as a baseline; rules depending on a higher version (e.g., 3.13 for warnings.deprecated) are called out inline. A rule match is a signal, not a verdict: most rules are design preferences for new code rather than bugs to fix across the repo. --- ## Table of Contents 1. [Data Modeling](#1-data-modeling) — **HIGH** - 1.1 [Brand Primitive IDs With NewType](#11-brand-primitive-ids-with-newtype) - 1.2 [Create Explicit Variants Instead of Mode Flags](#12-create-explicit-variants-instead-of-mode-flags) - 1.3 [Delete Dead Variants](#13-delete-dead-variants) - 1.4 [Derive, Don't Store](#14-derive-dont-store) - 1.5 [Encapsulate Mutable State in the Narrowest Clear Scope](#15-encapsulate-mutable-state-in-the-narrowest-clear-scope) - 1.6 [Never Use Mutable Default Arguments](#16-never-use-mutable-default-arguments) - 1.7 [Phase Related Optional Fields Into Nested Structs](#17-phase-related-optional-fields-into-nested-structs) - 1.8 [Pick a Mutation Contract](#18-pick-a-mutation-contract) - 1.9 [Use Discriminated Unions Over Optional Bags](#19-use-discriminated-unions-over-optional-bags) - 1.10 [Use Timezone-Aware Datetimes at Boundaries](#110-use-timezone-aware-datetimes-at-boundaries) - 1.11 [Use a Sentinel Object When None Is a Real Domain Value](#111-use-a-sentinel-object-when-none-is-a-real-domain-value) 2. [Error Handling](#2-error-handling) — **MEDIUM-HIGH** - 2.1 [Catch Specific Exception Types](#21-catch-specific-exception-types) - 2.2 [Consolidate try/except Blocks with the Same Handler](#22-consolidate-tryexcept-blocks-with-the-same-handler) - 2.3 [Inherit New Exceptions from Existing Base Exceptions](#23-inherit-new-exceptions-from-existing-base-exceptions) - 2.4 [Preserve Tracebacks When Logging Exceptions](#24-preserve-tracebacks-when-logging-exceptions) - 2.5 [Trust Validated State Within the Same Trust Domain](#25-trust-validated-state-within-the-same-trust-domain) - 2.6 [Use !r Format for Identifiers in Error Messages](#26-use-r-format-for-identifiers-in-error-messages) - 2.7 [Use assert Only for Debug-Only Internal Invariants](#27-use-assert-only-for-debug-only-internal-invariants) - 2.8 [Use assert_never for Exhaustiveness Checks](#28-use-assertnever-for-exhaustiveness-checks) - 2.9 [Use raise ... from to Preserve Exception Causality](#29-use-raise-from-to-preserve-exception-causality) - 2.10 [Use with / async with for Resource Lifetimes](#210-use-with-async-with-for-resource-lifetimes) - 2.11 [Validate Input at System Boundaries](#211-validate-input-at-system-boundaries) 3. [Type Safety](#3-type-safety) — **MEDIUM-HIGH** - 3.1 [Avoid Any Annotations](#31-avoid-any-annotations) - 3.2 [Fix Type Definitions Instead of cast()](#32-fix-type-definitions-instead-of-cast) - 3.3 [Fix Type Errors, Don't Ignore Them](#33-fix-type-errors-dont-ignore-them) - 3.4 [Narrow Type Signatures to Runtime Reality](#34-narrow-type-signatures-to-runtime-reality) - 3.5 [Remove Redundant `| None` When Values Are Guaranteed](#35-remove-redundant-none-when-values-are-guaranteed) - 3.6 [Trust the Type Checker — Remove Redundant Runtime Checks](#36-trust-the-type-checker-remove-redundant-runtime-checks) - 3.7 [U