About w-docs
w-docs is a Basilic workflow skill for keeping project documentation aligned with code changes. It guides agents to update the appropriate existing documentation layer and avoid unnecessary duplicate structure.
Key features
- 01Find the matching documentation topic
- 02Update canonical MDX explanations
- 03Patch README for setup and scripts
- 04Update agent rules when constraints change
- 05Suggest minimal file move lists
Use cases
- 01Document a changed feature or architecture
- 02Update setup instructions after script changes
- 03Plan related documentation file moves
Install
Copy the command and run it in a terminal.
$
npx skills add https:/After installing, type/w-docsin Claude Code to confirm it loaded.
Details
From the project READMEDocument the current code or feature. Follow the consuming repo's docs and README rules. Do not commit unless asked. Durable information architecture belongs in existing MDX; do not invent a second sitemap.
Write to the layer that owns the change:
| Layer | Role | Update when |
|---|---|---|
Technical docs (path in AGENTS.md) | Architecture, ADRs, how-to | Behavior, architecture, commands, conventions, or workflow changed |
| Agent rules | Short constraints | A convention the agent must not violate changed |
| Nearest README | How to run this app/package; links only | Scripts, setup, or package purpose changed |
Inline comments only when the code is otherwise misleading. Do not copy MDX into rules or READMEs. Do not @-attach MDX.
- Identify the matching docs section, then an existing topic page (create a page only if none fits).
- Write or patch MDX if the canonical explanation changed.
- Patch README only for run/setup/scripts; link the MDX.
- Patch the glob-matched rule only if a constraint changed.
- For mechanical file or doc moves: propose the smallest from/to list grouped by related files; drop folder-name prefixes inside groups. Save only if the user gave a path. Do not move files unless they also asked to implement.
Comments
Markdown supported