merge-docs — Claude Code skill: merge two design docs
merge-docs combines two doc sets for one feature into one: design, plan and tasks. Handy when design ran twice and you need a single version to build from.
no license ★ 155 updated 2026-10-29
npx skills add serpro69/claude-toolbox --skill merge-docs -a claude-codeWhat merge-docs does
The skill takes two write-ups of the same feature, whether they compete or complement each other, and produces one set of documents from them: a design doc, an implementation plan, a task list. That happens when the design step ran more than once and /docs/feat/wip/ now holds two folders about the same thing.
The order is fixed. Both folders get read in full first, and the skill builds a picture of how the project's code actually works. Only then does it sort sections, flag contradictions and write the merged text. Skip that grounding and the merge picks whichever document reads better — the wrong tiebreaker. Steps live in merge-process.md next to SKILL.md; the knowledge-base conventions sit in shared-capy-knowledge-protocol.md.
It works on a pair: two feature folders under /docs/feat/wip/, each carrying its own design, plan and task list. Docs kept elsewhere need to be moved into that layout first. Without reading the code, the merge follows the smoother prose instead of the project, which is the mistake this skill exists to prevent.
What it helps with
- merge two competing design docs for one feature
- find contradictions between two implementation plans
- build one task list from two parallel design runs
- decide which doc version matches the code
Example prompts for the agent
- Merge the two
billing-retryfeature folders under/docs/feat/wip/into one set of docs. - Compare the two design docs for this feature and list where they disagree.
- Combine the design, plan and task list from both runs into a single set.
How to install merge-docs
1Skills CLI (Vercel)
npx skills add serpro69/claude-toolbox --skill merge-docs -a claude-code2Manually: put the files in place
~/.claude/skills/merge-docs/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/merge-docs/
1Skills CLI (Vercel)
npx skills add serpro69/claude-toolbox --skill merge-docs -a codex2Manually: put the files in place
.agents/skills/merge-docs/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add serpro69/claude-toolbox --skill merge-docs -a cursor2Manually: put the files in place
.cursor/skills/merge-docs/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install serpro69/claude-toolbox kodex-plugin/skills/merge-docs2Manually: put the files in place
.github/skills/merge-docs/SKILL.md1Skills CLI (Vercel)
npx skills add serpro69/claude-toolbox --skill merge-docs -a gemini-cli2Platform CLI
gemini skills install https://github.com/serpro69/claude-toolbox --path kodex-plugin/skills/merge-docsManually: put the files in place
.devin/skills/merge-docs/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.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 merge-docs
How do I install merge-docs in Claude Code?
Run npx skills add serpro69/claude-toolbox --skill merge-docs -a claude-code. The skill file lands at ~/.claude/skills/merge-docs/SKILL.md.
What does merge-docs do?
It compares two sets of docs for one feature and turns them into a single set: design, implementation plan, task list. The codebase is read first, so contradictions get settled by the code rather than by which text sounds better.
Does the skill work in Codex?
Yes. Install it with npx skills add serpro69/claude-toolbox --skill merge-docs -a codex; the file goes to .agents/skills/merge-docs/SKILL.md.