| name | py-style |
| description | Enforce and review Python coding style for this project. PEP 8 is the baseline, with the project's explicit positive and negative constraints applied on top. Use this skill whenever you are writing new Python code, reviewing existing Python files, or responding to feedback about code quality. Trigger on any task that involves creating or modifying .py files, reviewing a function or class, or when the user asks about code style, best practices, or refactoring. Always apply these rules proactively -- don't wait for the user to ask. |
Python Style Guide
PEP 8 is the baseline style guide for all Python code in this project. On top
of PEP 8, this skill enforces the project's positive and negative constraints.
Apply both layers proactively when writing Python code, and surface every
violation when reviewing code.
When PEP 8 and a project-specific constraint overlap, follow the stricter
project-specific constraint. When PEP 8 covers an issue not mentioned here,
follow PEP 8.
The constraints exist to keep code readable, debuggable, and honest about
failure. Clever workarounds that hide bugs are more expensive than crashes that
reveal them immediately.
Constraint Architecture
Constraints are organized into two reference files that can grow independently.
Anyone on the team can add new constraints by appending to the relevant file --
no renumbering, no restructuring, no touching SKILL.md.
py-style/
|-- SKILL.md
`-- references/
|-- positive_constraints.md
`-- negative_constraints.md
How to read the constraints
Before writing or reviewing Python code, read both constraint files:
references/positive_constraints.md -- the full list of positive constraints
(P-XXX), which describe what to do.references/negative_constraints.md -- the full list of negative constraints
(N-XXX), which describe what not to do.
Apply every constraint from both files. Positive and negative constraints have
equal weight: a positive constraint tells you the right way; a negative
constraint tells you the boundary you must not cross.
How to add a new constraint
- Open the appropriate file:
positive_constraints.md or
negative_constraints.md.
- Append a new section at the end using the next available ID, such as
P-014 or N-013.
- Follow the existing format: ID in the heading, a rationale explaining why,
and Wrong/Right or Forbidden/Correct examples where applicable.
- Do not renumber or reorder existing constraints.
- Do not modify
SKILL.md; it automatically picks up new constraints from the
reference files.
When constraints conflict
If a positive and negative constraint appear to conflict, the negative
constraint wins; boundaries are harder limits than preferences. If two
constraints of the same type conflict, surface the conflict to the user with
reasoning rather than silently picking one path.
Review Workflow
When asked to review a file or selection:
- Read both
references/positive_constraints.md and
references/negative_constraints.md in full.
- Read the code to review in full.
- Check PEP 8 violations first, then check every positive and negative
constraint.
- For each violation, state the line reference, the constraint ID, and a
one-sentence explanation.
- Propose the corrected version inline.
- If no violations are found, say so explicitly and mention any remaining test
gaps or residual risk.
Writing Workflow
When writing new Python code:
- Read both constraint files in full before editing.
- Apply PEP 8 and every positive and negative constraint before producing code.
- If a constraint conflict arises or a genuine exception is needed, surface it
to the user with reasoning rather than silently picking one path.
references/examples.md remains supplemental reading. The active style
contract lives in the positive and negative constraint files.
