Writing Standards
Every document you write, edit, or review must comply with these rules. A document is any
prose deliverable: a README, a spec, a rule, a skill, a design doc, a guide, a review, release
notes. This skill does not govern normal conversation — only the deliverable.
The rules come in two sets, both applied on every document task:
references/common/source-to-deliverable.md — how to turn a source (code you read, or a
discussion you had) into a deliverable without dragging the source into the output.references/common/anti-slop.md — the patterns that make a document read as machine-padded
filler, each with a rule code and a fix.
All paths in this document are relative to this SKILL.md file, so they resolve wherever the skill
is installed.
Step 0 — Bootstrap the reminder hooks (once per session, only if needed)
The hooks inject a short reminder of these rules at session start and on every prompt, so the
rules don't get buried as a conversation grows. Run the fast read-only check first (single
absolute-path command, no cd/&&):
python3 <skill-dir>/bootstrap.py --verify
Exit 0 → hooks are wired; go to Step 1. Non-zero → wire them:
python3 <skill-dir>/bootstrap.py
It auto-detects scope (this project's .claude/settings.json vs global ~/.claude/settings.json)
from where the skill is installed, and merges two entries — SessionStart and UserPromptSubmit —
without disturbing hooks you already have. Tell the user to restart the session so the hooks
activate; until then the reminder isn't injected, but this SKILL.md is still in force for any
document you write this session.
Step 1 — Pick the document type (optional refinement)
references/common/ applies to every document. If a per-type guide exists under
references/<doc-type>/ (README, spec, review, …), read it too — it specializes the common rules
for that kind of document. If none matches, the common rules are the whole standard.
Step 2 — Write, edit, or review against the rules
Read both common references, then produce the document. The two failures this skill exists to stop:
- Echoing the source. You read code (or had a discussion) to understand something, then paste
that source — the code, the function names, the one example you just discussed — into the
deliverable. The source is what you learned from; it does not appear in the output. See
source-to-deliverable.md.
- Slop. Hedging, hype, throat-clearing, cheerleading, reflexive headers/bold/lists, and
sentences that sound like content but carry none. See
anti-slop.md.
When reviewing a document, report violations by rule code with the offending line and the fix —
the same way coding-standards reports a code review.
1---2name: writing-standards3description: Standards for writing, editing, and reviewing DOCUMENTS — READMEs, specs, rules, skills, design docs, guides, and any prose deliverable produced from a source (existing code, or a prior discussion). Two rule sets apply on every document task: (1) source-to-deliverable — code→doc describes what the system DOES with no code or code-identifiers; discussion→rule states the general principle, not the specific example just discussed; (2) anti-slop — cut hedging, hype words, throat-clearing, cheerleading, reflexive formatting, and padding. Use when the user says "write a document", "document this code", "write up what this does", "turn this into a rule/skill", "make a doc from our discussion", "review this doc", or "is this slop?". Consult before authoring or reviewing ANY document, even when the user does not say "standards" — every document write/edit/review must comply. The companion to coding-standards: that one governs code, this one governs documents.4license: MIT5---67# Writing Standards89Every document you write, edit, or review must comply with these rules. A *document* is any10prose deliverable: a README, a spec, a rule, a skill, a design doc, a guide, a review, release11notes. This skill does **not** govern normal conversation — only the deliverable.1213The rules come in two sets, both applied on every document task:1415- **`references/common/source-to-deliverable.md`** — how to turn a *source* (code you read, or a16 discussion you had) into a deliverable without dragging the source into the output.17- **`references/common/anti-slop.md`** — the patterns that make a document read as machine-padded18 filler, each with a rule code and a fix.1920All paths in this document are relative to this SKILL.md file, so they resolve wherever the skill21is installed.2223---2425## Step 0 — Bootstrap the reminder hooks (once per session, only if needed)2627The hooks inject a short reminder of these rules at session start and on every prompt, so the28rules don't get buried as a conversation grows. Run the fast read-only check first (single29absolute-path command, no `cd`/`&&`):3031```bash32python3 <skill-dir>/bootstrap.py --verify33```3435Exit 0 → hooks are wired; go to Step 1. Non-zero → wire them:3637```bash38python3 <skill-dir>/bootstrap.py39```4041It auto-detects scope (this project's `.claude/settings.json` vs global `~/.claude/settings.json`)42from where the skill is installed, and merges two entries — `SessionStart` and `UserPromptSubmit` —43without disturbing hooks you already have. Tell the user to **restart the session** so the hooks44activate; until then the reminder isn't injected, but this SKILL.md is still in force for any45document you write this session.4647---4849## Step 1 — Pick the document type (optional refinement)5051`references/common/` applies to every document. If a per-type guide exists under52`references/<doc-type>/` (README, spec, review, …), read it too — it specializes the common rules53for that kind of document. If none matches, the common rules are the whole standard.5455---5657## Step 2 — Write, edit, or review against the rules5859Read both common references, then produce the document. The two failures this skill exists to stop:60611. **Echoing the source.** You read code (or had a discussion) to understand something, then paste62 that source — the code, the function names, the one example you just discussed — into the63 deliverable. The source is what you learned from; it does not appear in the output. See64 `source-to-deliverable.md`.652. **Slop.** Hedging, hype, throat-clearing, cheerleading, reflexive headers/bold/lists, and66 sentences that sound like content but carry none. See `anti-slop.md`.6768When **reviewing** a document, report violations by rule code with the offending line and the fix —69the same way coding-standards reports a code review.
willey-labs