How do I install the Readme skill?

Run npx skillmds add statelyai/readme in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Readme safe to use?

This skill has not completed SkillMD's automated safety review yet. Capability flags: docs only. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Readme?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Readme free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Readme?

statelyai (@statelyai) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Readme by statelyai — Agent Skill

Name: Readme
Rating: 4.2 (5 reviews)
Author: statelyai

Readme

Keep README files in sync with the repo using symbolic HTML comments. Use this skill whenever making a repo change that could affect documentation — code (exported APIs, configuration, examples, CLI commands, dependencies), repo structure (adding/removing/renaming files, directories, packages, or other sibling entries referenced by a listing comment), or metadata (package.json, manifests). Also use when authoring or editing README files to add or update symbolic comments. Trigger on any change — code or structural — that touches a construct referenced by an HTML comment in a markdown file.

statelyai e0f6cd3 2 files · 3.7 KB Updated Sep 9, 2026

File contents

Symbolic README References

HTML comments in markdown files act as declarative queries over the codebase — they describe what the surrounding content should reflect. Example:

## API

<!-- exported functions and their signatures from src/index.ts -->

| Function | Description |
| --- | --- |
| `createMachine(config)` | Creates a state machine |

## Installation

<!-- install command matching package.json#name -->

`npm install xstate`

A comment is a symbolic reference if it describes content derivable from source — references to files/modules, package metadata, code constructs, or consistency constraints (consistent with, matching, derived from). Purely editorial comments () are not symbolic references.

References can be path-qualified (exported functions from src/index.ts) or logical (all exported creator functions, public API of the state module, supported config options). Resolve logical references by searching the codebase for constructs that match the description — don't require a filename.

When you change the repo

Scan all non-gitignored markdown files for symbolic comments: rg -l '<!--' --glob '*.md' .
Check relevance — does your change affect the content each comment describes? For logical references, resolve them against the codebase first, then check if the changed file/symbol falls in that set.
Regenerate affected sections: read the referenced source, extract the described construct, format to match existing style, replace only the content below the comment. Preserve the comment itself.
Preserve surrounding prose and sections without comments.
Backfill comments on unannotated READMEs — if a README has no symbolic comments but contains sections that clearly describe the code you just changed (API tables, install commands, config lists, CLI usage), infer the symbolic reference and insert a comment above that section before regenerating. Only backfill sections actually affected by the current change; don't rewrite the whole README. If the inferred reference is ambiguous, flag it instead of guessing.

If a comment references something that no longer exists, flag it to the user rather than silently removing the section.

When you author a README

Add a symbolic comment above any section that reflects the repo (code, structure, or metadata). Good comments are specific ( or  — not ), scoped to one concept, and reference logical constructs rather than line numbers. Prefer logical descriptions when the set spans multiple files or may move.

Scope

Apply to all non-gitignored markdown files in the project tree — README.md, packages/*/README.md, src/**/README.md, docs/**/*.md, CONTRIBUTING.md, etc.

---name: readmedescription: Keep README files in sync with the repo using symbolic HTML comments. Use this skill whenever making a repo change that could affect documentation — code (exported APIs, configuration, examples, CLI commands, dependencies), repo structure (adding/removing/renaming files, directories, packages, or other sibling entries referenced by a listing comment), or metadata (package.json, manifests). Also use when authoring or editing README files to add or update symbolic comments. Trigger on any change — code or structural — that touches a construct referenced by an HTML comment in a markdown file.--- # Symbolic README References HTML comments in markdown files act as declarative queries over the codebase — they describe what the surrounding content *should* reflect. Example: ```markdown ## API  | Function | Description | | --- | --- | | `createMachine(config)` | Creates a state machine | ## Installation  `npm install xstate` ``` A comment is a symbolic reference if it describes content derivable from source — references to files/modules, package metadata, code constructs, or consistency constraints (`consistent with`, `matching`, `derived from`). Purely editorial comments (``) are not symbolic references. References can be **path-qualified** (`exported functions from src/index.ts`) or **logical** (`all exported creator functions`, `public API of the state module`, `supported config options`). Resolve logical references by searching the codebase for constructs that match the description — don't require a filename. ## When you change the repo 1. **Scan** all non-gitignored markdown files for symbolic comments: `rg -l '` or `` — not ``), scoped to one concept, and reference logical constructs rather than line numbers. Prefer logical descriptions when the set spans multiple files or may move. ## Scope Apply to all non-gitignored markdown files in the project tree — `README.md`, `packages/*/README.md`, `src/**/README.md`, `docs/**/*.md`, `CONTRIBUTING.md`, etc.

Frequently asked questions