/sync-capabilities

description: Detect and fix drift between plugin.json registrations and capabilities reference documentation
usage: /sync-capabilities [--fix] [--plugin <name>]

Sync Capabilities

Compare plugin.json registrations (skills, commands, agents) against `book/src/reference/capabilities-reference.md` and report discrepancies. Optionally auto-generate missing entries.

Arguments

• `--fix` - Auto-generate missing entries in capabilities-reference.md (default: report only)
• `--plugin <name>` - Check a specific plugin instead of all plugins

What It Does

1. Reads all `plugins/*/.claude-plugin/plugin.json` files (or a single plugin if `--plugin` is specified) 2. Extracts registered skills, commands, and agents 3. Parses `book/src/reference/capabilities-reference.md` for documented entries 4. Reports discrepancies: missing from docs, extra in docs, stale entries 5. Checks for missing plugin book pages and SUMMARY.md entries 6. With `--fix`, generates table entries for missing items using templates

Workflow

Step 1: Run Detection Script

Execute the capabilities sync check from the repo root:

#!/bin/bash
# Run from repo root

PLUGIN_FILTER="${1:-}"  # Optional: specific plugin name

echo "=== Capabilities Sync Report ==="
echo ""

REGISTERED_SKILLS=$(mktemp)
DOCUMENTED_SKILLS=$(mktemp)
REGISTERED_COMMANDS=$(mktemp)
DOCUMENTED_COMMANDS=$(mktemp)
REGISTERED_AGENTS=$(mktemp)
DOCUMENTED_AGENTS=$(mktemp)

# Extract registered skills from plugin.json files
for pjson in plugins/*/.claude-plugin/plugin.json; do
  plugin=$(basename $(dirname $(dirname "$pjson")))
  [ -n "$PLUGIN_FILTER" ] && [ "$plugin" != "$PLUGIN_FILTER" ] && continue
  jq -r --arg p "$plugin" '.skills[]? | sub("^\\./skills/"; "") | "\($p):\(.)"' "$pjson" 2>/dev/null
done | sort -u > "$REGISTERED_SKILLS"

# Extract documented skills from capabilities-reference.md
grep -E "^\| \`[a-z-]+\` \|" book/src/reference/capabilities-reference.md 2>/dev/null | \
  sed -n '/All Skills/,/All Commands/p' | \
  grep -E "^\| \`" | \
  awk -F'|' '{gsub(/[`\[\] ]/, "", $2); gsub(/.*\(\.\.\/plugins\//, "", $3); gsub(/\.md\).*/, "", $3); print $3":"$2}' | \
  sort -u > "$DOCUMENTED_SKILLS"

# Extract registered commands
for pjson in plugins/*/.claude-plugin/plugin.json; do
  plugin=$(basename $(dirname $(dirname "$pjson")))
  [ -n "$PLUGIN_FILTER" ] && [ "$plugin" != "$PLUGIN_FILTER" ] && continue
  jq -r --arg p "$plugin" '.commands[]? | sub("^\\./commands/"; "") | sub("\\.md$"; "") | "/\($p):\(.)"' "$pjson" 2>/dev/null
done | sort -u > "$REGISTERED_COMMANDS"

# Extract documented commands
grep -E "^\| \`/" book/src/reference/capabilities-reference.md 2>/dev/null | \
  sed -n '/All Commands/,/All Agents/p' | \
  grep -E "^\| \`/" | \
  awk -F'|' '{gsub(/[`\[\] ]/, "", $2); gsub(/ /, "", $3); print $2}' | \
  sort -u > "$DOCUMENTED_COMMANDS"

# Extract registered agents
for pjson in plugins/*/.claude-plugin/plugin.json; do
  plugin=$(basename $(dirname $(dirname "$pjson")))
  [ -n "$PLUGIN_FILTER" ] && [ "$plugin" != "$PLUGIN_FILTER" ] && continue
  jq -r --arg p "$plugin" '.agents[]? | sub("^\\./agents/"; "") | sub("\\.md$"; "") | "\($p):\(.)"' "$pjson" 2>/dev/null
done | sort -u > "$REGISTERED_AGENTS"

# Extract documented agents
grep -E "^\| \`[a-z-]+\` \|" book/src/reference/capabilities-reference.md 2>/dev/null | \
  sed -n '/All Agents/,/All Hooks/p' | \
  grep -E "^\| \`" | \
  awk -F'|' '{gsub(/[`\[\] ]/, "", $2); gsub(/ /, "", $3); print $3":"$2}' | \
  sort -u > "$DOCUMENTED_AGENTS"

# Report
echo "### Skills"
echo "Missing from docs (registered but not documented):"
comm -23 "$REGISTERED_SKILLS" "$DOCUMENTED_SKILLS" | sed 's/^/  - /'
echo ""
echo "Extra in docs (documented but not registered):"
comm -13 "$REGISTERED_SKILLS" "$DOCUMENTED_SKILLS" | sed 's/^/  - /'

echo ""
echo "### Commands"
echo "Missing from docs:"
comm -23 "$REGISTERED_COMMANDS" "$DOCUMENTED_COMMANDS" | sed 's/^/  - /'
echo ""
echo "Extra in docs:"
comm -13 "$REGISTERED_COMMANDS" "$DOCUMENTED_COMMANDS" | sed 's/^/  - /'

echo ""
echo "### Agents"
echo "Missing from docs:"
comm -23 "$REGISTERED_AGENTS" "$DOCUMENTED_AGENTS" | sed 's/^/  - /'
echo ""
echo "Extra in docs:"
comm -13 "$REGISTERED_AGENTS" "$DOCUMENTED_AGENTS" | sed 's/^/  - /'

# Check for missing plugin pages
echo ""
echo "### Plugin Pages"
for plugin in plugins/*/; do
  name=$(basename "$plugin")
  [ -n "$PLUGIN_FILTER" ] && [ "$name" != "$PLUGIN_FILTER" ] && continue
  if [ ! -f "book/src/plugins/${name}.md" ]; then
    echo "  - Missing: book/src/plugins/${name}.md"
  fi
done

# Check SUMMARY.md
echo ""
echo "### SUMMARY.md"
for plugin in plugins/*/; do
  name=$(basename "$plugin")
  [ -n "$PLUGIN_FILTER" ] && [ "$name" != "$PLUGIN_FILTER" ] && continue
  if ! grep -q "plugins/${name}.md" book/src/SUMMARY.md 2>/dev/null; then
    echo "  - Missing from SUMMARY: ${name}"
  fi
done

rm -f "$REGISTERED_SKILLS" "$DOCUMENTED_SKILLS" "$REGISTERED_COMMANDS" "$DOCUMENTED_COMMANDS" "$REGISTERED_AGENTS" "$DOCUMENTED_AGENTS"

Step 2: Review Output

Examine the sync report. Discrepancies fall into three categories:

| Type | Meaning | Action | |------|---------|--------| | Missing from docs | Registered in plugin.json but not in capabilities-reference.md | Add entry | | Extra in docs | Documented but no matching plugin.json registration | Remove or investigate | | Missing pages | Plugin exists but has no book page or SUMMARY entry | Create page |

Step 3: Fix (with `--fix`)

When `--fix` is specified, auto-generate missing entries using these templates.

Skill Entry

Read the skill's `SKILL.md` frontmatter for the description, then insert:

| `{skill-name}` | [{plugin}](../plugins/{plugin}.md) | {description from SKILL.md} |

Command Entry

Read the command's YAML frontmatter for the description, then insert:

| `/{plugin}:{command}` | {plugin} | {description from command.md frontmatter} |

Agent Entry

Read the agent file's first hea