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:

Loads marketplace.json
- Reads the marketplace catalog
- Validates structure
- Builds component index
Scans Plugin Files
- Reads agent/command frontmatter
- Extracts skill metadata
- Builds comprehensive component list
Prepares Template Context
- Organizes plugins by category
- Creates component indexes
- Calculates statistics
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 updates:

Workflow

1. Plugin operation completes (add/update/remove)
2. Marketplace.json is updated
3. Invoke documentation-update skill
4. Documentation files regenerated
5. Changes ready to commit

Example Integration

python

# After creating/updating plugin
print("Updating documentation...")

# Run doc generator
import subprocess
result = subprocess.run(
    ["python", "plugins/claude-plugin/skills/documentation-update/doc_generator.py"],
    capture_output=True,
    text=True
)

if result.returncode == 0:
    print("✓ Documentation updated")
else:
    print(f"❌ Documentation update failed: {result.stderr}")

Template Examples

agents.md.j2

jinja2

# Agent Reference

This document lists all agents available across plugins in the marketplace.

{% for category, plugins in plugins_by_category.items() %}
## {{ category|title }}

{% for plugin in plugins %}
### {{ plugin.name }}

{{ plugin.description }}

**Agents:**

{% for agent in all_agents %}
{% if agent.plugin == plugin.name %}
- **{{ agent.name }}** (`{{ agent.model }}`)
  - {{ agent.description }}
  - File: `plugins/{{ plugin.name }}/agents/{{ agent.file }}`
{% endif %}
{% endfor %}

{% endfor %}
{% endfor %}

---
*Last updated: {{ now }}*
*Total agents: {{ stats.total_agents }}*

agent-skills.md.j2

jinja2

# Agent Skills Reference

This document catalogs all skills with progressive disclosure patterns.

{% for plugin in marketplace.plugins %}
## {{ plugin.name }}

{{ plugin.description }}

**Skills:**

{% for skill in all_skills %}
{% if skill.plugin == plugin.name %}
### {{ skill.name }}

{{ skill.description }}

- **Location:** `plugins/{{ plugin.name }}/skills/{{ skill.path }}/`
- **Structure:** SKILL.md + assets/ + references/

{% endif %}
{% endfor %}

{% endfor %}

---
*Last updated: {{ now }}*
*Total skills: {{ stats.total_skills }}*

Error Handling

Marketplace Not Found

Error: Marketplace file not found: .claude-plugin/marketplace.json
Suggestion: Ensure marketplace.json exists

Template Not Found

Error: Template file not found: assets/agents.md.j2
Suggestion: Ensure all template files exist in assets/

Invalid Plugin Structure

Warning: Plugin 'plugin-name' missing components
Suggestion: Verify plugin has agents or commands

Frontmatter Parse Error

Warning: Could not parse frontmatter in agents/agent-name.md
Suggestion: Check YAML frontmatter syntax

Best Practices

Always Regenerate After Changes
- Run after every plugin add/update/remove
- Ensure docs stay synchronized
- Commit documentation with plugin changes
Validate Before Generation
- Run marketplace validation first
- Fix any errors or warnings
- Ensure all files exist
Review Generated Output
- Check generated files for correctness
- Verify formatting and links
- Test any code examples
Template Maintenance
- Keep templates simple and readable
- Use consistent formatting
- Document template variables
Version Control
- Commit documentation changes
- Include in pull requests
- Document significant changes

Template Customization

Adding New Sections

To add a new section to a template:

Modify Template

jinja2

## New Section

{% for plugin in marketplace.plugins %}
### {{ plugin.name }}
[Your content here]
{% endfor %}

Update Context (if needed)
- Add new data to template context in doc_generator.py
- Process additional metadata
Test Output
- Run generator with dry-run
- Verify formatting
- Check for errors

Creating New Templates

To add a new documentation file:

Create Template
- Add
```
assets/newdoc.md.j2
```
- Define structure and content
Update Script
- Add to doc_generator.py template list
- Define output path
Test Generation
- Run generator
- Verify output
- Commit template and output

File Structure

plugins/claude-plugin/skills/documentation-update/
├── SKILL.md                      # This file
├── doc_generator.py              # Python implementation
├── assets/                       # Jinja2 templates
│   ├── agents.md.j2
│   ├── agent-skills.md.j2
│   ├── plugins.md.j2
│   └── usage.md.j2
└── references/                   # Optional examples
    └── template-examples.md

Requirements

Python 3.8+
No external dependencies (uses standard library only)
Access to
```
.claude-plugin/marketplace.json
```
Read access to plugin directories
Write access to
```
docs/
```
directory

Success Criteria

After running this skill:

✓ All documentation files generated
✓ Content matches marketplace state
✓ All links are valid
✓ Formatting is consistent
✓ Statistics are accurate
✓ No template rendering errors

Maintenance

Updating Templates

When marketplace structure changes:

Assess Impact
- Identify affected templates
- Determine required changes
Update Templates
- Modify Jinja2 templates
- Test with current data
Update Script
- Adjust context preparation if needed
- Add new data processing
Validate Output
- Regenerate all docs
- Review changes
- Test links and formatting

Version Compatibility

Templates should handle missing fields gracefully
Use Jinja2 default filters for optional data
Validate marketplace version compatibility

Example Output

The skill generates comprehensive, well-formatted documentation:

agents.md: ~500-1000 lines for 20-30 agents
agent-skills.md: ~300-600 lines for 30-50 skills
plugins.md: ~400-800 lines for 10-20 plugins
usage.md: ~200-400 lines of usage information

All files include:

Clear structure and headings
Formatted tables where appropriate
Links to source files
Statistics and metadata
Last updated timestamp

documentation-update

NPX Install

Tags

SKILL.md Content

Documentation Update Skill

Purpose

When to Use

Documentation Files

1. agents.md

2. agent-skills.md

3. plugins.md

4. usage.md

Template Structure

Template Variables

Python Script

Usage

Integration with Commands

Workflow

Example Integration

Template Examples

agents.md.j2

agent-skills.md.j2

Error Handling

Marketplace Not Found

Template Not Found

Invalid Plugin Structure

Frontmatter Parse Error

Best Practices

Template Customization

Adding New Sections

Creating New Templates

File Structure

Requirements

Success Criteria

Maintenance

Updating Templates

Version Compatibility

Example Output