Skip to content

write-project-readme

skillLast commit

Install an evidence-based project README skill for Codex and Claude Code.

Open productSource
Role
Agent workflow design and automation engineering
Scope
Agent workflow, validation automation, and packaging
Status
Published npm package

Problem

README generators often preserve stale claims or produce generic sections because they do not inspect the actual project or distinguish evidence from inference.

Constraints

  1. C1

    The skill may edit only the root README.

  2. C2

    Features, commands, compatibility, status, URLs, metrics, and license terms cannot be invented.

  3. C3

    Applications, packages, APIs, CLIs, monorepos, datasets, and skills require different reading flows.

Architecture

Repository evidence inventory; project-type/quality references and authoring workflow; deterministic README checker plus npm installer/tests.

01

Skill workflow

Repository evidence inventory.

02

Automation

Project-type/quality references and authoring workflow.

03

Verification

Deterministic README checker plus npm installer/tests.

Decisions

D1

Treat the old README as evidence to verify not a template to preserve

Treat the old README as evidence to verify, not a template to preserve.

D2

Classify facts as verified inferred or unknown

Classify facts as verified, inferred, or unknown.

D3

Enforce a full-document output contract

Enforce a full-document output contract rather than allowing a badge-only or single-section patch.

Contribution

  • Defined evidence priority and project-type routing.
  • Bundled comprehensive quality and benchmark references.
  • Implemented structural/content checks.
  • Added installer, release-workflow, compatibility, and package tests.

Outcomes

  • Agents can produce audience-first setup and usage docs.
  • Preserve verified voice/attribution while removing stale claims.
  • Surface material absences such as missing licenses.
  • Validate that the finished README is complete.

Verified stack

  • Agent Skills
  • JavaScript
  • Node.js
  • npm
  • GitHub Actions
  • CI/CD
  • Git

Working through something similar?

Share your challenge, scope, and timeline to start a focused conversation.