Readme Pass

readme-pass

Make the README useful before making it pretty. Optimize for a distracted reader who wants to know what the project does, how to install it, and whether it fits their stack.

Workflow

1. Read the repository instructions, README, installer files, and manifest. Do not document unsupported behavior.
2. Find existing brand assets before generating a banner. Check assets/, public/, docs/, logos, and brand files.
3. Cut before adding. Remove repeated claims, generic motivation, stale implementation detail, and sections that restate a table.
4. Put the sections in this order when the project supports them:
   • one-line value
   • agent-first install
   • core workflow or example
   • included capabilities
   • compatibility
   • advanced setup and safety
   • credits and license
5. Apply the writing skill. Preserve facts, commands, links, names, and licenses.
6. Add presentation only after the content is lean.
7. Verify commands, anchors, links, supported operating systems, and the changed diff.

Attention budget

• Answer "what is this?" in one sentence.
• Keep paragraphs to one idea and usually one to three sentences.
• Prefer a short table for repeated mappings such as skill to purpose or host to support.
• Show the main workflow once. Link or move deep internals instead of explaining them twice.
• Put copyable prompts and commands before implementation details.
• Keep examples small enough to understand without scrolling back.
• Delete any sentence that only announces importance or repeats the heading.
• Do not preserve prose merely because it already exists.

Agent-first install

When setup changes the user's machine, place a copyable agent-install prompt before manual commands. Tell the agent to:

• detect the operating system and select a documented installer;
• read repository instructions before mutation;
• preserve local changes and user-owned configuration;
• run the documented dry-run or preview first;
• continue only when no blocker remains;
• verify the installed capability and report backups, skips, failures, and unverified steps.

Use only commands and operating systems present in the repo. Keep manual commands below the prompt as a fallback.

Presentation

Preserve existing branding. Add a banner, badges or navigation only when the requested presentation work benefits from them. A text cleanup does not require image generation. Use a plain heading when no visual identity is available.

Writing rules

Use sentence-case headings, plain words, and concrete claims. Avoid em dashes, decorative triads, boldface spam, empty promises, and repeated feature lists.

Delivery

• Stage files only when staging, committing or PR preparation is requested.
• Inspect the changed content for private information before an authorized publication.
• Report what was cut, what moved, what was added, and what remains unverified.