Regenerates documentation files (agents.md, agent-skills.md, plugins.md, usage.md) from marketplace data using Jinja templates. Use when plugins are added,…
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 timestampdon't have the plugin yet? install it then click "run inline in claude" again.