writing-docs
Skill4 starsChanged 57 days agoApache-2.0View on GitHub
Write, revise, and deslop documentation for this repository in plain technical English. Use for the docs site, internal plans and specs, README, CHANGELOG, notebook research notes, error messages, and any prose where AI writing tells, density, or readability matter.
24 other projects use a version of this, 1 of them edited.
Adopted by
Most recently taken up by
- smarzban/agent-skillstheir own version, first seen Nov 15, 2026
- sourcehawk/feature-dev-workflowtheir own version, first seen Nov 15, 2026
- grgrwlkr/claude-dashboard-vscodetheir own version, first seen Nov 8, 2026
- johannschopplich/skillstheir own version, first seen Nov 8, 2026
- The-Vibe-Company/quivrtheir own version, first seen Nov 8, 2026
- Wade-DevCode/awesome-coding-skills-cntheir own version, first seen Nov 8, 2026
Used with
Projects with it also use pr-description, prototype and 3 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
MicrosoftSkillpr-description
Draft Nacelle PR titles, pull request descriptions, commit titles, commit descriptions, and squash commit messages. Use when asked for PR or commit wording, a branch summary, or a PR description that can be used in a commit. Omit validation sections from commit bodies and remove filler.
Also in 3 projects that use this
GoogleSkillprototype
Build a throwaway prototype to answer a design question. Use when the user wants to sanity-check whether a state model or logic feels right, or explore what a UI should look like.
Also in 3 projects that use this
GoogleSkillgrilling
Grill the user relentlessly about a plan, decision, or idea. Use when the user wants to stress-test their thinking, or uses any 'grill' trigger phrases.
Also in 3 projects that use this
MicrosoftSkillhandoff
Compact the current conversation into a handoff document for another agent to pick up.
Also in 3 projects that use this
- +1 more from google
Other versions24 projects use a version of this.
Word for word · 0
None found.
Edited · 1
- stormlightlabs/mire★ 190% same
Wrote their own version · 23
- remotion-dev/remotion★ 73ksame name
- QuivrHQ/quivr★ 40ksame name
- The-Vibe-Company/quivr★ 40ksame name
- medusajs/medusa★ 37ksame name
- Nagi-ovo/gemini-voyager★ 21ksame name
- nukeop/nuclear★ 19ksame name
- ngrx/platform★ 8.3ksame name
- cuthbertLab/music21★ 2.6ksame name
- c15t/c15t★ 2ksame name
- NVIDIA/Megatron-Energon★ 388same name
13 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository14 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- commits-and-prsSkill
- decomposeSkill
- github-boardSkill
- implementSkill
- releaseSkill
- reviewSkill
- reviseSkill
- rubber-duckSkill
- specifySkill
- thunderstormSkill
- triageSkill
- worktreeSkill
The file
We split this skill into the rules it gives an agent
11 rules. 0 are common, 9 are distinctive, and 2 are very specific to this project.
0
Common
Most of the 23 edited versions we read keep these.
9
Distinctive
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 8
Write like a person choosing words for a reader.
- Distinctive: line 91
Never drop a fact, a number, a limit, or a qualifier to reach a target.
- Distinctive: line 101
Use this mode by default.
- Distinctive: line 103
Use one term for one thing.
- Distinctive: line 104
Prefer short common words and plain verbs.
- Distinctive: line 106
Put the actor before the action when the actor matters.
- Distinctive: line 110
Use active voice when it clarifies responsibility.
- Very specific: line 116
Read references/tells.md for the full catalog and repository-specific examples.
- Very specific: line 145
Run pnpm --dir docs build after editing anything under docs/.
- Distinctive: line 155
Check the soft limits and the length target, and restructure where one is exceeded.
- Distinctive: line 157
Read for rhythm, parallel lists, and clear pronoun referents.
“Common” is measured: kept by at least 6 in 10 of the 23 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Writing docs
Write like a person choosing words for a reader. Keep every fact, number, qualifier, and identifier. Remove whatever does not help.
This applies to the chat response as well as the file being edited.
Soft limits
These are warnings that something needs restructuring, not reasons to delete information. Exceed one when the content requires it and the result still reads cleanly.
| Limit | Target | What exceeding it usually means |
| Line width | 80 characters | Reflow. Tables and links may exceed. |
| Sentence | 25 words | Two ideas in one sentence. Split them. |
| Paragraph | 5 sentences | More than one topic. Split or cut. |
| Section before a heading | 40 lines | The section needs subheadings or is doing too much. |
| Consecutive bullets | 9 | The list is a table, or it needs grouping. |
| Table columns | 4 | The table is prose in disguise. |
| Heading depth | 3 (###) | The document needs splitting. |
| Code block | 25 lines | Show the relevant span and link to the source. |
Prose paragraphs should outnumber tables and lists in any document that explains something. A page of nothing but tables is a reference, not an explanation; say which one you are writing.
Document length
The soft limits above govern a sentence, a paragraph, and a section. None of them stops a document from growing past what a reader will finish. Match the length to what a reader has to do with the document, and check it against these targets.
Count lines only where something wraps them. A file wraps at 80, a commit body at 72, a terminal at its width. Everything GitHub renders — a pull request body, a comment, an issue — is soft-wrapped, so one paragraph is one line and a line count measures nothing. Those are counted in words. A comment that passed the old 40-line cap ran 392 words, which is how the targets below were being met and missed at the same time.
| Text | Unit | Target |
| Error message | lines | 2 |
| Pull request title | characters | 53 |
| Pull request body | lines | 20 |
| Review comment | words | 200 |
| Edit reply | words | 150 |
| Any other pull request comment | words | 100 |
| Issue body | words | 250 |
| Chat reply | lines | 20 |
| Command or agent definition | lines | 40 |
SKILL.md | lines | 200 |
| Docs page, README, internal spec | lines | 300 |
The pull request body counts in lines because it is a commit body: this
repository merges with squash_merge_commit_message=PR_BODY, so the body
reaches git log verbatim and is written wrapped at 72 columns. The title is
the subject, and 53 is 59 less the (#NN) GitHub appends. commits-and-prs
holds both, and .claude/scripts/check-commit-message.py --pr reports them on
every pull request. The review and reply numbers live with review and
revise, which is where they are read.
A reference page that enumerates a surface, every configuration key or every flag, grows with that surface and is the usual exception. It still needs headings a reader can jump between.
A chat reply is held to its target like anything else. A long answer in chat is a document with no home: nobody can find it again, and the length hides which sentence held the decision. When a reply wants to exceed the target, write the file instead and answer with where it went.
A reader looking for one answer should reach it without reading the rest. When a document passes its target, cut in this order:
- Anything the code, the tests, or
--helpalready states. Link to it. - Anything another document states. One fact has one home; every other mention links to that home.
- Background the audience already has.
- Examples past the first one that shows the shape.
Split only after cutting. A split that sends one reader to two files costs more than the length did, so split by audience or by task, never by size alone.
Never drop a fact, a number, a limit, or a qualifier to reach a target. A document whose facts do not fit is more than one document.
A comment is the exception, because it is a reply rather than a record. When a
review comment does not fit, cut a finding and say how many you left out; do
not compress ten findings into denser prose. The reader can ask for the rest,
and the tenth nit was never what the length was for.
Plain technical prose
Use this mode by default.
- Use one term for one thing. Do not cycle through synonyms.
- Prefer short common words and plain verbs. Use the verb, not the nominalization: "parse the config," not "perform parsing of the config."
- Put the actor before the action when the actor matters.
- Give each paragraph one topic. Put conditions before the instruction they govern.
- State the point before its evidence, once.
- Use active voice when it clarifies responsibility. Keep passive voice when the actor is unknown or deliberately backgrounded.
- Name sources, limits, and observable behavior.
Deslop rules
Read references/tells.md for the full catalog and repository-specific
examples.
The tells that appear most in this repository:
- Bold-first bullets used as the default pattern. Use them only when the bolded span is a real term being defined.
not X, but Yand its variants, repeated.- Closing sections that restate what the document already said.
- Words that name a judgment instead of a property:
load-bearing,the whole point,worth noting,crucially,seamless,robust. boundedwithout a stated limit,contractfor anything that is not a formal API or schema,boundaryfor anything that is not an edge.- Em dashes used repeatedly for emphasis.
- Tricolons, anaphora, and one-line slogans.
One instance of any of these can read as a human voice. Repetition is the tell.
Repository conventions
- Sentence case for new headings. Existing pages under
docs/src/content/docs/docs/notebook/use title-case section names as a house format; keep that format and deslop the prose inside it. - Notebook pages keep their frontmatter and their section order: summary, key ideas, claims and evidence, terms, questions.
- Files under
internal/needname,last_updated, and a ULIDidin frontmatter. Generate identifiers with.claude/scripts/ulid.py. - Claims in research notes carry a confidence caveat. Do not strip it while editing for style.
- Run
pnpm --dir docs buildafter editing anything underdocs/. It validates internal links.
Editing method
- Identify the audience, the purpose, and which mode applies.
- Mark the facts, conditions, numbers, and qualifiers that must survive.
- State each point once, before its support.
- Cut preambles, duplication, filler, and template endings.
- Replace abstractions and nominalizations with concrete nouns and verbs.
- Check the soft limits and the length target, and restructure where one is exceeded.
- Read for rhythm, parallel lists, and clear pronoun referents.
For a small edit, change the smallest useful span. For a rewrite, preserve every fact unless the user authorizes substantive changes.
Check before returning
- Does the first sentence answer instead of announce?
- Does each claim appear once, before its evidence?
- Can any paragraph disappear without losing a fact?
- Is the document inside its length target? If not, what did the extra length buy the reader?
- Does every
same,this, andexistinghave a clear referent? - Are limits, sources, and failure behavior named rather than implied?
- Did one trope recur enough to become visible?
- Does the ending stop, or explain that it has ended?
- Did a style rule damage accuracy or clarity? If so, break the rule.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

