agentleFS
boazsegevboazsegev/omoya/skills/language-writing/SKILL.md

language-writing

Skill1 starsChanged 6 days agoMITView on GitHub

Use when writing or editing any human language text output (web, docs, email, proposals, marketing, reports, documentation). Not code.

We split this skill into the rules it gives an agent

13 rules. About 0 are common, 13 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈13

    Distinctive · estimate

    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:

    Every text is a negotiation for the reader's attention and trust: the reader can stop reading, distrust you, or do nothing.

    line 8
  2. Distinctive:

    If reader, goal, or strength is unclear, ask 1–2 questions.

    line 16
  3. Distinctive:

    Use common words ("use", not "utilize").

    line 21
  4. Distinctive:

    Avoid idioms and slang that non-native readers may miss.

    line 22
  5. Distinctive:

    Use inclusive words: "everyone" not "guys", "they" not "he/she", "has X" not "suffers from X".

    line 23
  6. Distinctive:

    Put the main point in the first sentence: answer first, details next, background last.

    line 27
  7. Distinctive:

    Write paragraphs of 2–3 sentences.

    line 29
  8. Distinctive:

    Start list items and headings with the word that sets them apart.

    line 30
  9. Distinctive:

    Prefer facts to hype: replace "world-class", "cutting-edge", "revolutionary" with a number, spec, or result.

    line 35
  10. Distinctive:

    Delete filler: "very", "really", "In today's fast-paced world…", "We understand…".

    line 36
  11. Distinctive:

    Use honest levers: give value first, real proof from similar people, real credentials, real deadlines, shared goals.

    line 63
  12. Distinctive:

    Never invent numbers, reviews, testimonials, credentials, scarcity, or deadlines.

    line 69
  13. Distinctive:

    No guilt-trip opt-outs; use "No thanks".

    line 70

≈ “Common” is an estimate: at least 1 in 5 of the 308,232 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

It Isn't What You Write, It's What They Read

Every text is a negotiation for the reader's attention and trust: the reader can stop reading, distrust you, or do nothing. You win when you transfer knowledge clearly and earn agreement honestly.

Plan Before Writing

  • Define the information you're trying to communicate, what do you want the reader to know or understand.
  • Define the reader, what they already know and believe, and the ONE belief or action you want.
  • Work backward from that goal: list the steps of understanding the reader needs to reach it.
  • Set push strength: Inform (docs, guides, reports) → Convince (proposals, essays, emails) → Sell (ads, landing pages).
  • If reader, goal, or strength is unclear, ask 1–2 questions.

Use Plain Language

  • Target: an average 15-year-old understands it (~grade 8). Technical docs may assume domain basics (~grade 10); explain key terms in plain words on first use.
  • Use common words ("use", not "utilize"). Keep sentences short (~15 words average), active, one idea each. Simple is better.
  • Avoid idioms and slang that non-native readers may miss.
  • Use inclusive words: "everyone" not "guys", "they" not "he/she", "has X" not "suffers from X".

Short and Scannable

  • Put the main point in the first sentence: answer first, details next, background last.
  • Cut the first draft by about half. Keep only words that add meaning.
  • Write paragraphs of 2–3 sentences. Use headings that say something ("Prices start at $10", not "Pricing").
  • Start list items and headings with the word that sets them apart; vary how items begin.
  • Format and space for readability. Bold only key terms, and rarely.

Earn Trust

  • Prefer facts to hype: replace "world-class", "cutting-edge", "revolutionary" with a number, spec, or result.
  • Delete filler: "very", "really", "In today's fast-paced world…", "We understand…".
  • Costly signals persuade; cheap ones don't. Use specific numbers, guarantees, named sources, and admitted limits.
  • Reputation compounds: one hyped claim discounts everything else you write.
  • Skeptical-engineer test: if it sounds unbelievable, add a fact or cut it.
  • For critical texts, such as technical, academic or legal texts, always re-validate all factual claims are correct and reference proof using:
    1. primary sources when possible (first hand documented evidence);
    2. two or more secondary sources (research papers / reports); and
    3. established tertiary sources as an optional last resort (Wikipedia / established news outlets). Any website link must be validated before delivery (working and content matches description). Every quote must be a validated verbatim quote.

Lead the Reader (Scaled to Strength)

  • Speak their language: reuse the reader's own terms; mirror their tone and sensory words ("see", "hear", "feel") when known.
  • Pace, then lead: open with something the reader already agrees with, then move to the new point.
  • Match motivation: gains AND problems avoided; options AND steps; summary first, details layered; the reader's own judgment AND outside proof.
  • Answer the top 2–3 doubts before they arise: price, trust, need, fit, "why now". Use "Yes, and…" or "Even if…", acknowledge before redirecting, and reframe (cost → cost of doing nothing).
  • Presuppose only true next steps ("When you set this up…").
  • Let readers sort themselves: "New? Start here. Upgrading? Skip to…".

When Convincing or Selling

Pick structure by what the reader already knows:

  • Knows the problem → PAS: name the problem, show its real cost, offer the fix.
  • Unaware or needs teaching → AIDA: hook, why it matters, proof, clear call to action.
  • Comparing options → FAB: feature → what it does → why the reader cares.

Use honest levers: give value first, real proof from similar people, real credentials, real deadlines, shared goals.

Sell only: place a clear call to action midway and at the end, and risk reversal (guarantee, free trial) near the ask.

Red Lines

  • Never invent numbers, reviews, testimonials, credentials, scarcity, or deadlines.
  • No guilt-trip opt-outs; use "No thanks". No fear, shame, or targeting of children or vulnerable people.
  • Show full and recurring costs up front. Cancelling must be as easy as signing up.
  • Consent test: would the reader still agree if they knew the technique? If not, rewrite.
  • Flag for human proof: statistics, reviews, credentials, prices, and health, legal, or money claims.

Check Before Delivering

  • Could a 15-year-old (or a domain newcomer, for technical docs) explain each paragraph back?
  • Is the main point in the first sentence? Does every section beat "stop reading"?
  • Is every claim true and backed by something?
  • Is the information transfer focused and effective?
  • Is the information transfer noisy?

Output

Return the text. For rewrites, report 2–4 bullets: key changes, techniques used, claims needing proof.

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.