documentation-update

文档更新技能

此技能会读取市场目录并应用 Jinja2 模板，自动重新生成 docs/ 目录中的文档文件。

用途

通过以下方式维护同步文档：

• 生成 Agent 参考文档
• 创建技能目录文档
• 构建插件目录
• 更新使用指南
• 确保所有文档保持一致

适用场景

在以下情况使用此技能：

• 市场中添加了新插件
• 现有插件已更新（添加或移除了组件）
• Agent 或技能元数据发生变化
• 需要重新生成文档
• 确保文档与市场状态一致

文档文件

此技能会生成四个主要文档文件：

1. agents.md

所有插件中 Agent 的完整参考文档：

• 按插件整理
• 列出 Agent 名称、描述和模型
• 包含 Agent 文件的链接
• 展示 Agent 的能力和用例

2. agent-skills.md

所有技能的目录，包含渐进式披露详情：

• 按插件整理
• 列出技能名称和描述
• 展示“适用场景”触发条件
• 包含技能结构信息

3. plugins.md

市场中所有插件的目录：

• 按类别整理
• 展示插件名称、描述和版本
• 列出组件（Agent、命令、技能）
• 提供安装和使用信息

4. usage.md

使用指南和命令参考：

• 入门说明
• 命令使用示例
• 工作流模式
• 集成指南

模板结构

模板使用 Jinja2 语法，存储在 assets/ 中：

assets/
├── agents.md.j2
├── agent-skills.md.j2
├── plugins.md.j2
└── usage.md.j2

模板变量

所有模板都会接收以下上下文：

{
  "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 脚本

此技能包含一个 Python 脚本 doc_generator.py，用于：

1. 加载 marketplace.json

   • 读取市场目录
   • 验证结构
   • 构建组件索引

2. 扫描插件文件

   • 读取 Agent/命令 frontmatter
   • 提取技能元数据
   • 构建全面的组件列表

3. 准备模板上下文

   • 按类别整理插件
   • 创建组件索引
   • 计算统计数据

4. 渲染模板

   • 应用 Jinja2 模板
   • 生成文档文件
   • 写入 docs/ 目录

用法

# 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

与命令集成

/claude-plugin:create 和 /claude-plugin:update 命令应在市场更新后自动调用此技能：

工作流

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

集成示例

# 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}")

模板示例

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: Marketplace file not found: .claude-plugin/marketplace.json
Suggestion: Ensure marketplace.json exists

未找到模板

Error: Template file not found: assets/agents.md.j2
Suggestion: Ensure all template files exist in assets/

插件结构无效

Warning: Plugin 'plugin-name' missing components
Suggestion: Verify plugin has agents or commands

Frontmatter 解析错误

Warning: Could not parse frontmatter in agents/agent-name.md
Suggestion: Check YAML frontmatter syntax

最佳实践

1. 更改后务必重新生成

   • 每次添加、更新或移除插件后运行
   • 确保文档保持同步
   • 将文档与插件更改一起提交

2. 生成前进行验证

   • 先运行市场验证
   • 修复所有错误或警告
   • 确保所有文件均存在

3. 检查生成结果

   • 检查生成的文件是否正确
   • 验证格式和链接
   • 测试所有代码示例

4. 维护模板

   • 保持模板简洁易读
   • 使用一致的格式
   • 记录模板变量

5. 版本控制

   • 提交文档更改
   • 将文档更改纳入拉取请求
   • 记录重大更改

自定义模板

添加新章节

向模板添加新章节：

1. 修改模板

   ## New Section
   
   {% for plugin in marketplace.plugins %}
   ### {{ plugin.name }}
   [Your content here]
   {% endfor %}
   

2. 更新上下文（如有需要）

   • 在 doc_generator.py 中向模板上下文添加新数据
   • 处理额外的元数据

3. 测试输出

   • 使用 dry-run 运行生成器
   • 验证格式
   • 检查错误

创建新模板

要添加新的文档文件：

1. 创建模板

   • 添加 assets/newdoc.md.j2
   • 定义结构和内容

2. 更新脚本

   • 将其添加到 doc_generator.py 模板列表
   • 定义输出路径

3. 测试生成

   • 运行生成器
   • 验证输出
   • 提交模板和输出

文件结构

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

要求

• Python 3.8+
• 无外部依赖（仅使用标准库）
• 访问 .claude-plugin/marketplace.json
• 插件目录的读取权限
• docs/ 目录的写入权限

成功标准

运行此技能后：

• ✓ 生成所有文档文件
• ✓ 内容与 marketplace 状态一致
• ✓ 所有链接均有效
• ✓ 格式保持一致
• ✓ 统计数据准确
• ✓ 无模板渲染错误

维护

更新模板

当 marketplace 结构发生变化时：

1. 评估影响

   • 找出受影响的模板
   • 确定所需的更改

2. 更新模板

   • 修改 Jinja2 模板
   • 使用当前数据进行测试

3. 更新脚本

   • 根据需要调整上下文准备工作
   • 添加新的数据处理

4. 验证输出

   • 重新生成所有文档
   • 检查更改
   • 测试链接和格式

版本兼容性

• 模板应能妥善处理缺失字段
• 对可选数据使用 Jinja2 默认过滤器
• 验证 marketplace 版本兼容性

示例输出

此技能会生成全面、格式规范的文档：

• agents.md：20-30 个 Agent，约 500-1000 行
• agent-skills.md：30-50 个技能，约 300-600 行
• plugins.md：10-20 个插件，约 400-800 行
• usage.md：约 200-400 行使用说明

所有文件均包含：

• 清晰的结构和标题
• 适当格式化的表格
• 指向源文件的链接
• 统计数据和元数据
• 上次更新时间戳