# Write Standard

> Write a well-structured standard document with headers, rules, and examples

- Skill: `sethdford/write-standard` (Agent Skill)
- Install (CLI): `npx skillmds@latest add sethdford/write-standard`
- Raw SKILL.md: https://api.skillmd.com/api/skills/sethdford/write-standard/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: sethdford (https://skillmd.com/u/sethdford)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/sethdford/write-standard

---


# Write Standard Skill

Create a new standard document that defines clear rules for a specific aspect of your project.

## Context

You're documenting a pattern, convention, or requirement that your team should follow. The standard becomes the source of truth — it's wired into agent context and used to verify compliance in ceremonies and enforcement.

## Domain Context

Standards in claude-standards follow the format established in `levels/L1-context/library/`. Each standard:

- Starts with frontmatter (category, standard name, version, customize flag)
- Has an Overview section explaining the "why"
- Contains Rules — numbered, actionable, specific
- Includes Examples — right and wrong patterns
- Defines Exceptions — when the standard doesn't apply
- Contains [CUSTOMIZE] markers for project-specific values

Reference: `levels/L1-context/README.md`

## Instructions

1. **Identify scope** — What rule are you documenting? (e.g., "error handling", "API design", "test coverage")
   - Which files does it affect?
   - Why does this standard matter to the team?
   - Deliverable: A clear 1-sentence summary

2. **Check if standard already exists** — Search `docs/standards/` for related files
   - Run: `grep -r "keyword" docs/standards/*/README.md`
   - If found, consider updating the existing standard instead of creating a new one
   - If not found, proceed to step 3

3. **Draft the standard** — Follow the template:

   ```markdown
   ---
   category: [engineering|design|quality|operations|architecture]
   standard: [kebab-case-name]
   version: 1.0
   customize: [true|false]
   ---

   # Standard Title

   ## Principles

   [Why this matters — 2-3 paragraphs]

   ## Rules

   1. **Rule Name** — What must be true
      - Details and context
      - [CUSTOMIZE]: Project-specific value needed here
   2. **Rule Name** — What must be true

   ## Examples

   ### Right ✓

   [Code/pattern that follows the standard]

   ### Wrong ✗

   [Code/pattern that violates the standard]

   ## Exceptions

   When this standard does NOT apply:

   - [Scenario where exception is valid]

   ## Compliance Checklist

   - [ ] [Verifiable check 1]
   - [ ] [Verifiable check 2]
   ```

   - Deliverable: Complete draft in `docs/standards/[category]/[standard-name].md`

4. **Add to category README index** — Update `docs/standards/[category]/README.md`
   - Add reference: `- [Standard Title](./standard-name.md) — One-line description`
   - Verify the index is alphabetized
   - Deliverable: Updated README with new entry

5. **Wire into agent context** — Update context files to reference the standard
   - In `CLAUDE.md`: Add reference if widely applicable
   - In `AGENTS.md`: Link if agents should know about it
   - In `.cursor/rules/` or equivalent: Create rule file if applicable
   - Rule: Always reference, never duplicate the standard content
   - Deliverable: Updated context files with relative paths to standard

6. **Verify with check-doc-index.sh** — Run verification
   ```bash
   ./levels/L2-ceremonies/scripts/check-doc-index.sh
   ./levels/L2-ceremonies/scripts/check-standards-refs.sh
   ```

   - Fix any orphaned docs or broken references
   - Deliverable: All verification scripts pass

## Anti-Patterns

1. **Duplicating content into CLAUDE.md** — Wrong approach
   - Standard lives in `docs/standards/`, agent files reference it
   - Agent files must never duplicate the standard text
   - Guard: If you find yourself copy-pasting from a standard into CLAUDE.md, stop and instead add a reference

2. **Vague rules that can't be verified** — Unclear standards
   - Rule: "Code should be clean" is not verifiable
   - Right: "No function longer than 50 lines; all functions have JSDoc"
   - Guard: For each rule, ask "How would a machine check this?"

3. **Missing [CUSTOMIZE] markers** — Makes standard unusable by other projects
   - Every project-specific value needs a marker
   - Examples: tool names, file paths, specific version numbers
   - Guard: Search the draft for proper nouns or version numbers — mark them

4. **Standards hoarding** — Writing standards for everything
   - Don't document every single detail as a standard
   - Standards are for patterns that appear 3+ times and have enforcement value
   - Guard: Before writing a standard, ask: "Would this affect ceremonies or enforcement?"

## Further Reading

- `levels/L1-context/README.md` — How the library is organized
- `levels/L1-context/library/quality/governance.md` — Example standard
- `AGENTS.md` — How to wire standards into agent context
- `levels/L2-ceremonies/ceremonies/pr-gate.md` — How standards are verified