Skip to content

gaia-research/gaia-skill-tree / .agents/skills/gaia-docs-sync

gaia-docs-sync

Verified

Regenerate and commit Class S site-served artifacts after registry changes, then sync documentation across the main repo and the adjacent wiki. Use this skill when: you've changed registry/nodes/, registry/named/, or named-skills.json and need to regenerate docs/graph/* so the live website reflects the update; CI Guard E (docs-cohesion.yml) is failing because Class S artifacts are out of date; someone says "sync the docs", "regenerate docs", "run gaia dev docs", "update the site graph", "commit the Class S artifacts", "website is stale", or "update the wiki"; or you're finishing a registry PR and need to ensure docs/graph/gaia.json, docs/graph/gaia.gexf, docs/graph/gaia.svg, and docs/graph/named/index.json are committed alongside the source change. Also covers updating README.md, docs/index.html, and mirroring changes to the adjacent wiki repo at ../gaia-wiki.

FileKindSize
SKILL.mdskill md6.1 KB
---
name: gaia-docs-sync
description: >
  Regenerate and commit Class S site-served artifacts after registry changes, then
  sync documentation across the main repo and the adjacent wiki. Use this skill when:
  you've changed registry/nodes/, registry/named/, or named-skills.json and need to
  regenerate docs/graph/* so the live website reflects the update; CI Guard E
  (docs-cohesion.yml) is failing because Class S artifacts are out of date; someone
  says "sync the docs", "regenerate docs", "run gaia dev docs", "update the site
  graph", "commit the Class S artifacts", "website is stale", or "update the wiki";
  or you're finishing a registry PR and need to ensure docs/graph/gaia.json,
  docs/graph/gaia.gexf, docs/graph/gaia.svg, and docs/graph/named/index.json are
  committed alongside the source change. Also covers updating README.md,
  docs/index.html, and mirroring changes to the adjacent wiki repo at ../gaia-wiki.
---

# gaia-docs-sync

Keep the live website (`gaiaskilltree.com`) and the project wiki in lockstep with the
registry. GitHub Pages publishes `main:/docs` as-is — if Class S artifacts aren't
committed, the site is dark or stale.

## Background: Why two artifact classes

Class P files (`registry/gaia.json`, `registry/named-skills.json`, etc.) are gitignored
pipeline internals — regenerated by `gaia dev docs` but never committed. Class S files
(`docs/graph/gaia.json`, `docs/graph/named/index.json`, `docs/graph/gaia.gexf`,
`docs/graph/gaia.svg`) ARE committed and are the exact bytes the browser fetches. Any
registry change that doesn't include a Class S regen will either break the site or leave
it showing old data. CI Guard E in `docs-cohesion.yml` enforces this pairing.

---

## Workflow A — Registry change requires Class S regen

Run this whenever you've modified `registry/nodes/`, `registry/named/`, or any file that
`gaia dev docs` reads to produce the site graph.

### Step 1: Confirm you're on the right branch

```bash
git branch --show-current
```

Use a `docs/*`, `review/meta/*`, or `cli/*` branch depending on what drove the change.
Never regenerate on main directly.

### Step 2: Run regeneration

```bash
gaia dev docs
```

This produces both Class P (gitignored, don't touch) and Class S (tracked, must commit).
Watch for warnings — `gaia dev docs` warnings are load-bearing; a silent failure leaves
the prior Class S state on disk.

### Step 3: Verify Class S files changed

```bash
git diff --stat docs/graph/
```

If `docs/graph/` shows no diff but you changed the registry, something went wrong —
investigate before proceeding.

### Step 4: Stage only Class S artifacts

```bash
git add docs/graph/gaia.json docs/graph/named/index.json docs/graph/gaia.gexf docs/graph/gaia.svg
```

Stage only these files, not the gitignored Class P files. Accidentally staging
`registry/gaia.json` (Class P) introduces a file that `.gitignore` should own and will
cause confusion on the next `gaia dev docs` run.

### Step 5: Commit alongside the source change

```bash
git add registry/nodes/ registry/named/   # or whatever source files changed
git commit -m "docs: regenerate Class S artifacts after <summary>"
```

Keeping the source change and its Class S output in the same commit makes the PR diff
self-contained and satisfies Guard E.

### Step 6: Push and open PR

```bash
git push -u origin <branch-name>
gh pr create --title "docs: <summary>" --body "$(cat <<'EOF'
## Summary
- <what changed in the registry>
- Regenerated Class S artifacts via `gaia dev docs`

## Test plan
- [ ] CI Guard E (docs-cohesion.yml) passes
- [ ] `docs/graph/gaia.json` diff looks reasonable (node count change expected)
EOF
)"
```

---

## Workflow B — Human-authored docs and wiki sync

Run this when editing README.md, docs/index.html, or any page that should also appear
on the wiki.

### Step 1: Update main repo documentation

Edit the target files in the main repo (e.g., `README.md`, `docs/index.html`).

The pre-commit hook may regenerate docs automatically — let it succeed rather than
bypassing it.

```bash
git add <files>
git commit -m "docs: <summary of changes>"
git push -u origin <branch-name>
gh pr create --title "docs: <summary>" --body "<detailed description>"
```

### Step 2: Pull or clone the wiki

The wiki lives in a separate git repository. Keep it adjacent to the main repo so paths
stay consistent.

```bash
# First time:
git clone https://github.com/gaia-research/gaia-skill-tree.wiki.git ../gaia-wiki

# Already cloned:
cd ../gaia-wiki && git pull origin master
```

### Step 3: Mirror the changes to wiki pages

Identify which wiki pages correspond to the main-repo changes:

| Main repo file | Wiki equivalent |
|---|---|
| README.md (CLI reference) | CLI-Reference.md |
| docs/index.html (getting started) | Getting-Started.md |
| CONTEXT.md (nomenclature) | Home.md |

Apply the same technical content. The wiki and main repo must describe identical
capabilities — divergence causes user confusion and fails the accuracy constraint.

### Step 4: Commit and push wiki directly to master

The wiki has no PR flow — push straight to `master`.

```bash
cd ../gaia-wiki
git add <updated-files>.md
git commit -m "docs: <summary of changes>"
git push origin master
```

---

## Constraints

**Do not stamp versions on Class S files.** `docs/graph/gaia.json`, `docs/tree.md`, and
`docs/index.html` must not carry a `version` field or banner. The lockstep verifier
checks only `pyproject.toml`, `packages/*/package.json` — a version stamp on a rendered
artifact will break unrelated PRs when they inherit a stale stamp (Issue #807 retro).

**Do not manually patch `?v=` cache-bust strings.** Add new HTML pages to
`build_html_cache_busting()` in `scripts/build_docs.py` instead — the function
auto-applies versioned query strings to all `.css` and `.js` references on every
`gaia dev docs` run.

**Keep the wiki adjacent at `../gaia-wiki`.** The clone path is assumed by this workflow
and by any scripts that cross-reference both repos.

**Auto-sync never touches `docs/badges/`.** The CI auto-sync workflow explicitly skips
badge regeneration to prevent stale-snapshot wipes. Badge updates require a human-run
`infra/badge-*` PR.
rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file).Stars: 198kUpdated Claude CodeCodexUnverifiedInstall
doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.Stars: 198kUpdated Claude CodeCodexVerifiedInstall