Docs Steward

Maintain, enhance, and improve the docs site at agents.w4w.dev. The site uses Astro + Starlight + starlight-theme-black. The wagents CLI generates MDX content pages from repository assets (skills, agents, MCP servers). This skill wraps that CLI and extends it with AI-powered enhancement, health checks, and site improvement capabilities.

When to Invoke

Invoke this skill after any of these events:

• •Creating or modifying any skills/*/SKILL.md
• •Creating or modifying any agents/*.md
• •Creating or modifying any mcp/*/server.py or mcp/*/pyproject.toml
• •Running wagents new skill, wagents new agent, or wagents new mcp
• •Installing new skills via npx skills add

Auto-invocation is enabled by default (the disable-model-invocation field is absent, which defaults to false).

When invoked after asset changes, run in auto mode (default). No approval gates, no user prompts. Detect what changed, regenerate, enhance, verify.

Quick Reference

# After creating/modifying skills, agents, or MCP servers:
uv run wagents docs generate && pnpm --dir docs build

# After installing new skills:
/docs-steward sync installed

# Full sync (regenerate + build + validate):
/docs-steward sync

# Full pipeline (sync + maintain + enhance + improve):
/docs-steward full

Dispatch

Auto Mode (Default)

This is the primary mode. Run it when auto-triggered or when $ARGUMENTS is empty or auto.

Step 1: Detect Changes

Run these commands to identify changed asset files:

git diff --name-only HEAD
git status --porcelain

Filter results for asset files matching these patterns:

• •skills/*/SKILL.md
• •agents/*.md
• •mcp/*/server.py
• •mcp/*/pyproject.toml

If no asset files changed, report "No asset changes detected" and exit.

Step 2: Regenerate Pages

Run the CLI to regenerate all content pages:

uv run wagents docs generate

This produces MDX files under docs/src/content/docs/ for skills, agents, and MCP servers based on their source assets.

Step 3: Enhance Changed Pages

For each new or changed page, enhance it. Read the generated MDX and its source asset side by side, then improve:

1. •Descriptions: Expand truncated or generic descriptions into specific, compelling text that explains what the asset does and when to use it.
2. •Usage examples: Add clear invocation instructions if missing. For skills: show the /skill-name command and argument patterns. For agents: show how to spawn or reference them. For MCP servers: show connection config.
3. •Visual elements: Add Starlight components where they improve comprehension:
   • •Aside callouts for tips, warnings, and important notes
   • •Steps for sequential instructions
   • •Tabs for configuration variants (different agents, different modes)
   • •CardGrid with Card for related items or feature overviews
4. •Cross-references: Link to related assets. A skill that uses MCP servers should link to them. An agent with preloaded skills should link to those skills.
5. •Section structure: Verify heading hierarchy (single h1, logical h2/h3 nesting). Reorganize if needed.

Consult references/quality-checklist.md for scoring criteria and references/starlight-patterns.md for component usage patterns.

When enhancing more than 3 pages, spawn parallel subagents (one per page or batch of 3-5 related pages). Each subagent receives: the current MDX content, the source SKILL.md or agent.md, the quality checklist, and the Starlight patterns reference.

Step 4: Verify Build

Run the docs build to confirm nothing is broken:

cd docs && pnpm build

If the build fails, diagnose the error, fix it, and rebuild.

Step 5: Validate Assets

Run the wagents validator to confirm all assets are still valid:

uv run wagents validate

Fix any validation errors before finishing.

Sync Mode

Force a full regeneration and build verification, regardless of what changed.

1. •Run uv run wagents docs generate
2. •Run cd docs && pnpm build
3. •Report: number of pages generated, build status, any warnings

No enhancement in this mode. Use it to reset the generated pages to CLI baseline.

Sync Installed Mode

When $ARGUMENTS is sync installed:

Scan ~/.claude/skills/ for installed skills not already in the repo's skills/ directory. The wagents docs generate command handles this automatically via --include-installed (enabled by default).

1. •Run uv run wagents docs generate (includes installed skill scanning)
2. •For installed skills with sparse descriptions (<50 tokens), spawn a subagent to read the full SKILL.md and write a richer description for the docs page
3. •Run pnpm --dir docs build to verify
4. •Report: number of installed skills found, new/removed since last sync

Run this mode after installing new skills via npx skills add.

Enhance Mode

Enhance All

When $ARGUMENTS is enhance with no path:

1. •List all generated MDX files under docs/src/content/docs/
2. •For each page, score it against references/quality-checklist.md
3. •Spawn parallel subagents (Pattern A from orchestration guide), one per page or batch of 3-5 related pages
4. •Each subagent receives:
   • •The current MDX content
   • •The corresponding source asset (SKILL.md, agent.md, or MCP files)
   • •The quality checklist
   • •The Starlight patterns reference
5. •Each subagent enhances the page and writes the result
6. •After all subagents complete, run cd docs && pnpm build to verify
7. •Run uv run wagents validate

Enhance One

When $ARGUMENTS is enhance <path>:

1. •Read the specified MDX file
2. •Locate its source asset
3. •Score against quality checklist
4. •Enhance in-place
5. •Verify build and validate

Maintain Mode

Run a comprehensive health check on the documentation site.

Step 1: Build Check

cd docs && pnpm build

Capture output. Look for broken link warnings, missing image errors, build failures.

Step 2: Staleness Detection

Compare generated MDX page modification times against source asset modification times. Flag pages that are older than their source (the CLI was not re-run after the asset changed).

# Example: compare skills
for skill_dir in skills/*/; do
  skill_name=$(basename "$skill_dir")
  source="$skill_dir/SKILL.md"
  generated="docs/src/content/docs/skills/$skill_name.mdx"
  # Compare mtimes
done

Step 3: Orphan Detection

Find generated pages whose source assets no longer exist. These are orphans left behind when an asset was deleted but wagents docs generate was not re-run.

Step 4: Validation

uv run wagents validate
uv run wagents readme --check

Step 5: Report

Present findings grouped by severity:

• •Critical: Build failures, broken links to external resources
• •Warning: Stale pages, orphaned pages, validation errors
• •Info: README out of date, minor inconsistencies

Offer to fix each category. Apply fixes in parallel where possible.

Improve Mode

Improve Site

When $ARGUMENTS is improve:

1. •Research latest Starlight docs via Context7 or web search for new features, components, or best practices
2. •Audit the site configuration:
   • •docs/astro.config.mjs — plugins, integrations, sidebar config
   • •docs/src/styles/custom.css — theming, visual polish
   • •docs/src/content/docs/index.mdx — landing page
3. •Propose improvements grouped by category:
   • •New pages: Missing content that should exist
   • •Navigation: Sidebar structure, grouping, ordering
   • •Visual: Theme enhancements, component usage, layout
   • •SEO: Meta descriptions, OpenGraph, structured data
   • •Performance: Image optimization, build config
4. •Ask the user before implementing — present proposals with effort estimates and let the user choose what to implement
5. •Implement approved improvements

Improve CLI Pipeline

When $ARGUMENTS is improve cli:

1. •Read wagents/cli.py, focusing on the docs generate command and its helpers
2. •Identify gaps in the generation pipeline:
   • •Missing metadata in generated frontmatter
   • •Poor MDX formatting or escaping
   • •Missing cross-references between assets
   • •Incomplete extraction of skill/agent information
3. •Ask the user before implementing — present proposed changes to the CLI with rationale
4. •Implement approved changes
5. •Re-run uv run wagents docs generate to verify
6. •Run cd docs && pnpm build to verify

Full Mode

Execute all modes in sequence:

1. •Sync: uv run wagents docs generate
2. •Maintain: Full health check, fix critical issues
3. •Enhance: Score and improve all pages (parallel subagents)
4. •Improve: Research and propose site improvements (ask first)

Key Principles

• •Wraps the CLI: Always call uv run wagents docs generate as the foundation. Never bypass or replace the CLI pipeline.
• •Extends the pipeline: Enhance on top of what the CLI generates. The CLI produces the structural baseline; this skill adds polish.
• •Can modify the pipeline: In improve cli mode, edit wagents/cli.py itself to improve the generation logic.
• •Invoke after asset changes: Run after creating or modifying skills, agents, or MCP servers. With disable-model-invocation: false, the model can auto-invoke this skill when it detects asset changes.
• •Parallel enhancement: Use subagent wave pattern for page-level enhancement work.
• •Non-destructive by default: In auto, sync, and enhance modes, preserve the CLI-generated structure. Add to it, do not replace it.
• •No approval gates in auto mode: When auto-triggered, sync and enhance without prompting the user.
• •Manual modes ask first: improve and improve cli modes present proposals and wait for approval before making changes.

Reference Files

Read these before enhancement work. They define the quality bar and component patterns to follow.

Critical Rules

• •NEVER delete pages that the CLI generates — only enhance them
• •ALWAYS run uv run wagents validate after any changes to asset files
• •ALWAYS run cd docs && pnpm build to verify the build after changes
• •When enhancing MDX, preserve the frontmatter generated by the CLI (title, description, and any other fields the CLI sets)
• •When enhancing, import Starlight components at the top of MDX files before using them in the body
• •Use _escape_mdx patterns — do not introduce raw JSX that breaks MDX parsing (escape {, <, > in prose; use {'{'} or backtick-wrap)
• •Reference files in references/ provide quality standards and component patterns — always read them before enhancement work
• •When spawning parallel subagents for enhancement, ensure no two subagents edit the same file (one subagent per page)
• •In auto mode, if the build fails after enhancement, revert the enhancement changes for the failing page and re-run the build
• •Do not add content that is fabricated or speculative — enhance based on what the source asset actually says