Python Code Review
Run a structured Python review on .py changes covering PEP8, typing, async correctness, and exception patterns before merge or release.
Overview
python-code-review is an agent skill most often used in Ship (also Build backend) that reviews Python files for PEP8, type hints, async/await usage, and exception handling via a structured checklist.
Install
npx skills add https://github.com/existential-birds/beagle --skill python-code-reviewWhat is this skill?
- PEP8 checklist: indentation, 79/72 line limits, imports, naming
- Type safety pass: hints on params/returns and justified Any usage
- Async patterns: blocking calls in async and missing await
- Error handling: bare except, context managers, logging
- Five linked reference guides (style, types, async, errors, common mistakes)
- 5 review reference areas (PEP8, type safety, async, errors, common mistakes)
- Line length ≤79 characters (≤72 for docstrings/comments)
- 4-space indentation standard in checklist
Adoption & trust: 529 installs on skills.sh; 61 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You are about to merge Python changes but lack a consistent checklist for style, typing, async pitfalls, and error-handling smells.
Who is it for?
Indie devs self-reviewing .py files in agent-assisted IDEs who want PEP8-plus-async discipline without hiring a reviewer.
Skip if: Non-Python stacks, greenfield architecture design, or automated CI substitution when you only need a linter config.
When should I use this skill?
Reviewing .py files, checking type hints, async/await usage, or exception handling in Python code.
What do I get? / Deliverables
You get prioritized review notes tied to five reference areas so fixes are applied before merge or release tagging.
- Checklist-based review notes mapped to reference guides
- Identified PEP8, typing, async, and error-handling issues
- Actionable fix list before merge or release
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Formal review is cataloged under Ship because it gates quality before launch, even though you can invoke it while still building features. The skill is a review checklist against existing Python modules—not scaffolding, deploy, or monitoring.
Where it fits
Sanity-check a new FastAPI route file for missing return types before opening a PR.
Run the full PEP8 and async checklist on a feature branch right before squash merge.
Review a hotfix script for logging and exception context before deploying to production.
How it compares
Structured human-style Python review checklist—not a one-shot formatter or generic language-agnostic code smell scan.
Common Questions / FAQ
Who is python-code-review for?
Solo builders and tiny teams maintaining Python backends, scripts, or agent tools who want agent-guided review before shipping.
When should I use python-code-review?
Use in Ship review before merge; during Build backend when iterating on .py modules; whenever checking type hints, async/await usage, or exception handling in Python files.
Is python-code-review safe to install?
It is read-only review guidance with no inherent runtime side effects; still review the Security Audits panel on this Prism page before trusting any third-party skill package in your repo.
SKILL.md
READMESKILL.md - Python Code Review
# Python Code Review ## Quick Reference | Issue Type | Reference | |------------|-----------| | Indentation, line length, whitespace, naming | [references/pep8-style.md](references/pep8-style.md) | | Missing/wrong type hints, Any usage | [references/type-safety.md](references/type-safety.md) | | Blocking calls in async, missing await | [references/async-patterns.md](references/async-patterns.md) | | Bare except, missing context, logging | [references/error-handling.md](references/error-handling.md) | | Mutable defaults, print statements | [references/common-mistakes.md](references/common-mistakes.md) | ## Review Checklist ### PEP8 Style - [ ] 4-space indentation (no tabs) - [ ] Line length ≤79 characters (≤72 for docstrings/comments) - [ ] Two blank lines around top-level definitions, one within classes - [ ] Imports grouped: stdlib → third-party → local (blank line between groups) - [ ] No whitespace inside brackets or before colons/commas - [ ] Naming: `snake_case` for functions/variables, `CamelCase` for classes, `UPPER_CASE` for constants - [ ] Inline comments separated by at least two spaces ### Type Safety - [ ] Type hints on all function parameters and return types - [ ] No `Any` unless necessary (with comment explaining why) - [ ] Proper `T | None` syntax (Python 3.10+) ### Async Patterns - [ ] No blocking calls (`time.sleep`, `requests`) in async functions - [ ] Proper `await` on all coroutines ### Error Handling - [ ] No bare `except:` clauses - [ ] Specific exception types with context - [ ] `raise ... from` to preserve stack traces ### Common Mistakes - [ ] No mutable default arguments - [ ] Using `logger` not `print()` for output - [ ] f-strings preferred over `.format()` or `%` ## Valid Patterns (Do NOT Flag) These patterns are intentional and correct - do not report as issues: - **Type annotation vs type assertion** - Annotations declare types but are not runtime assertions; don't confuse with missing validation - **Using `Any` when interacting with untyped libraries** - Required when external libraries lack type stubs - **Empty `__init__.py` files** - Valid for package structure, no code required - **`noqa` comments** - Valid when linter rule doesn't apply to specific case - **Using `cast()` after runtime type check** - Correct pattern to inform type checker of narrowed type ## Context-Sensitive Rules Only flag these issues when the specific conditions apply: | Issue | Flag ONLY IF | |-------|--------------| | Generic exception handling | Specific exception types are available and meaningful | | Unused variables | Variable lacks `_` prefix AND isn't used in f-strings, logging, or debugging | ## Gates (reporting workflow) Complete **in order**. Do not advance until each **pass condition** is met. 1. **Scope** — **Pass:** You list every `.py` path (or explicit glob) you inspected this run. 2. **False-positive screen** — **Pass:** For each issue you plan to report, you checked **Valid Patterns** and **Context-Sensitive Rules** above; you drop or narrow the finding if those sections say not to flag it. 3. **Evidence** — **Pass:** Each remaining finding includes **`[FILE:LINE]`** (or a bounded line range). Symbols or short verbatim snippets may supplement the location anchor but do not replace it. 4. **Verification protocol** — **Pass:** You load [review-verification-protocol](../review-verification-protocol/SKILL.md) and complete its mandatory steps **for each reported issue** before the user-facing write-up. 5. **Ship** — **Pass:** The user-visible output matches whatever structure that protocol requires (no issues-only dump that skips its checks). ## When to Load References - Reviewing code formatting/style → pep8-style.md - Reviewing function signatures → type-safety.