documentation-update

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: documentation-update
description: Regenerates documentation files (agents.md, agent-skills.md, plugins.md, usage.md) from marketplace data using Jinja templates. Use when plugins are added, updated, or removed to keep documentation in sync.
---

# Documentation Update Skill

This skill automatically regenerates documentation files in the `docs/` directory by reading the marketplace catalog and applying Jinja2 templates.

## Purpose

Maintain synchronized documentation by:

- Generating agent reference documentation
- Creating skill catalog documentation
- Building plugin directory
- Updating usage guides
- Ensuring consistency across all docs

## When to Use

Use this skill when:

- A new plugin is added to the marketplace
- An existing plugin is updated (components added/removed)
- Agent or skill metadata changes
- Documentation needs to be regenerated
- Ensuring docs match marketplace state

## Documentation Files

This skill generates four main documentation files:

### 1. agents.md

Complete reference of all agents across all plugins:

- Organized by plugin
- Lists agent name, description, and model
- Includes links to agent files
- Shows agent capabilities and use cases

### 2. agent-skills.md

Catalog of all skills with progressive disclosure details:

- Organized by plugin
- Lists skill name and description
- Shows "Use when" triggers
- Includes skill structure information

### 3. plugins.md

Directory of all plugins in the marketplace:

- Organized by category
- Shows plugin name, description, and version
- Lists components (agents, commands, skills)
- Provides installation and usage information

### 4. usage.md

Usage guide and command reference:

- Getting started instructions
- Command usage examples
- Workflow patterns
- Integration guides

## Template Structure

Templates are stored in `assets/` using Jinja2 syntax:

```
assets/
├── agents.md.j2
├── agent-skills.md.j2
├── plugins.md.j2
└── usage.md.j2
```

### Template Variables

All templates receive the following context:

```python
{
  "marketplace": {
    "name": "marketplace-name",
    "owner": {...},
    "metadata": {...},
    "plugins": [...]
  },
  "plugins_by_category": {
    "category-name": [plugin1, plugin2, ...]
  },
  "all_agents": [
    {
      "plugin": "plugin-name",
      "name": "agent-name",
      "file": "agent-file.md",
      "description": "...",
      "model": "..."
    }
  ],
  "all_skills": [
    {
      "plugin": "plugin-name",
      "name": "skill-name",
      "path": "skill-path",
      "description": "..."
    }
  ],
  "all_commands": [
    {
      "plugin": "plugin-name",
      "name": "command-name",
      "file": "command-file.md",
      "description": "..."
    }
  ],
  "stats": {
    "total_plugins": 10,
    "total_agents": 25,
    "total_commands": 15,
    "total_skills": 30
  }
}
```

## Python Script

The skill includes a Python script `doc_generator.py` that:

1. **Loads marketplace.json**

   - Reads the marketplace catalog
   - Validates structure
   - Builds component index

2. **Scans Plugin Files**

   - Reads agent/command frontmatter
   - Extracts skill metadata
   - Builds comprehensive component list

3. **Prepares Template Context**

   - Organizes plugins by category
   - Creates component indexes
   - Calculates statistics

4. **Renders Templates**
   - Applies Jinja2 templates
   - Generates documentation files
   - Writes to docs/ directory

### Usage

```bash
# Generate all documentation files
python doc_generator.py

# Generate specific file only
python doc_generator.py --file agents

# Dry run (show output without writing)
python doc_generator.py --dry-run

# Specify custom paths
python doc_generator.py \
  --marketplace .claude-plugin/marketplace.json \
  --templates plugins/claude-plugin/skills/documentation-update/assets \
  --output docs
```

## Integration with Commands

The `/claude-plugin:create` and `/claude-plugin:update` commands should invoke this skill automatically after marketplace upd