mcpField
R
readme

readme

github.com/statelyaiDevelopment4871 installsUpdated 24w ago
Repository

About readme

A documentation skill for treating HTML comments in Markdown as symbolic references to source-code facts and consistency requirements. It guides repository-wide scans and resolving references by logical code constructs or file paths.

Key features

  1. 01Recognize symbolic Markdown comments
  2. 02Resolve path-based and logical references
  3. 03Scan non-ignored Markdown files
  4. 04Prefer stable logical references

Use cases

  1. 01Keep API documentation aligned with source
  2. 02Find symbolic references when changing a repository
  3. 03Check documentation across project packages

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/statelyai/skills --skill readme

After installing, type/readmein Claude Code to confirm it loaded.

Bundled filesagents/openai.yaml

Details

From the project README

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 (<!-- TODO: rewrite -->) 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 '<!--' --glob '*.md' .
  2. 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.
  3. 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.
  4. Preserve surrounding prose and sections without comments.
  5. 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 (<!-- exported functions from src/index.ts --> or <!-- all exported creator functions --> — not <!-- API docs -->), 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.

Comments

Markdown supported