Terminal
Terminal/Skill
Keeps README files in sync with code and repo structure by updating symbolic HTML comments whenever a change touches a referenced construct.
By Stately (XState)
Works with
npx skills add statelyai/skills --skill readmeHTML 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.
rg -l '<!--' --glob '*.md' .If a comment references something that no longer exists, flag it to the user rather than silently removing the section.
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.
Apply to all non-gitignored markdown files in the project tree — README.md, packages/*/README.md, src/**/README.md, docs/**/*.md, CONTRIBUTING.md, etc.