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:

{
  "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

# 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

# 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

# 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

# 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

1. •

   Always Regenerate After Changes

   • •Run after every plugin add/update/remove
   • •Ensure docs stay synchronized
   • •Commit documentation with plugin changes
2. •

   Validate Before Generation

   • •Run marketplace validation first
   • •Fix any errors or warnings
   • •Ensure all files exist
3. •

   Review Generated Output

   • •Check generated files for correctness
   • •Verify formatting and links
   • •Test any code examples
4. •

   Template Maintenance

   • •Keep templates simple and readable
   • •Use consistent formatting
   • •Document template variables
5. •

   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:

1. •

   Modify Template

   jinja2

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

2. •

   Update Context (if needed)

   • •Add new data to template context in doc_generator.py
   • •Process additional metadata
3. •

   Test Output

   • •Run generator with dry-run
   • •Verify formatting
   • •Check for errors

Creating New Templates

To add a new documentation file:

1. •

   Create Template

   • •Add assets/newdoc.md.j2
   • •Define structure and content
2. •

   Update Script

   • •Add to doc_generator.py template list
   • •Define output path
3. •

   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:

1. •

   Assess Impact

   • •Identify affected templates
   • •Determine required changes
2. •

   Update Templates

   • •Modify Jinja2 templates
   • •Test with current data
3. •

   Update Script

   • •Adjust context preparation if needed
   • •Add new data processing
4. •

   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