build-workspace-docs — Claude Code skill: docs, setup
build-workspace-docs keeps README.md and WORK_AREAS.md aligned with a skills catalog. Run it after catalog changes or before committing workspace updates.
MIT 172 installs ★ 1,161 updated 2026-09-21
npx skills add MoizIbnYousaf/ai-agent-skills --skill build-workspace-docs -a claude-codeWhat build-workspace-docs does
This skill rebuilds the generated parts of README.md and WORK_AREAS.md in a managed library workspace. It starts with build-docs --dry-run so you can inspect the planned changes, then runs the rebuild. A JSON mode supports automation and reports whether the documents are already current.
Run it from an initialized workspace containing .ai-agent-skills/config.json. Without that file, the command fails. Do not edit generated sections by hand: HTML comments such as <!-- GENERATED:...:start/end --> mark the areas the CLI replaces. The currentlyInSync value in the JSON output gives the final status.
What it helps with
- sync README.md with the skills catalog
- rebuild WORK_AREAS.md after catalog edits
- preview documentation changes before writing
- check document status in JSON output
- verify workspace docs before a git commit
Example prompts for the agent
- Preview the documentation changes with
build-docs --dry-run. - Rebuild
README.mdandWORK_AREAS.mdafter changing the skills catalog. - Run the JSON check and report the value of
currentlyInSync.
How to install build-workspace-docs
1Skills CLI (Vercel)
npx skills add MoizIbnYousaf/ai-agent-skills --skill build-workspace-docs -a claude-code2Manually: put the files in place
~/.claude/skills/build-workspace-docs/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/build-workspace-docs/
1Skills CLI (Vercel)
npx skills add MoizIbnYousaf/ai-agent-skills --skill build-workspace-docs -a codex2Manually: put the files in place
.agents/skills/build-workspace-docs/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add MoizIbnYousaf/ai-agent-skills --skill build-workspace-docs -a cursor2Manually: put the files in place
.cursor/skills/build-workspace-docs/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install MoizIbnYousaf/ai-agent-skills skills/build-workspace-docs2Manually: put the files in place
.github/skills/build-workspace-docs/SKILL.md1Skills CLI (Vercel)
npx skills add MoizIbnYousaf/ai-agent-skills --skill build-workspace-docs -a gemini-cli2Platform CLI
gemini skills install https://github.com/MoizIbnYousaf/ai-agent-skills --path skills/build-workspace-docsManually: put the files in place
.devin/skills/build-workspace-docs/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add MoizIbnYousaf/ai-agent-skills --skill build-workspace-docs -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about build-workspace-docs
How do I install build-workspace-docs in Claude Code?
Run npx skills add MoizIbnYousaf/ai-agent-skills --skill build-workspace-docs -a claude-code. The skill will be available at ~/.claude/skills/build-workspace-docs/SKILL.md.
What does build-workspace-docs do?
It rebuilds the generated sections of README.md and WORK_AREAS.md from the skills catalog. The workflow previews changes first and can return structured JSON.
Where can I run build-workspace-docs?
Run it inside an initialized workspace that contains .ai-agent-skills/config.json. Use --dry-run before rebuilding and leave the generated sections untouched.
Source text
SKILL.md · MIT
--- name: build-workspace-docs description: Use when regenerating README.md and WORK_AREAS.md in a managed library workspace. Always dry-run first to preview changes. category: workflow version: 4.1.0 --- # Build Workspace Docs ## Goal Keep workspace documentation in sync with the skills catalog after adding, removing, or curating skills. ## Guardrails - Always use `--dry-run` before regenerating docs to preview what will change. - Only run from inside an initialized library workspace (a directory with `.ai-agent-skills/config.json`). - Never hand-edit the generated sections of README.md or WORK_AREAS.md. The CLI will overwrite them. - Use `--format json` to capture structured results for automation pipelines. ## Workflow 1. Preview what would change. ```bash npx ai-agent-skills build-docs --dry-run ``` 2. Regenerate the docs. ```bash npx ai-agent-skills build-docs ``` 3. Verify the output. ```bash npx ai-agent-skills build-docs --dry-run --format json ``` The JSON output includes `currentlyInSync` to tell you whether docs were already up to date. ## When to Run - After `add`, `catalog`, `vendor`, or `curate` commands that change the skills catalog. - After bulk imports from a remote library. - Before committing workspace changes to git. ## Gotchas - Running outside a workspace will fail with a clear error. Use `init-library` to create one first. - The generated docs use HTML comment markers (`<!-- GENERATED:...:start/end -->`) as boundaries. Do not remove these markers from the template sections.
© MoizIbnYousaf · MIT · MoizIbnYousaf/ai-agent-skills