| name | give-a-ship |
| description | Audit or improve public repository documentation for impatient, low-context readers. Use when a README, docs landing page, or repository presentation needs a clearer value proposition, better screenshots, faster Quick start, stronger links, tighter writing, or a ruthless skimmability pass. |
Give a Ship
Make repository documentation earn attention.
Before evaluating or editing documentation, read the ship check. Apply it with judgment; not every repository needs every section.
Choose the mode
- Audit: When the user asks to review, evaluate, or diagnose, report the highest-impact attention leaks. Do not edit files.
- Improve: When the user asks to rewrite, fix, or build the documentation, make the changes and verify them.
Do not infer permission to change repository settings, publish, or create promotional assets from an audit request.
Inspect before judging
Read the README and repository description, then inspect the docs, existing media, package metadata, releases, examples, contribution guidance, and linked destinations that affect a newcomer's path. For a remote repository, open the rendered repository page when possible; source Markdown alone does not reveal the real first impression.
Identify:
- The primary reader.
- The one thing the project helps them do.
- The fastest credible proof.
- The shortest path to a successful first run.
Do not invent features, maturity, commands, benchmarks, screenshots, or support claims. Separate what works now from roadmap material.
Run three passes
1. The ten-second skim
Look only at the title, tagline, top links, first visual, and major headings. Decide whether a low-context reader can tell what the project is, why it matters, and where to start.
2. The first-success path
Follow the Quick start exactly when safe and proportionate. Check prerequisites, commands, links, expected result, and whether different audiences have clearly labeled paths.
3. The trust pass
Check whether screenshots, status statements, examples, release information, and links are current and honest. Prefer specific evidence over adjectives.
Improve ruthlessly
- Put the core value before implementation detail or project history.
- Use every screenshot that answers a distinct reader question; stop when the next image merely repeats one. Favor real, current product views with useful alt text and short captions.
- Make
Quick start an obvious heading. In a long README, link to it near the top.
- Prefer copy-pasteable steps followed by the result the reader should see.
- Add high-value links where readers need them: demo, docs, examples, releases, roadmap, issues, contributing, security, and license. Do not add link clutter.
- Write headings as signposts and front-load paragraphs. Cut throat-clearing, repeated summaries, generic praise, and agentic filler.
- Preserve useful depth by moving it behind links or disclosure blocks when it interrupts the main path.
- Keep the project's voice. Punchy does not mean sterile, rude, or vague.
When a missing screenshot would materially improve the README, specify exactly what state and outcome to capture. Do not fabricate a product screenshot.
Report the result
Keep the handoff skimmable:
- Verdict: one sentence.
- Biggest attention leaks: no more than three, ordered by reader impact.
- Recommended shape: the proposed information order, only when restructuring is needed.
- Changes and checks: for improvement work, summarize edits and what was verified.
Mention lower-priority polish only when it is likely to change reader behavior.
