SKILL.md
User-facing documentation
Write for the person using the tool, not the person who built it.
"User" means whoever uses the thing. For an app, that's an end user. For a library, it's the developer who installs it. Either way they are not implementing it, and the docs should reflect that.
Voice
Everyday English — the way you'd explain it to a colleague sitting next to you. Formality doesn't add authority, it just adds distance and words.
- Second person, active, present tense. "You tap Save," not "the Save button should be tapped" or "the user will then be able to save."
- Cut "just," "simply," "easy," "obviously." They add nothing when things work, and read as mockery when they don't.
- No marketing adjectives. "Powerful," "seamless," "robust," "intuitive" — that's the author admiring the product. The reader is mid-task and doesn't care.
- One term per concept, matching the UI exactly. If the button says Workspace, the docs never say "project" or "team space." Varying your vocabulary is good prose and bad documentation — every synonym reads as a new concept.
Scope: what goes in
Include only what the reader needs to use the tool. The default is to leave things out.