Python Code Review

Reviews Python code for type safety, async patterns, error handling, and common mistakes. Use when reviewing .py files, checking type hints, async/await usag...

Security Scan

The skill's instructions and references mostly match a Python code-review tool, but it instructs the agent to load a verification file via a relative path outside the bundle (../review-verification-protocol/SKILL.md), which is unexpected and could cause the agent to read files outside the intended scope.

Purpose & Capability

Name/description align with contents: the SKILL.md and the six reference docs contain PEP8, type-safety, async, error-handling and common-mistakes guidance appropriate for a Python code-review skill. The skill declares no binaries, env vars, or installs — which is coherent for an instruction-only reviewer.

Instruction Scope

The runtime instructions require the agent to list every .py inspected and to produce anchored findings ([FILE:LINE]) — appropriate for a reviewer. However Gate 4 mandates loading "../review-verification-protocol/SKILL.md" and completing its mandatory steps for each reported issue. That referenced file is outside the skill bundle and is not present in the manifest. Requiring the agent to load a relative path outside the skill directory is unexpected and could cause the agent to read unrelated files or depend on an external/hidden protocol; this is the primary red flag.

Install Mechanism

No install spec and no code files — instruction-only. Lowest-risk install profile; nothing is written to disk by the skill itself.

Credentials

The skill requests no environment variables, no credentials, and no config paths. This is proportionate for a static code-review instruction set.

Persistence & Privilege

always is false and there is no indication the skill requests permanent system presence or modifies other skills. Autonomous invocation is allowed (platform default) but not combined with other concerning privileges.

What to consider before installing

This skill appears to be a legitimate, instruction-only Python code reviewer, and it requires no credentials or installs. The main concern is the SKILL.md's instruction to load "../review-verification-protocol/SKILL.md" and to perform its mandatory steps for each reported issue — that file is not included in the bundle, so the agent might try to read files outside the project or depend on an external protocol. Before installing or running: 1) Ask the publisher for the missing review-verification-protocol file and inspect it (what mandatory steps does it require? does it reference external endpoints or secrets?). 2) If you run the skill, do so in a sandboxed environment or limit the agent's filesystem scope so it cannot read unrelated files. 3) Verify the skill only reads the intended source files (.py paths you expect) and does not exfiltrate findings to external endpoints. If the verification-protocol is benign and tied to the same repository, the skill is coherent; if the protocol is unavailable or requires access to other repos/sensitive files, treat it as risky.

Quick Reference

Issue Type	Reference
Indentation, line length, whitespace, naming	references/pep8-style.md
Missing/wrong type hints, Any usage	references/type-safety.md
Blocking calls in async, missing await	references/async-patterns.md
Bare except, missing context, logging	references/error-handling.md
Mutable defaults, print statements	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 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.md
• Reviewing async def functions → async-patterns.md
• Reviewing try/except blocks → error-handling.md
• General Python review → common-mistakes.md

Review Questions

1. Does the code follow PEP8 formatting (indentation, line length, whitespace)?
2. Are imports properly grouped (stdlib → third-party → local)?
3. Do names follow conventions (snake_case, CamelCase, UPPER_CASE)?
4. Are all function signatures fully typed?
5. Are async functions truly non-blocking?
6. Do exceptions include meaningful context?
7. Are there any mutable default arguments?

Before reporting: complete Gates (reporting workflow) above (especially gate 4).