docs-sync
Skill1 starsChanged 24 days agoMITView on GitHub
Verify the docs still describe the code - and the diagrams too, when the repo keeps any. Use before calling a behaviour-changing task done, when the user asks to check or update docs, or when a diagram may have gone stale.
46 other projects use a version of this.
Adopted by
Most recently taken up by
- julianosirtori/skillstheir own version, first seen Nov 8, 2026
- voyager67/AgentFieldkittheir own version, first seen Nov 8, 2026
- uwuclxdy/agenticattheir own version, first seen Nov 8, 2026
- kekzl/imptheir own version, first seen Nov 7, 2026
- sunholo-data/ailangtheir own version, first seen Nov 6, 2026
- jackneil/claude-jackedtheir own version, first seen Nov 5, 2026
Used with
Projects with it also use tdd, code-review and 2 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
GoogleSkilltdd
Test-driven development. Use when the user wants to build features or fix bugs test-first, mentions "red-green-refactor", or wants integration tests.
Also in 4 projects that use this
- GoogleSkill
code-review
Adversarial systems, concurrency, memory-model, and architecture code review protocol. Use this skill whenever asked to review code, PRs, diffs, or branches in Filament.
Also in 5 projects that use this
MicrosoftSkillhandoff
Compact the current conversation into a handoff document for another agent to pick up.
Also in 4 projects that use this
- MicrosoftSkill
release
Use ONLY when the user explicitly asks to cut/publish a Huabu desktop release or tag a version. Performs an outward action — bumps the version in apps/desktop/package.json, commits + annotated-tags vX.Y.Z, and pushes the branch + tag. That tag push auto-builds the macOS/Windows installers and publishes a GitHub Release. Provides `status`, `bump`, `tag-push`, and a one-command `run` (bump → tag-push).
Also in 3 projects that use this
Other versions46 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 46
- openai/openai-agents-python★ 31ksame name
- redis/node-redis★ 18ksame name
- redis/ioredis★ 15ksame name
- fossasia/visdom★ 10ksame name
- Kiln-AI/Kiln★ 5.3ksame name
- danielmeppiel/apm★ 4.2ksame name
- microsoft/apm★ 4.2ksame name
- openai/openai-agents-js★ 4ksame name
- pnp/powershell★ 912same name
- strands-agents/box★ 503same name
36 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository6 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- bug-red-testSkill
- init-workflowSkill
- plan-startSkill
- standards-reviewSkill
- task-runSkill
The file
We split this skill into the rules it gives an agent
2 rules. 0 are common, 2 are distinctive, and 0 are very specific to this project.
0
Common
Most of the 36 edited versions we read keep these.
2
Distinctive
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 28
When the key is absent, skip this.
- Distinctive: line 65
Never report such a diagram as fixed.
“Common” is measured: kept by at least 6 in 10 of the 36 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
docs-sync
1. The checklist
.claude/workflow.json docsChecklist lists each doc and what it owns. Walk
every row, and verify it against the change - not against your memory of it.
Report per row: still true / updated / outstanding. No row is skipped silently.
1a. The glossary, if there is one
.claude/workflow.json decisions.glossary names the doc that owns the repo's
vocabulary. When the key is set, check it in the same pass: a change that
introduces a domain term, renames one, or splits one concept into two has changed
the language, and the glossary owns that.
Report a term the code now uses that the glossary does not define, and a definition the code has drifted away from. Where the two disagree, say which is which and let the owner settle it - the glossary is a decision record, not a description you may overwrite to match the code.
When the key is absent, skip this. A repo without a glossary made that choice; do not propose one as a gap.
2. The diagrams, if there are any
Read .claude/workflow.json diagrams.
maintain: false, or the key is absent - this repo does not keep diagrams.
Skip this section entirely. Do not suggest adding one, and do not treat its
absence as a gap: prose-only is a decision the repo owner already made. If a
change genuinely needs a picture to be understandable, say so once as a finding
and let them decide.
maintain: true - the prose and the drawings describe the same runtime, so
whenever you check or change one, check the other in the same pass. A diagram is
documentation, not an appendix to it.
A stale diagram is worse than a missing one: nothing type-checks it, and a box carrying a renamed state still shows the old name to every reader while turning up in no search for the new one.
How you check depends on diagrams.format:
| Format | How |
excalidraw | JSON, so labels are greppable: python3 "${CLAUDE_PLUGIN_ROOT}/skills/docs-sync/scripts/diagram-text.py" <diagrams.glob> |
drawio | Compressed XML - grep only helps if the file was saved uncompressed. Otherwise report it as needing a human to look |
mermaid, d2, plantuml | Plain text. Read the file directly |
3. Who edits a diagram
diagrams.editedBy settles it, and the format decides the default.
human (canvas formats - excalidraw, drawio, figma) - you may read a diagram
and report a stale label, never rewrite it. Editing the file changes no layout,
so a label that grows overflows its box. Give the current text, the correct text
and the file, then leave it listed as outstanding with a 🙋 row in the plan.
Never report such a diagram as fixed.
agent (text formats - mermaid, d2, plantuml) - edit it like any other
source file, and treat the rendered output as the thing that must be right.
4. Register
Committed text states the current design - not the conversation that produced it, and not the history it replaced.
- No "as requested", "as we discussed", "here's what I did". Every file is read by someone who was not in the room.
- No "previously X, now Y", "no longer used", "kept for older records". Describe what is true now. A removed approach that must stay warned off is a decision and belongs in the architecture doc with an ID, not as an aside in the source.
- Say it once. One statement per point, tables over prose, no recap paragraph, no "this document describes".
5. Delegating the sweep
For a checklist of more than two docs, hand it to the docs-diagram-auditor
agent, spawned with model set to models.surface from .claude/workflow.json.
The agent's frontmatter model is the fallback for a repo with no config.
6. Commit shape
A diagram-only change is its own docs: commit, with nothing else in it.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.