Back to Details

documentation-update

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Documentation Update Skill

文档更新Skill

This skill automatically regenerates documentation files in the 
docs/
directory by reading the marketplace catalog and applying Jinja2 templates.
该Skill会通过读取市场目录并应用Jinja2模板，自动重新生成
docs/
目录下的文档文件。

Purpose

用途

Maintain synchronized documentation by:
  • Generating agent reference documentation
  • Creating skill catalog documentation
  • Building plugin directory
  • Updating usage guides
  • Ensuring consistency across all docs
通过以下方式保持文档同步：
  • 生成Agent参考文档
  • 创建Skill目录文档
  • 构建插件目录
  • 更新使用指南
  • 确保所有文档的一致性

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
在以下场景中使用该Skill：
  • 向市场中添加新插件时
  • 更新现有插件（添加/移除组件）时
  • Agent或Skill元数据发生变化时
  • 需要重新生成文档时
  • 确保文档与市场状态匹配时

Documentation Files

文档文件

This skill generates four main documentation files:
该Skill会生成四个主要文档文件：

1. agents.md

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
所有插件中全部Agent的完整参考：
  • 按插件分类
  • 列出Agent名称、描述和模型
  • 包含指向Agent文件的链接
  • 展示Agent的能力和使用场景

2. agent-skills.md

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
包含渐进式披露细节的全Skill目录：
  • 按插件分类
  • 列出Skill名称和描述
  • 展示“适用场景”触发条件
  • 包含Skill结构信息

3. plugins.md

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
市场中所有插件的目录：
  • 按类别分类
  • 展示插件名称、描述和版本
  • 列出组件（Agent、命令、Skill）
  • 提供安装和使用信息

4. usage.md

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
模板存储在
assets/
目录中，采用Jinja2语法：
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
{
  "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

Python脚本

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
该Skill包含一个Python脚本
doc_generator.py
，它会执行以下操作：
  1. 加载marketplace.json
    • 读取市场目录
    • 验证结构
    • 构建组件索引
  2. 扫描插件文件
    • 读取Agent/命令的前置元数据
    • 提取Skill元数据
    • 构建完整的组件列表
  3. 准备模板上下文
    • 按类别组织插件
    • 创建组件索引
    • 计算统计数据
  4. 渲染模板
    • 应用Jinja2模板
    • 生成文档文件
    • 写入到docs/目录

Usage

使用方法

bash
undefined
bash
undefined

Generate all documentation files

生成所有文档文件

python doc_generator.py
python doc_generator.py

Generate specific file only

仅生成指定文件

python doc_generator.py --file agents
python doc_generator.py --file agents

Dry run (show output without writing)

试运行（仅显示输出不写入文件）

python doc_generator.py --dry-run
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
undefined
python doc_generator.py
--marketplace .claude-plugin/marketplace.json
--templates plugins/claude-plugin/skills/documentation-update/assets
--output docs
undefined

Integration with Commands

与命令的集成

The 
/claude-plugin:create
and 
/claude-plugin:update
commands should invoke this skill automatically after marketplace updates:
/claude-plugin:create
和
/claude-plugin:update
命令应在市场更新后自动调用该Skill：

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
1. 插件操作完成（添加/更新/移除）
2. Marketplace.json被更新
3. 调用documentation-update skill
4. 文档文件重新生成
5. 变更准备就绪可提交

Example Integration

集成示例

python
undefined
python
undefined

After creating/updating plugin

创建/更新插件后

print("Updating documentation...")
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}")
undefined
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}")
undefined

Template Examples

模板示例

agents.md.j2

agents.md.j2

jinja2
undefined
jinja2
undefined

Agent Reference

Agent Reference

This document lists all agents available across plugins in the marketplace.
{% for category, plugins in plugins_by_category.items() %}
This document lists all agents available across plugins in the marketplace.
{% for category, plugins in plugins_by_category.items() %}

{{ category|title }}

{{ category|title }}

{% for plugin in plugins %}
{% for plugin in plugins %}

{{ plugin.name }}

{{ 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 }}
undefined
{{ 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 }}
undefined

agent-skills.md.j2

agent-skills.md.j2

jinja2
undefined
jinja2
undefined

Agent Skills Reference

Agent Skills Reference

This document catalogs all skills with progressive disclosure patterns.
{% for plugin in marketplace.plugins %}
This document catalogs all skills with progressive disclosure patterns.
{% for plugin in marketplace.plugins %}

{{ plugin.name }}

{{ plugin.name }}

{{ plugin.description }}
Skills:
{% for skill in all_skills %} {% if skill.plugin == plugin.name %}
{{ plugin.description }}
Skills:
{% for skill in all_skills %} {% if skill.plugin == plugin.name %}

{{ skill.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 }}
undefined
{{ 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 }}
undefined

Error Handling

错误处理

Marketplace Not Found

未找到市场文件

Error: Marketplace file not found: .claude-plugin/marketplace.json
Suggestion: Ensure marketplace.json exists
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/
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
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
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
  1. 变更后始终重新生成
    • 每次添加/更新/移除插件后运行
    • 确保文档保持同步
    • 随插件变更一起提交文档
  2. 生成前先验证
    • 先运行市场验证
    • 修复所有错误或警告
    • 确保所有文件存在
  3. 审查生成的输出
    • 检查生成文件的正确性
    • 验证格式和链接
    • 测试所有代码示例
  4. 模板维护
    • 保持模板简洁易读
    • 使用一致的格式
    • 记录模板变量
  5. 版本控制
    • 提交文档变更
    • 包含在拉取请求中
    • 记录重大变更

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
要向模板中添加新章节：
  1. 修改模板
    jinja2
    ## New Section

{% for plugin in marketplace.plugins %}
### {{ plugin.name }}
[Your content here]
{% endfor %}
  2. 更新上下文（如需要）
    • 在doc_generator.py中向模板上下文添加新数据
    • 处理额外的元数据
  3. 测试输出
    • 以试运行模式运行生成器
    • 验证格式
    • 检查错误

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
要添加新的文档文件：
  1. 创建模板
    • 添加
      assets/newdoc.md.j2
    • 定义结构和内容
  2. 更新脚本
    • 在doc_generator.py的模板列表中添加新模板
    • 定义输出路径
  3. 测试生成
    • 运行生成器
    • 验证输出
    • 提交模板和输出

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
plugins/claude-plugin/skills/documentation-update/
├── SKILL.md                      # 本文档
├── doc_generator.py              # Python实现
├── assets/                       # Jinja2模板
│   ├── agents.md.j2
│   ├── agent-skills.md.j2
│   ├── plugins.md.j2
│   └── usage.md.j2
└── references/                   # 可选示例
    └── 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
  • Python 3.8+
  • 无外部依赖（仅使用标准库）
  • 可访问
    .claude-plugin/marketplace.json
  • 对插件目录有读取权限
  • 对
    docs/
    目录有写入权限

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
运行该Skill后：
  • ✓ 所有文档文件已生成
  • ✓ 内容与市场状态匹配
  • ✓ 所有链接有效
  • ✓ 格式一致
  • ✓ 统计数据准确
  • ✓ 无模板渲染错误

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
当市场结构发生变化时：
  1. 评估影响
    • 确定受影响的模板
    • 确定所需的变更
  2. 更新模板
    • 修改Jinja2模板
    • 使用当前数据测试
  3. 更新脚本
    • 如需要调整上下文准备逻辑
    • 添加新的数据处理步骤
  4. 验证输出
    • 重新生成所有文档
    • 审查变更
    • 测试链接和格式

Version Compatibility

版本兼容性

  • Templates should handle missing fields gracefully
  • Use Jinja2 default filters for optional data
  • Validate marketplace version compatibility
  • 模板应能优雅处理缺失字段
  • 对可选数据使用Jinja2默认过滤器
  • 验证市场版本兼容性

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
该Skill会生成全面、格式规范的文档：
  • agents.md：20-30个Agent对应约500-1000行内容
  • agent-skills.md：30-50个Skill对应约300-600行内容
  • plugins.md：10-20个插件对应约400-800行内容
  • usage.md：约200-400行使用说明
所有文件都包含：
  • 清晰的结构和标题
  • 适当情况下使用格式化表格
  • 指向源文件的链接
  • 统计数据和元数据
  • 最后更新时间戳