Python Conventions Skills

A CLAUDE.md for modern Python (3.11+) conventions — type discipline, pathlib over os.path, async patterns, structlog, ruff + mypy strict + pytest defaults. Drop into any Python project.

Stars License Last Commit Claude Code

A single CLAUDE.md for modern Python (3.11+) conventions. Type discipline, pathlib over os.path, async patterns, structlog, ruff + mypy strict + pytest defaults. Drop into any Python project.

Full content: CLAUDE.md. Code-level before/after: EXAMPLES.md.

curl -o CLAUDE.md https://raw.githubusercontent.com/HermeticOrmus/python-conventions-skills/main/CLAUDE.md

The same content as an installable skill: skills/python-conventions/.

See CURSOR.md. Rule at .cursor/rules/python-conventions.mdc.

Modern Python (3.11+) has cleaner idioms than older Python: native union syntax (A | B), match statements, TaskGroup, tomllib, faster startup. AI-generated Python often defaults to older idioms (Union[A, B], os.path, time.sleep in async code) because the training corpus is heavy on legacy code.

This file overrides the defaults with modern conventions.

• uv over pip. uv is ×ばつ faster for resolution, has built-in lockfiles, and matches the workflow that most new projects are converging on.
• ruff over black + flake8 + isort. One tool, faster, fewer config files, same outputs.
• mypy --strict. Some teams prefer pyright; the rules here apply to either. Strict mode is the point — # type: ignore should be rare.
• Pydantic v2 for I/O. v1 → v2 has breaking changes; this file presumes v2. For v1 codebases, the patterns still apply with v1 syntax.

If your project disagrees with any of these defaults, override at the project level. The CLAUDE.md is a baseline, not a religion.

• typescript-conventions-skills — sister repo for TypeScript
• shell-safety-skills — companion for bash scripts
• andrej-karpathy-skills — general coding discipline
• PEP 8 — the canonical style guide
• Hypermodern Python — longer-form modern Python setup

PRs welcome — especially Django-specific patterns, FastAPI patterns, data-science patterns (numpy/pandas/polars), and ML-specific patterns (PyTorch, JAX).

MIT.

This repository is part of a growing family of open-source toolkits for Claude Code.

• LibreUIUX-Claude-Code — UI/UX development (152 agents, 70 plugins, 76 commands, 74 skills)
• LibreArch-Claude-Code — Software architecture and system design
• LibreCopy-Claude-Code — Technical writing and documentation engineering
• LibreDevOps-Claude-Code — DevOps engineering and infrastructure automation
• LibreEmbed-Claude-Code — Embedded systems, firmware, and IoT development
• LibreFinTech-Claude-Code — Financial technology development
• LibreGEO-Claude-Code — AI-search optimization (ChatGPT, Perplexity, Gemini, Google AI Overviews)
• LibreGameDev-Claude-Code — Game development across Godot, Unity, Unreal
• LibreMLOps-Claude-Code — ML engineering and AI operations
• LibreMobileDev-Claude-Code — Mobile app development (Flutter, React Native, native iOS, native Android)
• LibreSecOps-Claude-Code — Security operations
• LibreSessionFlow-Claude-Code — Session lifecycle: handoff, pickup, absorb, explore, close

• vibe-engineer-skills — Direct AI codegen well: hypothesis before help, scoped prompts, validate before accepting
• markdown-discipline-skills — Strip AI-slop from markdown (no em dashes, no marketing fluff)
• shell-safety-skills — set -euo pipefail discipline plus 15 failure-mode examples
• commit-standard-skills — Ormus Commit Standard v1.0 plus commit-msg hook and commitlint
• unwoke-skills — Strip AI theater (ten sins to eliminate, symmetric engagement)
• typescript-conventions-skills — TypeScript strict mode, discriminated unions, Result types
• hermetic-laws-skills — Seven Hermetic Principles applied to engineering
• riper-workflow-skills — Research / Innovate / Plan / Execute / Review systematic dev
• six-day-cycle-skills — Sustainable shipping cadence with mandatory rest
• token-optimization-skills — Claude Code token and context optimization
• osint-skills — OSINT research methodology (multi-wave investigative spiral)
• calcinate-skills — Stage 1 of the Magnum Opus (burn project bloat)
• claude-md-overhaul-skills — Audit CLAUDE.md and MEMORY.md against caps
• session-handoff-skills — Session handoff and pickup discipline
• naming-skills — Product naming methodology (mine the brand's vocabulary)
• magnum-opus-skills — Seven-stage alchemy applied to project transformation
• mem-search-skills — Search claude-mem cross-session memory: search, filter, fetch
• hypothesis-debugging-skills — Hypothesis-driven debugging: reproduce, isolate, test, fix
• vibe-proof-skills — Security hardening for vibe-coded full-stack apps
• tdd-skills — Test-driven development (Red-Green-Refactor) for JS/TS and Python
• mars-skills — Production-readiness audit: the five mortal sins of vibe-coded MVPs
• git-workflow-skills — Clean git workflow: branch, atomic commits, reviewable PRs
• code-review-skills — Domain-aware code review: classify the code, then focus
• code-comprehension-skills — Understand an unfamiliar codebase fast
• dx-audit-skills — Audit developer experience: docs, onboarding, tooling friction
• setup-env-skills — Set up a project's development environment
• automate-skills — Turn repetitive tasks into reliable automation scripts
• quick-fix-skills — Fast troubleshooting for common issues
• prime-context-skills — Prime project context at the start of a session
• auto-docs-skills — Generate and maintain project documentation
• learning-skills — Learn any technology: roadmaps, explanations, practice, cheatsheets, comparisons
• linux-sysadmin-skills — Linux system administration: security, performance, diagnostics, monitoring, maintenance

• andrej-karpathy-skills — the canonical single-file CLAUDE.md pattern (fork of jiayuan_jy's original)

Star the family, not just one — that's how the suite stays coherent.