agentleFS
sodejmsodejm/portable-agent-repository-kit/.claude/skills/clear-writing/SKILL.md

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

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
  1. Distinctive:

    Keep evidence close to a claim.

    line 25
  2. Distinctive:

    Use familiar words when they retain the technical meaning.

    line 34
  3. Distinctive:

    Keep one stable term for one concept.

    line 39
  4. Distinctive:

    Use code formatting for identifiers, commands and literal values.

    line 51
  5. Distinctive:

    Do not expose secrets, private records or machine-specific paths in examples.

    line 53
  6. Distinctive:

    If the input says a fix resolved a problem but omits the problem's name, request that name.

    line 64

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.