Github readme
Skill mickzijdel/dev-hooks/plugins/writing/skills/github-readme
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.From its SKILL.md
npx -y skills add mickzijdel/dev-hooks --skill github-readmeAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
2.8 KB, 612 tokens by cl100k_base, as published. Nobody here has run it
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, apply the
readabilityskill afterward.
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:
uv run scripts/github_readme_audit.py README.md
Strict mode (stronger section expectations):
uv run scripts/github_readme_audit.py README.md --strict
The script checks for:
- H1 presence
- Core onboarding sections (installation, usage/quickstart)
- License section
- Command code blocks for setup/use
- Intro length guardrail
- Optional table-of-contents reminder on very long files
Output expectations
When using this skill for a user task:
- Return the revised README content.
- Summarize what changed in onboarding flow.
- Note any missing information that requires user input (for example, deployment steps or support policy).
Advanced GFM features
GitHub Flavored Markdown supports features beyond standard markdown — <kbd> key caps,
<details> collapsibles, Mermaid diagrams, GeoJSON maps, STL viewers, animated SVG via
<foreignObject>, color swatches, and > [!NOTE]-style alerts. When a README would benefit
from one, read references/gfm-advanced.md for the syntax and
the gotchas. Use them only where they add genuine value.
Credit: Adapted verbatim from Nate Berkopec's dotfiles.
What ships with it: 3 files
10.9 KB alongside SKILL.md, 1 of them executable
references/
- checklist.md733 B
- gfm-advanced.md3.7 KB
scripts/
- github_readme_audit.pyruns6.5 KB