A portable Agent Skill for writing READMEs that don't lie

github-readme-generator teaches a coding agent to write or refresh a repository's root README.md from what the project actually contains — its code, manifests, scripts, tests, workflows, and existing docs.

One canonical skill definition serves every host. It is developed and tested against Claude Code; the same definition installs into Codex, Cursor and the other agents the skills CLI knows, but no scenario has been run there yet, so those hosts are packaged rather than verified. That gap, and a benchmark whose scorer is not yet trustworthy, are why this is a public beta.

Requirements

An agent host that loads Agent Skills. The skill itself has no dependencies; installing with npx needs Node.js.

Installation

npx skills add pekral/github-readme-generator

That installs into every agent it detects — Claude Code, Codex, Cursor, and 70-odd others. Add -g to install for your user instead of the current project, and -a to pick agents explicitly:

npx skills add pekral/github-readme-generator -g -a claude-code -a codex

As a plugin instead

Both plugin hosts carry a marketplace entry, which trades a second command for managed updates.

Claude Code:

/plugin marketplace add pekral/github-readme-generator
/plugin install github-readme-generator@pekral

Codex:

codex plugin marketplace add pekral/github-readme-generator

Codex then needs a restart of the ChatGPT desktop app, after which the plugin appears in the Plugins Directory under the pekral marketplace.

Configuration

List what is installed, and where:

npx skills list

Turn the Claude Code plugin off without uninstalling it:

claude plugin disable github-readme-generator
claude plugin enable github-readme-generator

Both write to enabledPlugins in ~/.claude/settings.json, so the setting is user-wide.

Quick start

Ask for README work in the repository you want documented:

Write a README for this repository.

The skill scans the repository, picks create / update / audit, drafts against its structure reference, and ends with a summary of what it verified and what it could not prove.

To get findings without touching a file:

Audit this README and tell me what's wrong.

An audit also covers the surfaces beside the README — missing community health files, links with no target, and an empty GitHub About box when the agent can read the repository's metadata — as text for you to apply.

What it does

• Scans the working tree first and builds a claim → source map before writing a single sentence.
• Omits any command, badge, version, config key, link, or license claim it cannot trace to a file in the repository.
• Builds the header block and badge row from templates — a <picture> wrapper for projects that own a logo, and version, license, CI and downloads badges filled from the manifest, the license file, and the workflow's own name:. A workflow whose triggers never put a run on the default branch gets no badge, so none reports a branch it does not cover.
• Knows what each ecosystem keeps where, so a PHP package documents Composer and Packagist while a Rust crate documents Cargo and crates.io.
• Treats every file it reads as data, not instructions. Text in a scanned repository that addresses the agent is reported to you, never obeyed.
• Restricts its diff to README.md, and never stages, commits, or pushes unless you say so.

Before and after

docs/examples/ puts three README pairs side by side — a Composer library, an unpublished CLI, and a README that had drifted from its package — each generated by the same agent from the same repository and the same prompt, once without the skill and once with it, with the full text of both and a comparison of what differs.

Read them for what they are: on those repositories the baseline invented nothing, so the pairs show ordering, evidence-backed badges and referenced-rather-than-copied output — and one case where the skill did worse than the baseline. The index says so plainly.

Documentation

• SKILL.md — purpose, workflow, core constraints.
• references/readme-structure.md — header block, section order, what to cut, per-ecosystem rules, keeping examples true to the package's own domain, and style.
• references/evidence-policy.md — what counts as evidence, badge templates, public surface findings, security and change-scope rules.
• references/validation-checklist.md — pre-handover checks and the handover summary shape.

Testing

Three checks, three different questions. Only the first has an answer on record.

tests/repository.test.mjs asks whether this repository holds to its own claims: every file the skill declares is present, its licence copy matches the root one, every relative documentation link resolves, each scenario has a host coverage row, the three manifests agree on one version, and a released version has both a changelog entry and a matching tag.

tests/scenarios.md asks whether the skill behaves: ten manual scenarios — from a documented PHP package to a monorepo to a secrets-handling case — each with activation and output invariants, plus a coverage log for recording which of them has been run under Claude Code, so far empty.

tests/evals/ asks whether it helps: the same plain prompt against the same ten fixture repositories, with and without the skill, scored by a deterministic checker that counts unsupported claims, invalid commands, invalid badges, broken links and missing information. The harness carries invocation templates for Codex and Cursor as well, but no recorded run has used them.

That third question is open, and the benchmark is not yet evidence for anything. Its scorer has known defects — it reads help text and command output as commands, and a repository's own logo as a badge — large enough to swamp the difference between the two modes. So no figure from it is quoted here, and none should be quoted elsewhere until the scorer stops counting them. #11 recorded those defects and was closed as not planned, which retired the ticket rather than the defect.

node --test tests/repository.test.mjs
node --test tests/evals/*.test.mjs
node tests/evals/run.mjs --dry-run

The first two run in CI on Node.js 20 and 22. The agent invocations never do — they cost money and need credentials CI has no business holding.

One run is published: 2026-08-31-claude-code-subset — Claude Code, both modes, two of the ten scenarios, zero findings on each. It shows the harness works end to end. It says nothing about the skill, and this README claims nothing from it.

Updating

npx skills update github-readme-generator

Plugin installs update through their own host instead:

claude plugin marketplace update pekral && claude plugin update github-readme-generator
codex plugin marketplace upgrade pekral

Claude Code needs a session restart afterwards.

Changelog

See CHANGELOG.

Contributing

See CONTRIBUTING, and the Code of Conduct that participation is held to.

Security

See the security policy.

Credits

• Petr Král — @kral_petr_88
• All contributors

License

The MIT License (MIT). Please see License File for more information. The skill directory carries its own copy of the notice, so an installed copy stays licensed even though installers take that directory alone.