Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add MoizIbnYousaf/ai-agent-skills --skill build-workspace-docs -a claude-code
Open on GitHub

What 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.md and WORK_AREAS.md after 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-code

2Manually: put the files in place

~/.claude/skills/build-workspace-docs/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/build-workspace-docs/

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

Similar skills

All skills for Writing and docs →

From the same set15

The whole set →
llm-application-dev llm-application-dev is a Claude Code skill for building with large language models across coding platforms. It includes prompt templates, API integration, RAG patterns, and error handling. CX Codex +1 467installs ask-questions-if-underspecified The ask-questions-if-underspecified skill makes the agent ask 1–5 clarifying questions before it starts work, so you don't get the wrong thing built. Invoked manually. CX Codex +1 383installs browse-and-evaluate The browse-and-evaluate skill helps you find, compare, and inspect catalog skills before adding them. Use it when catalog output needs to stay focused. CX Codex +1 177installs review-a-skill review-a-skill reviews a skill before it enters a library by checking metadata, structure, safety, and dependencies. Use it when the choice is keep, curate, or remove. CX Codex +1 177installs audit-library-health audit-library-health — a skill for diagnosing a skills library: validates structure, finds stale elements, checks documentation sync. Run before publishing or updating. CX Codex +1 170installs update-installed-skills update-installed-skills syncs previously installed agent skills to their upstream versions. Helps you inspect changes safely with dry-run flags before overwriting local setups. CX Codex +1 168installs share-a-library share-a-library — a skill that automates publishing a finished local library to GitHub and generates an install command for your teammates. CX Codex +1 161installs install-from-remote-library install-from-remote-library guides safe skill installs from shared repos. Inspects targets via --list and previews every action with a dry-run flag. CX Codex +1 161installs

Project sponsors

Companies that keep this analytics open