Documentation Update

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 filespython doc_generator.py
# Generate specific file onlypython doc_generator.py --file agents
# Dry run (show output without writing)python doc_generator.py --dry-run
# Specify custom pathspython 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 updated3. Invoke documentation-update skill4. Documentation files regenerated5. Changes ready to commit

Example Integration

# After creating/updating pluginprint("Updating documentation...")
# Run doc generatorimport subprocessresult = 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.jsonSuggestion: Ensure marketplace.json exists

Template Not Found

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

Invalid Plugin Structure

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

Frontmatter Parse Error

Warning: Could not parse frontmatter in agents/agent-name.mdSuggestion: 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