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:

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

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 %}

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 %}

{{ skill.name }}

{{ skill.description }}

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

{% endif %}

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

New Section

{% for plugin in marketplace.plugins %}

{{ plugin.name }}

[Your content here]

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