readme-creator
Original：🇺🇸 English
Translated
Writes or rewrites README.md files tailored to the project type (CLI, library, app, framework, monorepo, or skill bundle). Discovers project context, selects the right structure, writes section by section, and validates against quality checks. Use when creating a README, writing a README from scratch, rewriting a bad README, bootstrapping project documentation, or asking "write a README for this project."
2installs
Sourcemblode/agent-skills
Added on
NPX Install
npx skill4agent add mblode/agent-skills readme-creatorTags
Translated version includes tags in frontmatterSKILL.md Content
View Translation Comparison →README Creator
Write or rewrite a README.md tailored to the project type and audience.
Reference Files
| File | Read When |
|---|---|
| Phase 3: choosing structure and writing sections for a specific project type |
| Phase 5: validating the finished README against quality standards |
| Phase 4: adding badges after the main content is written |
README Workflow
Copy this checklist to track progress:
text
README progress:
- [ ] Phase 1: Discover project context
- [ ] Phase 2: Choose README structure
- [ ] Phase 3: Write sections
- [ ] Phase 4: Add badges and extras
- [ ] Phase 5: Validate qualityPhase 1: Discover project context
Read the project before asking questions. Explore files to detect the project type:
- Read ,
package.json,Cargo.toml,pyproject.toml, or equivalent for name, description, license, dependencies, scripts, and bin field.go.mod - Read existing README.md (if rewriting).
- Scan directory structure to understand architecture.
Classify into one of six project types:
| Type | Signals |
|---|---|
| CLI tool | |
| Library / package | |
| Web app | |
| Framework | Plugin/middleware architecture, configuration API, extensibility points |
| Monorepo | |
| Skill bundle | |
Ask the user only for what cannot be discovered from the code:
- What problem does the project solve? (the "why")
- Who is the target audience?
- Any sections to include or exclude?
Phase 2: Choose README structure
Load .
references/section-templates.mdSelect sections based on the project type:
| Section | CLI | Library | App | Framework | Monorepo | Skills |
|---|---|---|---|---|---|---|
| Title + one-liner | yes | yes | yes | yes | yes | yes |
| Badges | yes | yes | -- | yes | yes | -- |
| Features / highlights | yes | yes | yes | yes | -- | yes |
| Install | yes | yes | -- | yes | yes | -- |
| Quick start / usage | yes | yes | yes | yes | yes | yes |
| Options / API reference | yes | yes | -- | yes | -- | -- |
| Configuration | opt | opt | yes | yes | opt | -- |
| Environment variables | -- | -- | yes | -- | -- | -- |
| Packages table | -- | -- | -- | -- | yes | -- |
| Skills table | -- | -- | -- | -- | -- | yes |
| Requirements | yes | yes | opt | yes | opt | -- |
| Contributing | opt | opt | opt | opt | opt | opt |
| License | yes | yes | yes | yes | yes | opt |
Phase 3: Write sections
Load . Write each section following the template for the detected project type.
references/section-templates.mdKey principles:
- Title is the project name. One-liner directly below, no heading.
- Feature list above the fold (before Install) so readers see value before effort.
- Install: single fastest path first. for CLIs,
npm install -gfor libraries.npm install - Usage: 3-5 runnable examples, simplest first. Real values, not or
foo.example - Every code block must be copy-pasteable and runnable without modification.
- A reader should be able to install and run something within 60 seconds.
- Progressive disclosure: basic first, advanced later or in linked docs.
Phase 4: Add badges and extras
Load . Add badges only if the project is published to a registry. Place directly below the title and one-liner. Maximum 4 badges.
references/badges-and-shields.mdSkip badges entirely for private apps, unpublished projects, and skill bundles.
Phase 5: Validate quality
Load . Run through every applicable check. Fix issues before finalizing.
references/quality-checklist.mdAfter fixes, reread the README top to bottom to confirm it flows naturally.
Anti-patterns
- Do not write a README longer than the codebase warrants
- Do not include a table of contents for READMEs under 100 lines
- Do not use "About" or "Introduction" as the first heading
- Do not ship the default create-next-app or create-vite README
- Do not include badges for unpublished projects
- Do not include a "Features" section that restates the one-liner
- Do not write "This project is..." or "This is a..." — describe what it does directly
- Do not include empty Contributing or Acknowledgements sections
- Do not use ,
foo, orbaras example valuestest
Skill Handoffs
| When | Run |
|---|---|
| After README is written, audit prose quality | |
| If project needs AGENTS.md / CLAUDE.md | |