/update-docs

description: Update all the documentation related files.

After completing any skill creation, agent creation, or command creation in this repository, run the full post-creation sync pipeline below. Execute every step — never skip a task. If something is unclear or a step fails, ask the user for guidance before continuing.

---

Step 1: Inventory what changed

Scan the working tree to identify what was added, modified, or deleted:

git status --short

Classify each change:

• **New skill** — a new folder containing `SKILL.md` under a domain directory
• **New agent** — a new `.md` file under `agents/`
• **New command** — a new `.md` file under `commands/`
• **Modified skill/agent/command** — updated existing files
• **Deleted skill/agent/command** — removed files

Report the inventory to the user before proceeding.

---

Step 2: Cross-platform CLI sync

Ensure all platforms have compatible versions of every skill, agent, and command.

2a. Codex CLI

Run the Codex sync script to regenerate symlinks and the skills index:

python3 scripts/sync-codex-skills.py --verbose

Verify the output: check `.codex/skills-index.json` for correct `total_skills` count and that new skills appear in the index.

2b. Gemini CLI

Run the Gemini sync script:

python3 scripts/sync-gemini-skills.py --verbose

Verify: check `.gemini/skills-index.json` for correct total count. New skills, agents, and commands should all have corresponding entries and symlinks under `.gemini/skills/`.

2c. OpenClaw

Verify that `scripts/openclaw-install.sh` will pick up the new skills. The install script uses the same directory structure, so no separate sync is needed — but confirm the new skill directories are not excluded by any filter in the script.

Report sync results (skill counts per platform) to the user.

---

Step 3: Claude Code plugin marketplace

3a. Domain-level plugin.json

For each domain that had changes, update the domain's `.claude-plugin/plugin.json`:

• Update `description` with accurate skill/tool/reference counts
• Update `version` if needed
• Verify `source` paths are correct

Domain plugin.json locations:

• `marketing-skill/.claude-plugin/plugin.json`
• `engineering-team/.claude-plugin/plugin.json`
• `engineering/.claude-plugin/plugin.json`
• `product-team/.claude-plugin/plugin.json`
• `c-level-advisor/.claude-plugin/plugin.json`
• `project-management/.claude-plugin/plugin.json`
• `ra-qm-team/.claude-plugin/plugin.json`
• `business-growth/.claude-plugin/plugin.json`
• `finance/.claude-plugin/plugin.json`

3b. Root marketplace.json

Update `.claude-plugin/marketplace.json`:

• Update the top-level `metadata.description` with accurate total counts (skills, tools, references, agents, commands)
• If a new individual skill plugin entry is needed (for standalone install), add it to the `plugins` array following the existing pattern
• Update `keywords` arrays if new domains or capabilities were added
• Verify all `source` paths point to valid directories

---

Step 4: Update documentation files

4a. Root CLAUDE.md

Update `/CLAUDE.md` (the root project instructions):

• **Current Scope** line: update skill, tool, reference, agent, and command counts
• **Repository Structure** comment counts (agents, commands, skills per domain)
• **Navigation Map** table: verify all domain entries are current
• **Current Version** section: add a bullet if significant changes were made
• **Roadmap** section: update counts if needed

4b. Domain-level CLAUDE.md files

For each domain that had changes, update its `CLAUDE.md`:

• Skill count and list
• Script/tool count
• Agent references
• Command references
• Any new cross-domain integrations

Domain CLAUDE.md locations:

• `agents/CLAUDE.md`
• `marketing-skill/CLAUDE.md`
• `product-team/CLAUDE.md`
• `engineering-team/CLAUDE.md`
• `c-level-advisor/CLAUDE.md`
• `project-management/CLAUDE.md`
• `ra-qm-team/CLAUDE.md`
• `business-growth/CLAUDE.md`
• `finance/CLAUDE.md`
• `standards/CLAUDE.md`
• `templates/CLAUDE.md`

4c. Root README.md

Update `/README.md`:

• Badge counts (Skills, Agents, Commands)
• Tagline/intro paragraph skill count
• Skills Overview table (domain rows with correct counts)
• Quick Install section (install commands, skill counts in comments)
• Python Analysis Tools section (tool count, add examples for new tools)
• FAQ section (update any counts mentioned)

4d. docs/index.md (GitHub Pages homepage)

Update `docs/index.md`:

• `description` meta tag
• Hero subtitle skill count
• Grid cards (skills, tools, agents, commands counts)
• Domain cards (skill counts per domain, links)

4e. docs/getting-started.md

Update `docs/getting-started.md`:

• `description` meta tag
• Available Bundles table (skill counts per bundle)
• Python Tools section (tool count)
• FAQ answers (any count references)

---

Step 5: Regenerate GitHub Pages

Run the docs generation script to create/update all MkDocs pages:

python3 scripts/generate-docs.py

This generates pages for:

• Every skill (from SKILL.md files)
• Every agent (from agents/*.md)
• Every command (from commands/*.md)
• Index pages for skills, agents, and commands sections

5a. Update mkdocs.yml navigation

Open `mkdocs.yml` and update the `nav:` section:

• Add new skill pages under the correct domain section
• Add new agent pages under the Agents section
• Add new command pages under the Commands section
• Update `site_description` with current counts

5b. Verify the build

python3 -m mkdocs build 2>&1 | tail -5

The build should complete without errors. Warnings about relative links in SKILL.md files are expected and can be ignored (they reference skill-internal paths like `references/` and `scripts/`).

Report the build result and page count to the user.

---

Step 6: Consistency verification

Run a final consistency check across all updated files:

1. **Count consistency** — Verify the same skill/agent/comma