agentsclimarketplace
Sign in

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

Install
npx -y skills add mickzijdel/dev-hooks --skill github-readme

Assembled 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:

  1. What is this project?
  2. Why should I use it?
  3. How do I run it right now?
  4. How do I configure common cases?
  5. How do I contribute?

Workflow

  1. Identify audience and primary use case.
  2. Write a short value-first opening section.
  3. Add a runnable quickstart with copy-pastable commands.
  4. Add usage examples for the 1–3 most common tasks.
  5. Add configuration/reference sections only after core onboarding is complete.
  6. Add contributor guidance or link to CONTRIBUTING.md.
  7. Run the README audit script and fix failures.
  8. If prose still feels dense, apply the readability skill 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:

  1. Return the revised README content.
  2. Summarize what changed in onboarding flow.
  3. 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/

scripts/

Gives 0 of the 12 instructions most readme changelog skills give in 612 tokens

Counted across 472 of the 478 authors here whose files we hold, read 2026-08-07

  • Follow the keep a changelog formatin 31 of 472, across 26 files
  • Run from the git repository rootin 20 of 472, across 7 files
  • Save output directly to CHANGELOG.mdin 20 of 472, across 7 files
  • Group commits into logical categoriesin 19 of 472, across 6 files
  • Review the generated changelog before publishingin 19 of 472, across 6 files
  • Omit empty sectionsin 19 of 472
  • Apply changelog guidelines and brand voicein 18 of 472, across 5 files
  • Exclude internal commits like refactoring and testsin 18 of 472, across 5 files
  • Specify date ranges for focused changelogsin 17 of 472, across 4 files
  • Convert technical commits into customer languagein 17 of 472, across 4 files
  • Provide a migration guide for breaking changesin 15 of 472, across 10 files
  • Group commits by conventional commit typein 13 of 472

Said here and by no other author read

  • identify the audience and primary use case
  • write a short value-first opening section
  • add usage examples for common tasks
  • add configuration sections after core onboarding
  • add contributor guidance or link to CONTRIBUTING.md
  • return the revised README content

Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once. Length counted with cl100k_base; the agent that loads this file may tokenize it differently.

Keep looking

Skills are one crate of 326,512. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.