clear-writing
Skill1 starsChanged 3 months agoApache-2.0View on GitHub
Write and review clear, accurate documentation, docstrings, code comments, procedures, and technical explanations. Combine prose guidance with the repository's language-specific documentation conventions.
17 other projects use a version of this.
Adopted by
Most recently taken up by
- tovrleaf/openkatatheir own version, first seen Nov 16, 2026
- rediche/skillstheir own version, first seen Nov 16, 2026
- emadabdulrahim/claude-skillstheir own version, first seen Nov 16, 2026
- PanQiWei/pqw-skillstheir own version, first seen Nov 15, 2026
- liao666brant/skillstheir own version, first seen Nov 15, 2026
- wanderingspirit03/clear-writing-skilltheir own version, first seen Nov 15, 2026
Other versions17 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 17
- wanderingspirit03/clear-writing-skill★ 48same name
- wpank/ai★ 11same name
- rediche/skills★ 3same name
- liao666brant/skills★ 1same name
- PanQiWei/pqw-skills★ 1same name
- pinkpixel-dev/agent-context-kit★ 1same name
- pinkpixel-dev/skills★ 1same name
- sglibiciuc/skills★ 1same name
- sgrzincich/skills★ 1same name
- SylphxAI/skills★ 1same name
7 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 repository28 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- agent-workboardSkill
- clear-writingSkill
- documentation-impactSkill
- github-state-auditSkill
- gitignore-auditSkill
- milestone-deliverySkill
- repository-checkSkill
- repository-delivery-gateSkill
- repository-orientationSkill
- resumable-worktree-runSkill
- security-reviewSkill
- session-usage-auditSkill
- template-project-creatorSkill
- agent-workboardSkill
- documentation-impactSkill
- github-state-auditSkill
- gitignore-auditSkill
- milestone-deliverySkill
- repository-checkSkill
- repository-delivery-gateSkill
- repository-orientationSkill
- resumable-worktree-runSkill
- security-reviewSkill
- session-usage-auditSkill
- template-project-creatorSkill
The file
We split this skill into the rules it gives an agent
6 rules. 0 are common, 6 are distinctive, and 0 are very specific to this project.
0
Common
Most of the 14 edited versions we read keep these.
6
Distinctive
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 25
Keep evidence close to a claim.
- Distinctive: line 34
Use familiar words when they retain the technical meaning.
- Distinctive: line 39
Keep one stable term for one concept.
- Distinctive: line 51
Use code formatting for identifiers, commands and literal values.
- Distinctive: line 53
Do not expose secrets, private records or machine-specific paths in examples.
- Distinctive: line 64
If the input says a fix resolved a problem but omits the problem's name, request that name.
“Common” is measured: kept by at least 6 in 10 of the 14 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
Clear writing
Help a reader understand the behavior, decision or action without reconstructing it from scattered context. Apply this skill to source documentation as well as guides and explanations. It does not require a particular agent host, model, network connection or personal installation.
Establish the meaning
Identify the audience, purpose and main point before editing sentences. Read the whole passage. Preserve the supplied meaning; flag missing facts rather than inventing causes, symptoms, actors, measurements, guarantees or recovery steps. User-requested voice and established technical terminology take precedence over stylistic defaults.
Organize around the reader's needs
- Lead with the answer or purpose when context permits. Put prerequisites and consequential warnings before the action they govern.
- Keep evidence close to a claim. Distinguish observations, recommendations and uncertainty; a plausible explanation is not a verified fact.
- Give each paragraph a purpose. Use headings and lists to expose structure, not to fragment a simple explanation. Number steps only when order matters.
- Explain what a reader needs to use, maintain or diagnose the system. Link to a durable detailed explanation instead of maintaining conflicting copies.
Prefer direct, precise prose
Use familiar words when they retain the technical meaning. Remove filler and stale metaphors. Prefer active voice when the responsible actor is known, but never invent an actor to avoid passive voice. Keep necessary qualifications and useful repetition. A shorter sentence is not automatically clearer.
Keep one stable term for one concept. Explain unfamiliar domain language rather than replacing it with a misleading everyday synonym. Avoid promotional claims, unnecessary idioms and claims that a reader's task is easy. Do not rewrite already clear text merely to demonstrate editing.
Apply the right technical format
For docstrings, API comments and algorithm explanations, read Source documentation. Follow the existing language and toolchain conventions; writing guidance does not replace required tags, type information, comment delimiters or executable examples.
Use code formatting for identifiers, commands and literal values. Make links describe their destination. Keep instructions executable and examples synthetic. Do not expose secrets, private records or machine-specific paths in examples.
Check meaning and evidence
Compare the result with the source and implementation. Preserve negation, conditions, exceptions, causal relationships, ordering, units, dates, bounds and claim strength. For example, "retry at most twice" must not become "retry twice," and "may reduce latency" must not become a measured performance claim.
Retain distinctions such as authentication versus authorization. If an actor is unknown, "the file was deleted" is more accurate than naming an administrator. If the input says a fix resolved a problem but omits the problem's name, request that name; do not invent a symptom or change the assertion into uncertainty.
Review documentation against actual behavior and tests. Structural lint cannot prove accuracy, useful troubleshooting advice or invocation of this skill. Report those evidence limits explicitly.
Deliver the requested result
For a draft or rewrite, return the finished text and only necessary caveats. For a review, prioritize meaning, structure and consequential omissions; give concrete corrections. Do not add a catalogue of optional synonym changes.
See Provenance for sources and attribution. Routine use is offline; consult current authoritative documentation when API or toolchain details need verification.
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.

