# merge-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.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf (Devin Desktop), Claude.ai · ★ 155 repo stars
- Author: serpro69
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/serpro69/claude-toolbox/tree/HEAD/kodex-plugin/skills/merge-docs/SKILL.md
- Updated: 2026-10-29
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/merge-docs

## What it 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.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add serpro69/claude-toolbox --skill merge-docs -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/merge-docs/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/merge-docs/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add serpro69/claude-toolbox --skill merge-docs -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/merge-docs/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add serpro69/claude-toolbox --skill merge-docs -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/merge-docs/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install serpro69/claude-toolbox kodex-plugin/skills/merge-docs
```

2. **Manually: put the files in place**
- File: `.github/skills/merge-docs/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add serpro69/claude-toolbox --skill merge-docs -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/serpro69/claude-toolbox --path kodex-plugin/skills/merge-docs
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/merge-docs/SKILL.md` — The legacy .windsurf/skills/ path still works

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/serpro69/claude-toolbox/tree/HEAD/kodex-plugin/skills/merge-docs/SKILL.md

## When to use it
- 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
- Merge the two `billing-retry` feature 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.

## Similar
- [design-docs](https://affpapa.org/en/nevibecode/skills/design-docs.md) — skill · ★ 539 repo stars
- [writing-design-docs](https://affpapa.org/en/nevibecode/skills/writing-design-docs.md) — skill · 26900 installs
- [rfc-generator](https://affpapa.org/en/nevibecode/skills/rfc-generator.md) — skill · 294 installs
- [egm-drift-report](https://affpapa.org/en/nevibecode/skills/egm-drift-report.md) — skill · 583 installs
- [research-merge](https://affpapa.org/en/nevibecode/skills/research-merge.md) — skill · 1 install
- [tailwind-4-docs](https://affpapa.org/en/nevibecode/skills/tailwind-4-docs.md) — skill · 19300 installs

From the same set: [serpro69/claude-toolbox](https://affpapa.org/en/nevibecode/by/serpro69/claude-toolbox.md) — 30 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
