build-workspace-docs

1# Build Workspace Docs
2 
3## Goal
4 
5Keep workspace documentation in sync with the skills catalog after adding, removing, or curating skills.
6 
7## Guardrails
8 
9- Always use `--dry-run` before regenerating docs to preview what will change.
10- Only run from inside an initialized library workspace (a directory with `.ai-agent-skills/config.json`).
11- Never hand-edit the generated sections of README.md or WORK_AREAS.md. The CLI will overwrite them.
12- Use `--format json` to capture structured results for automation pipelines.
13 
14## Workflow
15 
161. Preview what would change.
17 
18```bash
19npx ai-agent-skills build-docs --dry-run
20```
21 
222. Regenerate the docs.
23 
24```bash
25npx ai-agent-skills build-docs
26```
27 
283. Verify the output.
29 
30```bash
31npx ai-agent-skills build-docs --dry-run --format json
32```
33 
34The JSON output includes `currentlyInSync` to tell you whether docs were already up to date.
35 
36## When to Run
37 
38- After `add`, `catalog`, `vendor`, or `curate` commands that change the skills catalog.
39- After bulk imports from a remote library.
40- Before committing workspace changes to git.
41 
42## Gotchas
43 
44- Running outside a workspace will fail with a clear error. Use `init-library` to create one first.
45- The generated docs use HTML comment markers (`<!-- GENERATED:...:start/end -->`) as boundaries. Do not remove these markers from the template sections.