agentleFS
benjaminardbenjaminard/fable-skills/skills/outcome-first-writing/SKILL.md

outcome-first-writing

Skill30 starsChanged 4 months agoMITView on GitHub

Prose discipline for any written deliverable. Use whenever writing for a human reader: answers, explanations, reports, summaries, documentation, PR descriptions, emails, or analyses. Trigger especially when the draft is getting long, when reaching for headers and bullet points, or when compressing text with fragments and abbreviations.

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:

    Compression (wrong): keep every point but squeeze the prose into fragments, abbreviations, arrow chains like A → B → fails, and jargon.

    line 19
  2. Distinctive:

    If every response you write has headers, bullets, and a bolded phrase per paragraph, the formatting is a tic, not a choice.

    line 32
  3. Distinctive:

    No fragment stacks ("Fast.

    line 36
  4. Distinctive:

    No hedged symmetry ("While X has advantages, it also has drawbacks") that spends a sentence saying nothing.

    line 37
  5. Distinctive:

    No inflated connectives ("Moreover," "Furthermore," "It's worth noting that") where a plain sentence break works.

    line 38
  6. Distinctive:

    No unexplained labels or numbering you invented earlier.

    line 39

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

Outcome-First Writing

Lead with the answer. Shorten by cutting content, never by compressing prose. Readability beats brevity every time the two conflict.

Lead with the outcome

Your first sentence answers "what happened" or "what did you find": the thing the reader would ask for if they said "just give me the TLDR." Supporting detail and reasoning come after, for readers who want them. Never open with background, method, or throat-clearing; the reader who needs context will keep reading, but the reader who needs the answer should not have to hunt.

Selectivity over compression

There are two ways to make writing shorter, and only one of them works:

  • Selectivity (correct): drop whole points that do not change what the reader thinks or does next. Fewer things, said fully.
  • Compression (wrong): keep every point but squeeze the prose into fragments, abbreviations, arrow chains like A → B → fails, and jargon. Everything, said badly.

Compressed text saves the writer's tokens by spending the reader's time. If the reader has to re-read a sentence, or ask what a term means, every second the brevity saved is gone. What you keep, write in complete sentences with the technical terms spelled out.

The formatting budget

Formatting is not organization. Prose is the default.

  1. Headers belong only in genuinely sectioned documents. A conversational answer, however substantive, is paragraphs.
  2. Bullets are for lists of parallel items. Argument, explanation, and narrative are prose; a chain of reasoning chopped into bullets loses exactly the connective tissue that made it reasoning.
  3. Tables hold short enumerable facts. Explanations go in the surrounding prose, not crammed into cells.
  4. Bold marks the one thing that must survive a skim, which means it loses all meaning when applied per-sentence.

If every response you write has headers, bullets, and a bolded phrase per paragraph, the formatting is a tic, not a choice.

Kill the tells

  • No fragment stacks ("Fast. Reliable. Built for scale.") in expository writing.
  • No hedged symmetry ("While X has advantages, it also has drawbacks") that spends a sentence saying nothing.
  • No inflated connectives ("Moreover," "Furthermore," "It's worth noting that") where a plain sentence break works.
  • No unexplained labels or numbering you invented earlier; say what you mean in place.
  • Match register to reader: tighter for experts, more explanatory for newcomers, but complete sentences for both.

Why this matters

A reader judges writing by how fast they can extract what they need and how much they trust it. Answer-first structure serves the first; prose that spells things out serves the second. Text that looks like a slide deck reads as generated filler, and gets skimmed like it.

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.