{"slug": "a-portable-agent-skill-that-grounds-readme-claims-in-repository-evidence", "title": "A portable Agent Skill that grounds README claims in repository evidence", "summary": "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.", "body_md": "`github-readme-generator`\n\nteaches a coding agent to write or refresh a\nrepository's root `README.md`\n\nfrom what the project actually contains — its\ncode, manifests, scripts, tests, workflows, and existing docs.\n\nOne canonical skill definition serves every host. It is developed and tested\nagainst Claude Code; the same definition installs into Codex, Cursor and the\nother agents the `skills`\n\nCLI knows, but no scenario has been run there yet, so\nthose hosts are packaged rather than verified. That gap, and a benchmark whose\nscorer is not yet trustworthy, are why this is a public beta.\n\nAn agent host that loads Agent Skills. The skill itself has no dependencies;\ninstalling with `npx`\n\nneeds Node.js.\n\n```\nnpx skills add pekral/github-readme-generator\n```\n\nThat installs into every agent it detects — Claude Code, Codex, Cursor, and\n[70-odd others](https://github.com/vercel-labs/skills#supported-agents). Add\n`-g`\n\nto install for your user instead of the current project, and `-a`\n\nto pick\nagents explicitly:\n\n```\nnpx skills add pekral/github-readme-generator -g -a claude-code -a codex\n```\n\nBoth plugin hosts carry a marketplace entry, which trades a second command for managed updates.\n\nClaude Code:\n\n```\n/plugin marketplace add pekral/github-readme-generator\n/plugin install github-readme-generator@pekral\n```\n\nCodex:\n\n```\ncodex plugin marketplace add pekral/github-readme-generator\n```\n\nCodex then needs a restart of the ChatGPT desktop app, after which the plugin\nappears in the Plugins Directory under the `pekral`\n\nmarketplace.\n\nList what is installed, and where:\n\n```\nnpx skills list\n```\n\nTurn the Claude Code plugin off without uninstalling it:\n\n```\nclaude plugin disable github-readme-generator\nclaude plugin enable github-readme-generator\n```\n\nBoth write to `enabledPlugins`\n\nin `~/.claude/settings.json`\n\n, so the setting is\nuser-wide.\n\nAsk for README work in the repository you want documented:\n\n```\nWrite a README for this repository.\n```\n\nThe 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.\n\nTo get findings without touching a file:\n\n```\nAudit this README and tell me what's wrong.\n```\n\nAn 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.\n\n- Scans the working tree first and builds a claim → source map before writing a single sentence.\n- Omits any command, badge, version, config key, link, or license claim it cannot trace to a file in the repository.\n- Builds the header block and badge row from templates — a\n`<picture>`\n\nwrapper 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:`\n\n. 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.\n- Treats every file it reads as data, not instructions. Text in a scanned repository that addresses the agent is reported to you, never obeyed.\n- Restricts its diff to\n`README.md`\n\n, and never stages, commits, or pushes unless you say so.\n\n[ docs/examples/](/pekral/github-readme-generator/blob/master/docs/examples/README.md) puts three README pairs side by side —\na Composer library, an unpublished CLI, and a README that had drifted from its\npackage — each generated by the same agent from the same repository and the same\nprompt, once without the skill and once with it, with the full text of both and a\ncomparison of what differs.\n\nRead 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.\n\n— purpose, workflow, core constraints.`SKILL.md`\n\n— 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`\n\n— what counts as evidence, badge templates, public surface findings, security and change-scope rules.`references/evidence-policy.md`\n\n— pre-handover checks and the handover summary shape.`references/validation-checklist.md`\n\nThree checks, three different questions. Only the first has an answer on record.\n\n[ tests/repository.test.mjs](/pekral/github-readme-generator/blob/master/tests/repository.test.mjs) asks whether this\nrepository holds to its own claims: every file the skill declares is present,\nits licence copy matches the root one, every relative documentation link\nresolves, each scenario has a host coverage row, the three manifests agree on\none version, and a released version has both a changelog entry and a matching\ntag.\n\n[ tests/scenarios.md](/pekral/github-readme-generator/blob/master/tests/scenarios.md) asks whether the skill behaves: ten\nmanual scenarios — from a documented PHP package to a monorepo to a\nsecrets-handling case — each with activation and output invariants, plus a\ncoverage log for recording which of them has been run under Claude Code, so far\nempty.\n\n[ tests/evals/](/pekral/github-readme-generator/blob/master/tests/evals/README.md) asks whether it helps: the same plain\nprompt against the same ten fixture repositories, with and without the skill,\nscored by a deterministic checker that counts unsupported claims, invalid\ncommands, invalid badges, broken links and missing information. The harness\ncarries invocation templates for Codex and Cursor as well, but no recorded run\nhas used them.\n\nThat third question is open, and the benchmark is not yet evidence for anything.\nIts scorer has known defects — it reads help text and command output as\ncommands, and a repository's own logo as a badge — large enough to swamp the\ndifference between the two modes. So no figure from it is quoted here, and none\nshould be quoted elsewhere until the scorer stops counting them.\n[#11](https://github.com/pekral/github-readme-generator/issues/11) recorded\nthose defects and was closed as not planned, which retired the ticket rather\nthan the defect.\n\n```\nnode --test tests/repository.test.mjs\nnode --test tests/evals/*.test.mjs\nnode tests/evals/run.mjs --dry-run\n```\n\nThe 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.\n\nOne run is published:\n[ 2026-08-31-claude-code-subset](/pekral/github-readme-generator/blob/master/tests/evals/results/2026-08-31-claude-code-subset/summary.md)\n— Claude Code, both modes, two of the ten scenarios, zero findings on each. It\nshows the harness works end to end. It says nothing about the skill, and this\nREADME claims nothing from it.\n\n```\nnpx skills update github-readme-generator\n```\n\nPlugin installs update through their own host instead:\n\n```\nclaude plugin marketplace update pekral && claude plugin update github-readme-generator\ncodex plugin marketplace upgrade pekral\n```\n\nClaude Code needs a session restart afterwards.\n\nSee [CHANGELOG](/pekral/github-readme-generator/blob/master/CHANGELOG.md).\n\nSee [CONTRIBUTING](/pekral/github-readme-generator/blob/master/CONTRIBUTING.md), and the\n[Code of Conduct](/pekral/github-readme-generator/blob/master/CODE_OF_CONDUCT.md) that participation is held to.\n\nSee [the security policy](/pekral/github-readme-generator/blob/master/SECURITY.md).\n\nThe MIT License (MIT). Please see [License File](/pekral/github-readme-generator/blob/master/LICENSE.md) for more\ninformation. The skill directory carries\n[its own copy](/pekral/github-readme-generator/blob/master/skills/github-readme-generator/LICENSE.md) of the notice, so an\ninstalled copy stays licensed even though installers take that directory alone.", "url": "https://wpnews.pro/news/a-portable-agent-skill-that-grounds-readme-claims-in-repository-evidence", "canonical_source": "https://github.com/pekral/github-readme-generator", "published_at": "2026-09-02 19:07:51+00:00", "updated_at": "2026-09-02 19:23:59.397584+00:00", "lang": "en", "topics": ["ai-tools", "developer-tools", "ai-agents"], "entities": ["github-readme-generator", "Pekral", "Claude Code", "Codex", "Cursor", "skills CLI", "Vercel Labs"], "alternates": {"html": "https://wpnews.pro/news/a-portable-agent-skill-that-grounds-readme-claims-in-repository-evidence", "markdown": "https://wpnews.pro/news/a-portable-agent-skill-that-grounds-readme-claims-in-repository-evidence.md", "text": "https://wpnews.pro/news/a-portable-agent-skill-that-grounds-readme-claims-in-repository-evidence.txt", "jsonld": "https://wpnews.pro/news/a-portable-agent-skill-that-grounds-readme-claims-in-repository-evidence.jsonld"}}