mcpField
W
write-readme

write-readme

github.com/wilbeibiDevelopment240 installsUpdated 3d ago
Repository

About write-readme

A skill for writing concise READMEs that help readers understand a project, decide when to use it, and get started. It prioritizes practical value, common usage, and clear boundaries over repeated inventories or promotional claims.

Key features

  1. 01Gather audience and project context
  2. 02Classify the project type
  3. 03Prioritize value and quickstart
  4. 04State boundaries and non-goals
  5. 05Remove repetition and unsupported claims

Use cases

  1. 01Drafting a README for a new library
  2. 02Revising a CLI or agent tool README
  3. 03Making setup and common usage easy to find

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/wilbeibi/wilbeibi-skills --skill write-readme

After installing, type/write-readmein Claude Code to confirm it loaded.

Bundled filesREFERENCE.md

Details

From the project README

write-readme

Write READMEs for readers with short attention: what is it, when do I use it, how do I start, what should I not expect.

Workflow

  1. Gather context: problem solved, target audience, current alternatives, sharpest value/proof, and non-goals.
  2. Classify once: library, CLI/tool, or agent tool. Ask if unclear.
  3. Cut before adding: remove duplicated inventories, badge noise, marketing claims, and copied --help tables.
  4. Draft in inverted-pyramid order: plain value, install, common use, boundaries, then optional reference.
  5. Put the most common invocation or import path in the first 30 lines.
  6. Use REFERENCE.md only for section choices, not as a required template.
  7. Final pass: every line must answer a likely reader question or change their next action.

Opening Rules

  • Lead with concrete value: metric, named capability, or sharp differentiator.
  • Never start with "A library/tool that..."; show the reader's outcome first.
  • Name the target audience and the non-goal early.
  • Claims need evidence or a methodology note.
  • Be genuine. Avoid ad-copy words like "seamless", "instant", "powerful", and "no re-explaining" unless the README proves them.
  • Prefer a normal-user voice over a product-sheet voice. A first-person note is fine when it names a real daily use; cut it if it turns into taste-making, hype, or a joke.
  • Open on the human moment the tool fixes, then name the mechanism. "I was here, this helped" beats "this solution enables..."

Ruthless Cut Pass

Delete or compress:

  • Repeated supported-platform or integration lists. Name them once, where they affect command syntax or installation.
  • Full flag/reference tables when --help, generated docs, or package docs already cover them.
  • Badges that do not affect trust or installation decisions.
  • Separate "What it does", "Features", and "Why" sections that restate the same sentence.
  • Long caveats. Keep boundaries, but write them as short operational facts.

Agent Tools

For CLIs meant to be invoked by coding agents:

  • Treat the README as the tool's function signature.
  • Show exact command shape, required args, important flags, and expected success/error shape when that output helps the agent verify work.
  • Add Not for X guardrails so agents avoid misuse.
  • Keep the core interface scannable without expanding <details>.

Non-Negotiables

  • Install/quickstart before architecture.
  • Limitations get their own heading, not a buried caveat.
  • Broad support claims must name platforms, formats, languages, or integrations.
  • Troubleshooting belongs in the README only when the failure is common and actionable.
  • Use <details> only for advanced config, raw data, methodology, or alternative setup.
  • No marketing adjectives; use numbers, examples, and named evidence.
  • No dramatic connector cadence as a default voice: em dashes, arrows, and "not just X, but Y" need a reason.

See REFERENCE.md for templates, badge patterns, screenshot guidance, tone notes, and final-pass prompts.

Comments

Markdown supported