Docs Refresh

Purpose

Keep generated documentation in sync with source files. Manages skill reference documentation, project-level Claude instructions, and validates human-written documentation.

When to Use

• After modifying skill configurations
• When adding or removing skills
• Before creating PRs that change documentation sources
• When CI reports documentation is out of sync

Quick Reference

• Setup: /docs-refresh configure (run once during framework setup)
• Config: .claude/skills/docs-refresh.yaml
• Stop hook: ${CLAUDEPLUGINROOT}/infra/refresh-and-validate.sh — on Stop this installs the bundled skill infra into .claude/, regenerates the skills reference, and validates skill YAML.

How it works (global-install model)

This plugin is auto-discovered from the plugin cache; its files do not live in the project. ${CLAUDEPLUGINROOT} is available to hook processes only, not to the model's Bash calls, so the deterministic skills-reference generation and validation run from the Stop hook (which carries the bundled infra/), not from the procedure. The Stop hook also installs the infra into .claude/ (idempotent) so you can re-run task -t .claude/Taskfile.skills.yaml skills-reference manually afterward.

Configure Mode

Configure documentation settings during framework setup:

/docs-refresh configure

Discovers:

• Documentation directory (docs/, documentation/, wiki/)
• Documentation format (markdown, rst, mdx)
• CLAUDE.md location
• Generated vs human-written documentation

Outputs: .claude/skills/docs-refresh.yaml

# Documentation configuration
# Generated by: /docs-refresh configure

paths:
  docs_directory: "docs/"
  claude_md: "CLAUDE.md"

format: markdown

generated_docs:
  - path: "docs/api/"
    source: "src/"
    generator: "task docs:generate-api"

human_docs:
  - "README.md"
  - "CONTRIBUTING.md"
  - "docs/guides/"

Discovery Procedure

1. Detect docs directory by checking common locations
2. Detect format from file extensions (.md, .rst, .mdx)
3. Find CLAUDE.md in project root
4. Identify generated docs by looking for generator configs
5. Propose configuration to user for approval
6. Save to .claude/skills/docs-refresh.yaml

Commands

Skills-reference generation is automatic on Stop (via the bundled infra in the Stop hook — see above). After the first run the infra is installed into .claude/, so you can also regenerate it manually:

# Generate skills reference documentation (outputs: docs/skills/REFERENCE.md)
task -t .claude/Taskfile.skills.yaml skills-reference

Project-specific documentation commands are configured in the project's Taskfile:

# Regenerate all documentation (project-specific)
task docs:refresh

# Check if docs are in sync (CI mode)
task docs:check

What It Manages

Documentation Sources

Documentation sources are configured per-project in skill.yaml:

documentation_sources:
  api_docs:
    sources:
      - path: "${DOCS_PATH}/api/"
    update_trigger: "When API endpoints change"

  guides:
    sources:
      - path: "${DOCS_PATH}/"
    update_trigger: "When workflows change"

CLAUDE.md Skills Table

The skills table in CLAUDE.md lists all skills and when to use them:

| Skill | When to Use |
|-------|-------------|
| `setup` | Setting up a new development environment |
| `commit` | Creating conventional commits |

When adding/removing skills:

1. Update the skills table in CLAUDE.md
2. Run documentation refresh command
3. Commit both files together

Patterns

Never Edit Generated Docs

Generated documentation should never be manually edited:

BAD:  vim docs/api/generated.md
GOOD: Update source code, then regenerate docs

Docs With Code

Update documentation when changing related code:

1. Implement the feature
2. Update relevant documentation
3. Regenerate any generated docs
4. Commit code and docs together

When It Fails

1. Documentation out of sync: Run refresh command to regenerate
2. Source files invalid: Fix syntax errors in source files
3. Missing CLAUDE.md: Create project instructions file

Configuration

Config Location

Config path depends on how the plugin was installed:

Precedence when reading (first found wins):

1. .claude/skills/docs-refresh.local.yaml
2. .claude/skills/docs-refresh.yaml
3. Skill defaults

Config Fields

Set via /docs-refresh configure:

Automation

See skill.yaml for the full procedure and customization guide. See sharp-edges.yaml for common failure modes.