Build Workspace Docs
Regenerates README.md and WORK_AREAS.md in an ai-agent-skills library workspace via the CLI
Test report
- Verdict
- Works with setup
- Score
- Tested
- Jul 21, 2026
- Environment
- Claude Code 2.x (agent harness)
- Upstream re-checked
- Aug 10, 2026 · c99781b
Built a real workspace in a temp HOME (`npx ai-agent-skills@4.3.2 init-library demo-lib --areas "frontend,workflow"`, imported two house-copy skills, then added a third catalog entry to skills.json to make the docs stale), copied it twice, and produced two artifacts: a baseline where I hand-edited README.md/WORK_AREAS.md, and a skill artifact from the prescribed CLI flow. The generated docs differed from my hand edit on two derived lines — README stats "3 house copies · 0 cataloged upstream" vs my "2 house copies · 1 cataloged upstream", and WORK_AREAS source cell "workspace" vs my "upstream/seo-pack" — i.e. the CLI derived tier/author correctly from skills.json where I guessed wrong, and a second run was byte-identical (idempotent). However, steps 1 and 3 of the skill (`build-docs --dry-run`, and `--dry-run --format json`) both exited 1 with "ENOENT ... /opt/homebrew/lib/node_modules/ai-agent-skills/WORK_AREAS.md"; the published 4.3.2 tarball contains no WORK_AREAS.md (excluded by .npmignore and package.json files[]), and cli.js:6846 passes the workspace context as the options object so `generatedDocsAreInSync` falls back to the bundled package root. Forcing it to run against a patched package copy showed the documented `currentlyInSync` field comparing against the upstream repo's own README instead of the workspace, reporting readmeMatches:false right after a successful regeneration. Frontmatter has name+description, no scripts or bundled files are referenced, and I found no security smells (no curl|sh, base64, credential access, or injection text) in the 52-line SKILL.md.
Scored on four weighted criteria — install, triggering, output vs. baseline, docs. How scoring works
- Installs cleanly 4/5
- Triggers reliably 5/5
- Output vs. baseline 6/10
- Docs & honesty 2/5
What Build Workspace Docs does
Wraps the `ai-agent-skills` CLI `build-docs` command to regenerate the README.md and WORK_AREAS.md files of a managed skills-library workspace from skills.json, so shelf tables, skill counts, and source tables match the catalog. Triggers when a user asks to rebuild or resync the generated docs of an ai-agent-skills library workspace after adding, importing, or curating skills. Requires Node/npx and an initialized workspace containing .ai-agent-skills/config.json.
How to install Build Workspace Docs
git clone --depth 1 https://github.com/MoizIbnYousaf/Ai-Agent-Skills.git /tmp/build-workspace-docs-src
mkdir -p ~/.claude/skills
cp -R /tmp/build-workspace-docs-src/skills/build-workspace-docs ~/.claude/skills/build-workspace-docs
# Runtime dependency (not stated in SKILL.md): Node.js + network for `npx ai-agent-skills`.
# Only usable inside a workspace created by: npx ai-agent-skills init-library <name>
# Alternative install via the project's own CLI: npx ai-agent-skills install build-workspace-docs
# KNOWN BREAKAGE (verified on ai-agent-skills@4.3.2): steps 1 and 3 of the skill body
# (`build-docs --dry-run` and `build-docs --dry-run --format json`) exit 1 with
# "ENOENT ... node_modules/ai-agent-skills/WORK_AREAS.md" because that file is
# excluded from the published npm tarball. Run the bare `npx ai-agent-skills build-docs` instead.
Skills live in ~/.claude/skills/ (global) or .claude/skills/
(per-project). Restart Claude Code after installing.
Commands — how to trigger Build Workspace Docs
-
/build-workspace-docsRegenerates README.md and WORK_AREAS.md in an ai-agent-skills library workspace via the CLI
It also activates on plain-language prompts like these:
-
Regenerate the README for this workspace -
Update WORK_AREAS.md to reflect current skills -
Preview doc changes before regenerating them
Frequently asked questions
- Is the Build Workspace Docs skill free?
- Yes. The skill itself is free from MoizIbnYousaf/Ai-Agent-Skills. SkillProof publishes the install command and an independent test verdict at no cost.
- Does Build Workspace Docs work with Claude Code?
- We tested it with Claude Code 2.x (agent harness) on Jul 21, 2026. Verdict: Works with setup. Built a real workspace in a temp HOME (`npx ai-agent-skills@4.3.2 init-library demo-lib --areas "frontend,workflow"`, imported two house-copy skills, then added a third catalog entry to skills.json to make the docs stale), copied it twice, and produced two artifacts: a baseline where I hand-edited README.md/WORK_AREAS.md, and a skill artifact from the prescribed CLI flow. The generated docs differed from my hand edit on two derived lines — README stats "3 house copies · 0 cataloged upstream" vs my "2 house copies · 1 cataloged upstream", and WORK_AREAS source cell "workspace" vs my "upstream/seo-pack" — i.e. the CLI derived tier/author correctly from skills.json where I guessed wrong, and a second run was byte-identical (idempotent). However, steps 1 and 3 of the skill (`build-docs --dry-run`, and `--dry-run --format json`) both exited 1 with "ENOENT ... /opt/homebrew/lib/node_modules/ai-agent-skills/WORK_AREAS.md"; the published 4.3.2 tarball contains no WORK_AREAS.md (excluded by .npmignore and package.json files[]), and cli.js:6846 passes the workspace context as the options object so `generatedDocsAreInSync` falls back to the bundled package root. Forcing it to run against a patched package copy showed the documented `currentlyInSync` field comparing against the upstream repo's own README instead of the workspace, reporting readmeMatches:false right after a successful regeneration. Frontmatter has name+description, no scripts or bundled files are referenced, and I found no security smells (no curl|sh, base64, credential access, or injection text) in the 52-line SKILL.md.
- What is the Build Workspace Docs SkillProof Score?
- 6.8/10 — installs cleanly 4/5, triggers reliably 5/5, output vs. baseline 6/10, docs & honesty 2/5.
- How do I install Build Workspace Docs?
- Copy the install command from this page, run it in your terminal, and restart Claude Code. Skills live in ~/.claude/skills/ (global) or .claude/skills/ inside a project.
- Can I use Build Workspace Docs with Cursor, Copilot, Gemini CLI, Codex or other AI tools?
- The SKILL.md format is native to Claude (Claude Code, Desktop, claude.ai). The instructions inside adapt to other assistants: Cursor rules, GitHub Copilot instructions, Windsurf rules, Custom GPTs, AGENTS.md for OpenAI Codex, and GEMINI.md for Google Gemini CLI — our conversion guides cover each, and the free converter on the tools page does the wrapping for you.