| name | github-readme |
| description | This skill should be used when creating or revising a GitHub README for a software project, including section structure, onboarding flow, examples, and contribution guidance. |
GitHub README
Use this skill to produce a README that helps visitors decide quickly whether to use the project and how to get started.
Goal
A good GitHub README should answer, in order:
- What is this project?
- Why should I use it?
- How do I run it right now?
- How do I configure common cases?
- How do I contribute?
Workflow
- Identify audience and primary use case.
- Write a short value-first opening section.
- Add a runnable quickstart with copy-pastable commands.
- Add usage examples for the 1–3 most common tasks.
- Add configuration/reference sections only after core onboarding is complete.
- Add contributor guidance or link to
CONTRIBUTING.md.
- Run the README audit script and fix failures.
- If prose still feels dense, revise it for clarity and concision.
Suggested section order
Use this order by default (adapt as needed):
- Project name
- Short value proposition
- Features / capabilities
- Installation
- Quickstart / usage
- Configuration (if applicable)
- Development / testing
- Contributing
- License
Style constraints
- Prefer concrete examples over abstract claims.
- Keep setup commands in fenced code blocks.
- Keep each section focused on one user question.
- Avoid burying setup steps deep in prose.
- Use relative links for in-repo docs.
Audit script
Run the bundled checker:
ruby ~/.claude/skills/github-readme/scripts/github_readme_audit.rb README.md
Strict mode (stronger section expectations):
ruby ~/.claude/skills/github-readme/scripts/github_readme_audit.rb README.md --strict
For keyboard keys, collapsible sections, diagrams, or maps, read references/gfm-features.md only when needed. For models, SVG animation, swatches, or alerts, read references/gfm-media.md only when that richer rendering would materially help.
