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

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

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