READMEs AI Can Explain

A problem-first README skill for Amplifier agents

The Frame

Your AI writes a tidy README — and fails the one reader who matters now

Agents ship polished-looking READMEs that open with “A tool that…” and a feature list. It looks done. It isn’t.

Because the reader who matters most isn’t a person anymore.

“A feature list is not an opening.”

Principle 1 — Problem before solution, from SKILL.md

The Tension

People paste your repo into an AI and ask “what is this?”

A vague feature-list README makes that AI answer wrong — and the misrepresentation propagates from there.

So clarity had to become something you could actually check.

Paste your README into an AI and ask “explain this project to me.”

The explain-it-back test — “what most people will actually do”

The Proof

cpark4x shipped a real, reusable fix — installable in one line

The amplifier-writing-readme skill bundle is public on GitHub: a README-writing skill for Amplifier agents, not a proposal.

And it carries a specific, testable definition of “clear.”

# cpark4x/amplifier-writing-readme — public, branch main
amplifier bundle add \
  git+https://github.com/cpark4x/amplifier-writing-readme@main

7

commits (created 2026-03-15)

5

principles enforced

The Mechanism

The sharpest gate: if an AI can’t explain it, the README failed

The explain-it-back test is one of four quality tests — and the one that mirrors how repos are really consumed.

But a good test knows when not to fire.

Substitution test — swap in another project’s name; does it still read true?
“So what?” test — does each line earn its place?
30-second test — can a reader get it fast?
Explain-it-back test — paste it into an AI and see.

The Mechanism

Evaluate first, don’t bulldoze

Before rewriting, the skill runs the quality tests. If the README passes, it suggests 1–2 precise edits instead — because a precise edit beats a rewrite every time.

That discipline is what lets it judge five very different repos.

Run the tests first on the existing README.
If it passes, don’t rewrite — suggest 1–2 improvements.
Look for buried gold in the vision docs.
Preserve voice — and compress Built By.

The Test Bed

Pointed at five real repos of different types

Not toy examples — a consumer podcast tool, two dev-tool workflows, a CLI generator, and a kids-nutrition app.

One skill, five very different jobs. Would it over-correct?

ridecastPersonal podcast factory — consumer product
amplifier-change-advisorMulti-lens PR review workflow — dev tool
amplifier-doc-driven-devAlignment bundle / workflow
deckgenHTML presentation generator — CLI
nouriKids-nutrition consumer app

The Payoff

It discriminated correctly — rewrite, edit, or leave alone

Full rewrites for the feature-catalog READMEs, surgical edits that surfaced buried gold, and a leave-alone for the one already worth copying.

Clarity-as-a-test produced judgment, not blanket rewrites.

Full rewrite deckgen · amplifier-doc-driven-dev Feature-list openings replaced with problem-first ones (commits fe56dcc, dda74c5).
Surgical edit amplifier-change-advisor · nouri Added a “blast radius” example & compressed Built By (7ba4df6); kept nouri’s dad-voice.
Leave alone ridecast Its opening is the very example SKILL.md cites as “what good looks like.” No README commit.

The Takeaway

The skill even sharpened itself from those runs

Lessons from the tests folded back into its own guidance — a reusable, self-improving discipline for writing READMEs an AI can actually explain.

Write for the reader who matters now: another AI.

bca8312 — added evaluate-first guidance, voice preservation, consumer-product patterns.
7f191e5 — added buried-gold and compress-built-by guidance from the change-advisor test.

Sources

Research Methodology

Data as of: skill last pushed 2026-03-17; deck PR #80 merged 2026-03-20 (regenerated 2026-07-14 local).

Feature status: Active — cpark4x/amplifier-writing-readme public, main branch, 7 commits.

Research performed (GitHub CLI + git):

gh repo view cpark4x/amplifier-writing-readme --json name,description,createdAt,pushedAt,defaultBranchRef,isPrivate
gh api repos/cpark4x/amplifier-writing-readme/contents/skills/writing-readmes/SKILL.md --jq '.content' | base64 -d (Five Principles, Quality Tests, Before You Rewrite)
gh api repos/cpark4x/amplifier-writing-readme/commits (7 commits: bf22b98 → 05e8a38; incl. bca8312, 7f191e5)
gh api repos/cpark4x/deckgen/contents/README.md?ref=fe56dcc~1 | base64 -d (emoji feature-list before / problem-first after)
gh api repos/cpark4x/amplifier-doc-driven-dev/commits | grep -i readme (rewrite dda74c5)
gh api repos/cpark4x/amplifier-change-advisor/contents/README.md | base64 -d | grep -i blast (surgical edit 7ba4df6)
gh api repos/cpark4x/nouri/contents/README.md | base64 -d | head; gh api repos/cpark4x/ridecast/commits | grep -i readme (no result = leave-alone)
gh pr view 80 --repo ramparte/amplifier-stories --json number,title,author,mergedAt,files

Gaps: The deck author’s numeric 1–10 before/after README scores could not be reproduced from any eval harness or log; only the treatments (rewrite / surgical / leave-alone) are independently verified against real README commits and content. Repos were inspected remotely via gh (not cloned locally).

Primary contributors: cpark4x (Chris Park) — skill author & PR #80 opener; Sam Schillace & sadlilas — deck regeneration/promotion in amplifier-stories.