agentleFS
andymaiandymai/claude-agent-team/skills/outward-writing/SKILL.md

outward-writing

Skill4 starsChanged yesterdayMITView on GitHub

Write outward-facing prose another person will read: a design or shaping doc, a proposal, a wiki page, a Slack message, a PR title, body, or reply, a review reply, an issue or ticket, an email. You collect every fact with a source, write the draft in ASD-STE100 Simplified Technical English, fact-check it sentence by sentence, and run the checker, then show the draft before anything is published. Not for code, tests, prompt files, commit messages, or replies to the user in the session.

1 other project uses a version of this.

Adopted by

Most recently taken up by

  • Other versions1 project uses a version of this.

    Word for word · 1

    1. andymai/skills★ 4100% same

    Edited · 0

    None found.

    Wrote their own version · 0

    None found.

    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 repository8 other files it gives its agents.

The file

We split this skill into the rules it gives an agent

6 rules. About 0 are common, 5 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Write the draft yourself from that list.

    line 27
  2. Distinctive:

    Do not write a dense draft and simplify it after.

    line 31
  3. Distinctive:

    Write for the reader as they are.

    line 38
  4. Distinctive:

    Write to the reader as someone the user wants to keep working with.

    line 42
  5. Distinctive:

    Never name the author in the third person, and never describe the piece itself ("this deck covers", "I explain").

    line 51
  6. Distinctive:

    Write the way a person would say it.

    line 54

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “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

Outward writing

You own every fact and every sentence. Nothing is published until the user has seen the draft and said so.

1. Facts

List every fact, number, name, and claim the piece needs, each with a source observed this session: a file and line you opened, a query or command you ran, a URL you fetched, a message you read. Write down each judgment call with its reason. No source, no sentence.

2. Write

Write the draft yourself from that list. Apply ${CLAUDE_PLUGIN_ROOT}/skills/outward-writing/reference/house-rules.md (with its ASD-STE100 grammar rules), the user's writing rules (CLAUDE.md, memory), and the venue's structure (the repo's PR template, the doc template). Apply the STE rules as you write. Do not write a dense draft and simplify it after. For anything posted under the user's name on GitHub, read two or three of their recent comments first and match that voice.

Stay as precise as the source: a total stays a total, "widened the peer range" does not become "added support", a value that moved does not "remain". Keep code spans, paths, and identifiers exactly as written.

Write for the reader as they are. Before the piece relies on a project, tool, or mechanism the reader has not seen, introduce it, and say what the author did. If the user needed something explained to them, the reader needs it too.

Write to the reader as someone the user wants to keep working with. When the piece asks something of them, thank them first, give the reason in terms they would agree with, make the ask once and plainly, and say what the user will handle. The research behind a request stays out of the piece: do not cite what you found by looking into the reader (their fork, profile, other accounts, timestamps), and do not hint at suspicion you reported to the user. State a rule they must follow as routine ("one small thing"), not as a warning ("I want to be explicit", "has to be you personally").

Under the user's name, write as the user: "I" for the author, "you" for the reader. Never name the author in the third person, and never describe the piece itself ("this deck covers", "I explain").

Write the way a person would say it. Titles and headings are plain sentences, not a formula: no fixed grammatical template, no per-line word caps (fit space by measuring the rendered result, then trim), no noun stacks ("Added median wait on the first page"), no telegraphic fragments ("Pool resets. Memory drops."). The title or first line gets the most care, because it is read first: it says what changes and what is asked.

3. Check

Reread the draft one sentence at a time against the fact list. Remove anything without a source, and fix anything that changed a fact. Then read it again as the reader: is everything they do not know introduced, does it sound like the author talking, and do the titles read naturally in a row without all sharing one shape?

For a change (a PR, a proposal, a ticket), read the first paragraph alone: can the reader say what happens today, what happens after, and what a user sees differently? State today's behavior even when the reader wrote the code. If the facts or the design changed after you drafted, rewrite the lead from the fact list instead of patching the old sentences: each sentence can stay true while the result it led to moved.

Then read it once more as the reader taking it badly: does any sentence make them feel watched, suspected, lectured, or talked down to? Rewrite that sentence before showing the draft.

Then read it for the ASD-STE100 rules. Does one action keep one verb in all of the piece? Can each passive sentence name its actor? Does any sentence carry two instructions? Then run:

python3 -I "${CLAUDE_PLUGIN_ROOT}/skills/outward-writing/scripts/check.py" DRAFT.md --max N

It fails on em or en dashes outside code and quotes, on a sentence over 25 words, and on a paragraph over 6 sentences. Fix each FAIL. It also warns on the present perfect, "-ing" verbs, possible passives, and two verbs for one action. Read each warning and fix the real ones. The first line reports the word count against the target.

4. Show, then publish

Show the draft in a quoted block with the checker's output. Publish only when the user says so. Publishing means posting, committing, or saving anywhere another person will read it. A project's CLAUDE.md or the user's memory can make an exception, for example for PR bodies.

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.