Initial commit
This commit is contained in:
Zhongwei Li
467
skills/documentation-update/SKILL.md
Normal file
467
skills/documentation-update/SKILL.md
Normal file
@@ -0,0 +1,467 @@
|
||||
---
|
||||
name: documentation-update
|
||||
description: Regenerates documentation files (agents.md, agent-skills.md, plugins.md, usage.md) from marketplace data using Jinja templates. Use when plugins are added, updated, or removed to keep documentation in sync.
|
||||
---
|
||||
|
||||
# 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:
|
||||
|
||||
```python
|
||||
{
|
||||
"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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```python
|
||||
# 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
|
||||
|
||||
```jinja2
|
||||
# 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
|
||||
|
||||
```jinja2
|
||||
# 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
|
||||
Reference in New Issue
Block a user