hipson-readme-craft

Hipson README Craft

Use this skill to turn repository evidence into a clear, useful, good-looking README without drifting into marketing fluff.

Core Workflow

1. Inspect source truth before writing:
   • existing README.md, pyproject.toml, package.json, or equivalent manifest;
   • CLI entrypoints, public APIs, examples, tests, docs, and configuration files;
   • current setup commands and verification commands.
2. Define the README job:
   • first-time install and quick start;
   • contributor onboarding;
   • product positioning for public release;
   • internal handoff or operator guide.
3. Lead with the shortest accurate value proposition.
4. Put runnable commands early, and keep them copy-pasteable.
5. Preserve tested behavior and avoid inventing features, flags, URLs, badges, compatibility claims, benchmarks, or roadmap promises.
6. Keep visual polish lightweight: strong section names, scannable bullets, code blocks, small status tables, and optional badges only when backed by repository evidence.
7. End with practical development, safety, and troubleshooting notes when they help users succeed.
8. Verify all commands and links that can be checked locally.

Recommended Structure

For CLI and developer-tool repos, prefer this order:

# Project Name

One-sentence value proposition.

## Why It Exists
## Features
## Install
## Quick Start
## Common Commands
## Configuration
## Workflow
## Safety / Privacy
## Development
## CI / Release

Use fewer sections for small projects. Add architecture, API, screenshots, examples, troubleshooting, or migration notes only when the repo supports them.

Quality Bar

• The first screen should answer: what is this, who is it for, and how do I try it?
• Every claim should trace to source, tests, docs, or visible repo behavior.
• Setup should distinguish required steps from optional provider/API-key setup.
• Commands should use the repo's preferred tooling, such as uv, pnpm, npm, pytest, ruff, or project scripts.
• Security-sensitive docs should explicitly say where secrets belong and what should never be committed.
• Tone should be confident, concrete, and developer-friendly.