write-for-ai

write-for-ai

Documentation in this pack has a different primary audience than usual. Most docs are written for a human who will skim them once. These are written for an AI assistant in a future session — same operator, same model, but zero context from this conversation.

AI reads tables faster than prose. It follows explicit file paths better than vague references. It needs "always do X, never do Y" stated declaratively, not implied. It re-reads the same file every session, so the payoff for writing once is large.

This skill produces docs in that style. Humans benefit too — the structure is also friendlier for cold skimmers.

State assumptions — before acting

Before starting the procedure, write an explicit Assumptions block. Don't pick silently between interpretations; surface the choice. If any assumption is wrong or ambiguous, pause and ask — do not proceed on a guess.

Required block:

Assumptions:
- Target artifact:   <README | CLAUDE.md | AGENTS.md | commit message | PR body | changelog | architecture doc>
- Audience:          <AI primary (default) | humans primary (explicit request)>
- Edit mode:         <new doc | surgical edit (preserve voice + structure) | full rewrite (explicit operator approval required)>
- Verifiable claims: <list of commands the doc will cite — each must actually run before writing>

Typical items for this skill:

• The target artifact (README / CLAUDE.md / commit / PR body / AGENTS.md)
• The verification commands the repo actually supports — every capability claim requires one
• The audience (AI is primary, humans are secondary; reverse only on explicit request)

Stop-and-ask triggers:

• Operator requests marketing copy, superlatives, or unbacked claims — refuse per Objectivity section, explain why
• A verification command does not exist for a claim the operator asked to include — ask whether to drop the claim or add the verification

Silent picks are the most common failure mode: the skill runs, produces plausible output, and the operator doesn't notice the wrong interpretation was chosen. The Assumptions block is cheap insurance.