A portable Agent Skill that grounds README claims in repository evidence

A new open-source Agent Skill, github-readme-generator, enables coding agents to write or refresh a repository's README.md based on actual repository contents, omitting any claim it cannot trace to a file. Developed by Pekral and tested against Claude Code, it installs into Codex, Cursor, and 70-odd other agents via the skills CLI, though only Claude Code is verified. The skill is in public beta because the benchmark scorer is not yet trustworthy.

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. An agent host that loads Agent Skills. The skill itself has no dependencies; installing with npx needs Node.js. npx skills add pekral/github-readme-generator That installs into every agent it detects — Claude Code, Codex, Cursor, and 70-odd others https://github.com/vercel-labs/skills supported-agents . 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 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. 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. 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. - 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. docs/examples/ /pekral/github-readme-generator/blob/master/docs/examples/README.md 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. — purpose, workflow, core constraints. SKILL.md — header block, section order, what to cut, per-ecosystem rules, keeping examples true to the package's own domain, and style. references/readme-structure.md — what counts as evidence, badge templates, public surface findings, security and change-scope rules. references/evidence-policy.md — pre-handover checks and the handover summary shape. references/validation-checklist.md Three checks, three different questions. Only the first has an answer on record. tests/repository.test.mjs /pekral/github-readme-generator/blob/master/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 /pekral/github-readme-generator/blob/master/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/ /pekral/github-readme-generator/blob/master/tests/evals/README.md 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 https://github.com/pekral/github-readme-generator/issues/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 /pekral/github-readme-generator/blob/master/tests/evals/results/2026-08-31-claude-code-subset/summary.md — 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. 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. See CHANGELOG /pekral/github-readme-generator/blob/master/CHANGELOG.md . See CONTRIBUTING /pekral/github-readme-generator/blob/master/CONTRIBUTING.md , and the Code of Conduct /pekral/github-readme-generator/blob/master/CODE OF CONDUCT.md that participation is held to. See the security policy /pekral/github-readme-generator/blob/master/SECURITY.md . The MIT License MIT . Please see License File /pekral/github-readme-generator/blob/master/LICENSE.md for more information. The skill directory carries its own copy /pekral/github-readme-generator/blob/master/skills/github-readme-generator/LICENSE.md of the notice, so an installed copy stays licensed even though installers take that directory alone.