code-standards

name	code-standards
description	Generates or updates docs/code-standards.md by scanning the codebase for actual conventions. Produces an example-rich standards file optimized for LLM consumers, grounded in the project's real patterns. Not for auditing one file's naming, comments, or clarity (use code-clarity-and-docs).
user-invocable	false

Skill: code-standards

Generate or update docs/code-standards.md — a project-specific conventions file optimized for LLM consumers.

LLMs default to training-data averages. Without project-specific guidance, they produce generic code that passes tests but fails review. This skill extracts the patterns that matter: concrete examples, forbidden patterns, and exemplar file pointers.

---

Workflow

1. Detect

Check for existing standards file:

1. Look for docs/code-standards.md (or legacy docs/code-patterns.md)
2. If legacy exists: migrate path (rename to docs/code-standards.md)

2. Decide: Skip, Update, or Generate

If file exists, read the <!-- base-commit: ... --> header and check staleness:

git rev-list <base-commit>..HEAD --count

Commits since	Action
0	Skip — file is current, return it as-is
1–20	Update — spot-check recent diffs (git diff <base-commit>..HEAD), update changed sections only
21+	Generate — full re-scan, regenerate entire file

If file exists but has no <!-- base-commit: ... --> header, the sha is unknown, or the repo is not a git repo: treat as Generate.

If file missing, proceed to full Generate.

3. Scan

Search the codebase for conventions. Adapt searches to what the project actually contains — not every section applies to every codebase.

Search strategy per section:

Section	What to grep/glob for
Forbidden Patterns	Linter configs, eslint-disable comments, TODO/HACK comments
Code Examples	Covered by other searches — select best do/don't pairs found
Error Handling	try/catch, Result types, error classes, .catch()
Imports & Dependencies	Import statements, barrel files, dependency direction
Testing Patterns	Test files, helpers, fixtures, mocks
Naming	Variable/function/file naming across 5+ files
File Organization	Directory structure, co-location patterns
Technology Decisions	Package files, config files, framework imports
Exemplar Files	Well-structured files that demonstrate multiple conventions

Scan breadth over depth — sample across the codebase rather than exhaustively cataloging one directory.

For Update mode: Only search sections where recent diffs show changes to relevant patterns.

4. Write

Read the section templates before writing: Read(${CLAUDE_PLUGIN_ROOT}/skills/code-standards/references/section-templates.md)

File format:

<!-- base-commit: [HEAD sha] -->
<!-- generated: [YYYY-MM-DD] -->

# Code Standards

[sections per templates]

Core rules:

• Every section MUST contain at least one code snippet or file pointer. Descriptions without examples waste tokens and don't anchor behavior.
• Separate the rule from the example. State the constraint, then show the code. Never weave constraints into narrative prose — constraints dissolve in paragraphs (NLD-P, 2602.22790).
• Examples should explain WHY the pattern works, not just show the code. Interpretable examples outperform raw code blocks (CL4SE, 2602.23047).
• Only document what deviates from mainstream conventions. "Use meaningful variable names" is noise.
• Show the project's way, not the textbook way. Extract from actual code, don't invent idealized examples.
• Shorter is better. A 200-line file that's all signal beats a 500-line file with filler.

Write to docs/code-standards.md. Do NOT commit the file.

5. Verify

After writing, self-check:

• Every section has a code snippet or file pointer
• No section is pure prose without an example
• base-commit header matches current HEAD
• File is under 300 lines (warn if over, trim filler)
• No generic advice the LLM already knows

---

Sections

Nine sections. Contrastive sections (DO/DON'T) come first — they resist confirmation bias and anchor behavior more reliably than descriptive sections (2603.18740). Not all sections apply to every project — skip where you find no meaningful conventions.

1. Forbidden Patterns — Anti-patterns with rationale and correct alternative
2. Code Examples — 2-3 do/don't pairs showing the most important conventions
3. Error Handling — The project's specific strategy
4. Imports & Dependency Direction — Ordering, what can import what
5. Testing Patterns — Framework, helpers, fixtures
6. Naming Conventions — Variables, functions, files, modules
7. File Organization — Where new things go, co-location rules
8. Technology Decisions — Non-obvious choices and constraints only
9. Exemplar Files — Pointers to "gold standard" files for common tasks

See the templates file for detailed format per section.

---

Chain

From	To
plan (codebase scan step)	Returns docs/code-standards.md path
build-agent (discovery phase)	Reads the file directly