decision-doc-sync — Claude Code skill: keep docs in sync
Keeps README, DESIGN, AGENTS and ADR files aligned with the code after architectural or UX changes. Useful when an edit breaks the docs.
npx skills add C3SC0-V4113/Scaffold --skill decision-doc-sync -a claude-codeWhat decision-doc-sync does
The skill loads when a change introduces or alters a structural decision: architecture, a UI/UX standard, scripts and quality gates, or a cross-cutting convention. It first checks which documents actually exist and edits only those. A new file gets created only when the decision table calls for one.
Where things go is fixed. Architecture, folder structure and scripts land in README.md; visual standards, tokens and component usage in DESIGN.md; agent workflow and operational guidance in AGENTS.md; a durable decision with alternatives and consequences becomes a new record in docs/adr/. One change can hit several rows at once. Each fact stays in a single document and others link to it instead of copying it.
Before finishing, it rereads the edited sections against the code and reports every document updated, created or deliberately skipped, one line of reason each. For ADRs it follows the numbering and format already present in docs/adr/, so you do not need to seed that folder first. A document left contradicting the code after the change is a failure, not a warning.
What it helps with
- update README after moving folders around
- record a new UI standard in DESIGN.md
- document agent commands in AGENTS.md
- write an ADR with alternatives and consequences
- close the gap between docs and code
Example prompts for the agent
- We switched to a new folder layout — sync the docs
- Added a quality gate to CI, update whatever should know about it
- Record the state management choice as an ADR
How to install decision-doc-sync
1Skills CLI (Vercel)
npx skills add C3SC0-V4113/Scaffold --skill decision-doc-sync -a claude-code2Manually: put the files in place
~/.claude/skills/decision-doc-sync/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/decision-doc-sync/
1Skills CLI (Vercel)
npx skills add C3SC0-V4113/Scaffold --skill decision-doc-sync -a codex2Manually: put the files in place
.agents/skills/decision-doc-sync/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add C3SC0-V4113/Scaffold --skill decision-doc-sync -a cursor2Manually: put the files in place
.cursor/skills/decision-doc-sync/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install C3SC0-V4113/Scaffold decision-doc-sync2Manually: put the files in place
.github/skills/decision-doc-sync/SKILL.md1Skills CLI (Vercel)
npx skills add C3SC0-V4113/Scaffold --skill decision-doc-sync -a gemini-cli2Platform CLI
gemini skills install https://github.com/C3SC0-V4113/Scaffold --path skills/decision-doc-syncManually: put the files in place
.devin/skills/decision-doc-sync/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add C3SC0-V4113/Scaffold --skill decision-doc-sync -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about decision-doc-sync
How do I install decision-doc-sync in Claude?
Run npx skills add C3SC0-V4113/Scaffold --skill decision-doc-sync -a claude-code. The skill lands at ~/.claude/skills/decision-doc-sync/SKILL.md.
What does decision-doc-sync do?
It keeps README, DESIGN, AGENTS and docs/adr records from contradicting the code after a structural change. It updates only documents that exist and reports what it skipped.
Which documents does it touch?
README.md for architecture and scripts, DESIGN.md for visual and UX standards, AGENTS.md for agent workflow, docs/adr/ for decisions with alternatives. Each fact lives in one place and the rest link to it.
Source text
SKILL.md · Apache-2.0
--- name: decision-doc-sync description: "Trigger: architecture change, new convention, UI/UX standard, quality gate change, ADR. Keep existing project docs in sync with structural decisions." license: Apache-2.0 metadata: author: purrfold version: "1.0" --- # Decision Documentation Sync ## Activation Contract Load this skill when a change introduces or changes a structural decision: architecture, UI/UX standards, scripts or quality gates, or a cross-cutting convention. ## Hard Rules 1. Check which documents exist before editing; update only documents that exist, and create one only when a rule below requires it. 2. Keep each fact in one document and link to it from others instead of duplicating it. 3. Record the decision itself, not the change history. 4. Never leave a document contradicting the code after the change. ## Decision Gates | Change type | Document | | --- | --- | | Architecture, folder structure, scripts | `README.md` | | Visual or UX standard, tokens, component usage | `DESIGN.md` | | Agent workflow, commands, operational guidance | `AGENTS.md` | | Durable decision with alternatives and consequences | new record in `docs/adr/` | ## Execution Steps 1. Check which of `README.md`, `DESIGN.md`, `AGENTS.md`, and `docs/adr/` exist. 2. Classify the change with the table above; one change may hit several rows. 3. Update each affected document that exists. 4. For an ADR, follow the existing numbering and format in `docs/adr/`; see [references/doc-map.md](references/doc-map.md). 5. Reread the edited sections against the code. ## Output Contract List every document updated, created, or deliberately skipped, with a one-line reason each. ## References - [references/doc-map.md](references/doc-map.md) — ADR format and edge cases.
© purrfold · Apache-2.0 · C3SC0-V4113/Scaffold
