# Skill Doc Sync

Post-ship doc sync across project markdown.

- Repository: https://github.com/nyldn/claude-octopus (4351 stars)
- Category: Writing
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add nyldn/claude-octopus --skill skill-doc-sync -g -a claude-code -y`
Codex: `npx skills add nyldn/claude-octopus --skill skill-doc-sync -g -a codex -y`
Cursor: `npx skills add nyldn/claude-octopus --skill skill-doc-sync -g -a cursor -y`
Gemini CLI: `npx skills add nyldn/claude-octopus --skill skill-doc-sync -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add nyldn/claude-octopus`

## Description

Post-ship doc sync across project markdown. Use when: sync docs, update docs, document changes, release notes.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Post-Ship Documentation Synchronization

Automated documentation synchronization for the Deliver phase. After code is committed and a PR is created, this skill reads all `.md` files in the project, cross-references the diff, auto-updates factual content, checks cross-doc consistency, and updates the PR body.

---

## Caps

- **Max 30 doc files scanned**, skip files beyond the cap, warn the user
- **Never clobber CHANGELOG**, append only, never delete existing entries
- **Ask user before changing narrative/philosophy sections**, risky changes require confirmation

---

## Step 1: Discover Docs

Find all `.md` files in the project root (max depth 2), skipping `node_modules/` and `.git/`.

```bash
# Discover all markdown files (max depth 2, skip noise directories)
DOC_FILES=$(find . -maxdepth 2 -name '*.md' \
  -not -path './node_modules/*' \
  -not -path './.git/*' \
  -not -path './vendor/*' \
  -not -path './.claude/*' \
  2>/dev/null | head -30)

DOC_COUNT=$(echo "$DOC_FILES" | wc -l | tr -d ' ')
echo "Found $DOC_COUNT doc files to scan (cap: 30)"

if [[ "$DOC_COUNT" -ge 30 ]]; then
  echo "WARNING: Doc file cap reached (30). Some files may be skipped."
fi
```

Read each discovered doc file so you have their current content in context.

---

## Step 2: Cross-Reference Diff

Run `git diff --stat HEAD~1` (or diff against the base branch if on a feature branch) to identify which files changed and what content may now be stale in each doc.

```bash
# Get the diff stat to identify changed files
BRANCH=$(git rev-parse --abbrev-ref HEAD)
if [[ "$BRANCH" == "main" || "$BRANCH" == "master" ]]; then
  DIFF_STAT=$(git diff --stat HEAD~1)
  DIFF_FULL=$(git diff HEAD~1)
else
  BASE_BRANCH=$(git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null)
  DIFF_STAT=$(git diff --stat "$BASE_BRANCH"..HEAD)
  DIFF_FULL=$(git diff "$BASE_BRANCH"..HEAD)
fi

echo "$DIFF_STAT"
```

The rest: https://github.com/nyldn/claude-octopus/blob/HEAD/.claude/skills/skill-doc-sync/SKILL.md