build-workspace-docs

$npx mdskill add MoizIbnYousaf/Ai-Agent-Skills/build-workspace-docs

Regenerates README.md and WORK_AREAS.md from the skills catalog.

  • Keeps workspace docs in sync after adding or curating skills.
  • Depends on the ai-agent-skills CLI and a valid workspace config.
  • Uses dry-run to preview changes before regenerating docs.
  • Outputs updated markdown files and optional JSON sync status.

SKILL.md

.github/skills/build-workspace-docsView on GitHub ↗
---
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.

More from MoizIbnYousaf/Ai-Agent-Skills

SkillDescription
ask-questions-if-underspecifiedClarify requirements before implementing. Do not use automatically, only when invoked explicitly.
audit-library-healthUse when checking the overall health of a skills library. Run doctor, validate, check for stale skills, and verify generated docs are in sync.
backend-developmentBackend API design, database architecture, microservices patterns, and test-driven development. Use for designing APIs, database schemas, or backend system architecture.
browse-and-evaluateUse when exploring the ai-agent-skills catalog to find, compare, and evaluate skills before installing. Always use --fields to limit output size and --dry-run before committing to an install.
code-documentationWriting effective code documentation - API docs, README files, inline comments, and technical guides. Use for documenting codebases, APIs, or writing developer guides.
curate-a-team-libraryUse when building a managed team skills library for a real stack. Map work to shelves, browse before curating, write meaningful `whyHere` notes, and create a starter pack once the first pass is solid.
install-from-remote-libraryUse when installing skills from a shared ai-agent-skills library repo. Inspect with `--list` first, prefer `--collection`, and preview with `--dry-run` before installing.
llm-application-devBuilding applications with Large Language Models - prompt engineering, RAG patterns, and LLM integration. Use for AI-powered features, chatbots, or LLM-based automation.
migrate-skills-between-librariesUse when moving skills between library workspaces or upgrading from a personal library to a team library. Export from one workspace, import into another.
review-a-skillUse when evaluating whether a skill belongs in a library. Preview content, check frontmatter, validate structure, and decide whether to keep, curate, or remove.