Python Best Practices Skill

An AI coding agent skill that enforces idiomatic, clean, and maintainable Python code based on PEP 8, PEP 20, and community best practices.

Core Principles

1. Explicit over implicit — PEP 20: prefer clarity and directness
2. Readability counts — PEP 20: code is read far more than it is written
3. Fix issues as discovered — don't leave TODOs when the fix is clear now
4. Human-Driven Development — write code for humans first, machines second
5. Test ruthlessly — strive for 100% coverage, but don't obsess over the score

Available Patterns

Topic	File
Naming conventions	patterns/naming.md
Style and formatting	patterns/style.md
Imports and structure	patterns/imports.md
Documentation and comments	patterns/documentation.md
Testing patterns	patterns/testing.md
Idiomatic patterns	patterns/idiomatic.md
Pygame best practices	patterns/pygame.md

Installation

Copy this skill directory to your skills folder:

cp -r python-best-practices-skill/ ~/.agents/skills/python-best-practices/

Or symlink it:

ln -s $(pwd) ~/.agents/skills/python-best-practices

Usage

This skill is automatically loaded by most AI coding agents when working with Python code. It provides guidelines for:

• Naming: PEP 8 naming conventions for variables, functions, classes, constants
• Style: Indentation, line length, whitespace, equality checks
• Imports: Ordering, module vs symbol imports, avoiding wildcards
• Documentation: Docstrings (PEP 257), block comments, inline comments
• Testing: Unit tests, functional tests, coverage patterns
• Idiomatic patterns: Comprehensions, context managers, dataclasses, type hints
• Pygame: Delta time, sprite groups, collision detection, state machines, asset caching

Sources

• PEP 8 — Style Guide for Python Code
• PEP 20 — The Zen of Python
• PEP 257 — Docstring Conventions
• PEP 484 — Type Hints
• Pygame community best practices