Audit or generate a project README against gold-standard best practices. Use when onboarding a project, after major changes, or to check README quality.
<skill_info> <name>nmblr:readme</name>
<summary>Audit an existing README against best practices or generate a new one from project context. Two modes: audit (default) reports gaps, generate scaffolds a complete README.</summary> </skill_info> <usage> <syntax>nmblr:readme</syntax> <syntax>nmblr:readme --generate</syntax> <syntax>nmblr:readme --fix</syntax> </usage> <options> <option name="--generate">Generate a new README from project context (overwrites existing)</option> <option name="--fix">Audit and automatically fix gaps (adds missing sections, does not rewrite existing content)</option> </options><gold_standard_checklist> The following checklist defines the gold-standard README structure, derived from The Good Docs Project, Best-README-Template, and patterns from Vault, Grafana, and Supabase.
| # | Section | What to check | Weight |
|---|---|---|---|
| 1 | Title + Description | H1 with project name. 1-2 sentence description answering "what is this?". A "why" statement explaining the problem it solves. | High |
| 2 | Built With |
| Quick-glance list of key technologies with links |
| Medium |
| 3 | Table of Contents | Present if README > 150 lines. Links resolve to actual headings. | Medium |
| 4 | Features | Scannable bullet list of capabilities (not tech stack) | High |
| 5 | Prerequisites | Tools and versions required to develop | High |
| 6 | Quick Start | Copy-pasteable commands from clone to running. No <placeholder> URLs — use real repo URL. | High |
| 7 | Project Structure | Directory tree with annotations explaining each directory's purpose | Medium |
| 8 | Development | Commands (build, lint, dev, CI). Environment variables table. Docker/services setup. | High |
| 9 | Architecture | High-level description of backend and frontend patterns and key libraries | Medium |
| 10 | Testing | How to run tests. How to write tests. Integration test setup if applicable. | High |
| 11 | API | Endpoint table or reference. At minimum, health/readiness endpoints. | Medium |
| 12 | Deployment | Environments, hostnames, how deploys are triggered | Medium |
| 13 | Contributing | How to get started. Workflow/process (branch naming, PR process). Code conventions. | High |
| 14 | Security | How secrets/auth/encryption are handled. Security contact if applicable. | Medium |
| 15 | Documentation | Pointer to docs/ or external docs. Table of doc types if using nmblr. | Low |
| 16 | Troubleshooting | 3-5 common issues and fixes | Medium |
| 17 | Getting Help | Where to file issues, ask questions, find docs | Low |
| 18 | License | Copyright or license statement | High |
| # | Check | What to look for |
|---|---|---|
| Q1 | No placeholders | No <repo-url>, <your-name>, {placeholder} left in content |
| Q2 | Real repo URL | Clone command uses actual git URL, not a placeholder |
| Q3 | Env file reference correct | References .env.example (or whatever actually exists), not a wrong filename |
| Q4 | Referenced files exist | All file paths mentioned in README actually exist on disk |
| Q5 | Makefile targets exist | All make X commands reference real Makefile targets |
| Q6 | ToC links resolve | Every ToC link matches an actual heading |
| Q7 | No sensitive values | No API keys, passwords, or secrets in examples |
| Q8 | Description has "why" | Intro explains the problem solved, not just "what" |
| Q9 | Commands are copy-pasteable | Quick Start works end-to-end without hidden steps |
| </gold_standard_checklist> |
<execution_instructions> When this skill is invoked, follow these steps based on the mode:
Read these files (skip any that don't exist):
README.mdCLAUDE.mdMakefile (or justfile, taskfile.yml).env.example (or env-example, .env.sample)package.json, go.mod, Cargo.toml, pyproject.toml (detect language).claude/nmblr/config.yaml.claude/nmblr/install-manifest.jsonFor each item in the Required Sections checklist:
For each item in the Quality Checks:
<.*>, {.*}, placeholder patternsmake targets from README, verify each exists in Makefilesk-, pk_)## README Audit Report
**Overall Score:** {X}/18 sections present, {Y}/9 quality checks passing
### Section Checklist
| # | Section | Status | Notes |
|---|---------|--------|-------|
| 1 | Title + Description | ✅ Present | |
| 2 | Built With | ❌ Missing | |
| ... | ... | ... | ... |
### Quality Checks
| # | Check | Status | Notes |
|---|-------|--------|-------|
| Q1 | No placeholders | ✅ Pass | |
| Q2 | Real repo URL | ⚠️ Fail | Line 29: `<repo-url>` |
| ... | ... | ... | ... |
### Recommendations
1. **[High]** Add "Built With" section — ...
2. **[Medium]** Add Table of Contents — README is {N} lines
3. ...
--generate)From the gathered files, determine:
config.yaml, package.json, go.mod, or directory nameCLAUDE.md overview or package.json descriptiongo.mod, package.json, Cargo.toml, etc..env.examplegit remote get-url origindocs/ directory structure.github/workflows/, .deployment/Use AskUserQuestion for anything that can't be auto-detected:
Produce a complete README following the gold-standard section order:
Write the generated README and run the audit checklist against it to confirm all sections are present and quality checks pass.
--fix)<repo-url> with actual repo URL from git remote)The fix mode is additive — it fills gaps but respects what's already written. It should never rewrite a section that already has substantive content.
List each change with before/after or addition summary. </execution_instructions>