• AI 技能/插件
• 人工智能

这篇指南面向希望向 awesome-claude-code-subagents 仓库提交 Claude Code 子代理（Subagent）或工具的开发者，完整梳理 CONTRIBUTING.md 中定义的贡献流程：从新 Subagent 的分类选择、必改文件清单，到插件版本同步机制与工具（Skill）的目录规范。读完本文，你将掌握一套可复用的贡献检查清单，能够按仓库既有模板高质量地提交 PR，并理解插件版本（plugin.json / marketplace.json）如何驱动claude plugin update向用户推送更新。

一、贡献前先理解仓库的组织结构

在动手提交之前，先明确仓库的物理布局，这直接决定了"该把文件放哪里、该改哪些文件"：

• categories/：全部 Subagent 按主题分为 10 个编号分类目录（如01-core-development、02-language-specialists、03-infrastructure），每个分类下既有各 agent 的.md定义文件，也有分类自己的README.md和.claude-plugin/plugin.json；
• tools/：可选的 Claude Code Skill 目录，目前内置了 subagent-catalog（一个用于浏览、检索、拉取 Subagent 定义的命令集合），其内部是README.md+ 命令文件（带 YAML frontmatter）+config.sh共享脚本的结构；
• 根目录文件：主 README.md（分类索引与安装说明）、CLAUDE.md、install-agents.sh（交互式安装脚本）、.claude-plugin/marketplace.json（市场插件清单）。

CONTRIBUTING.md 的核心逻辑正是围绕"新增 Subagent""更新插件版本""新增工具"三条主线的文件变更约束展开。

二、如何新增一个 Subagent：四步主流程

CONTRIBUTING.md 规定新增 Subagent 需按以下顺序执行：

1. 选择正确的分类（Choose the right category）——将你的 Subagent 放入最贴切的分类文件夹。例如一个语言专精型 agent 应进入categories/02-language-specialists/，基础设施类进入categories/03-infrastructure/；
2. 测试你的 Subagent（Test your subagent）——确保它能与 Claude Code 正常工作，即 frontmatter 中的name、description、tools、model合法，系统提示词逻辑自洽；
3. 更新必需文件（Update required files）——同时维护主 README、分类 README、agent 定义文件三处（详见下节）；
4. 提交 PR（Submit a PR）——附带清晰的用途说明。

主 README 的贡献入口（README.md）也印证了这三类可接受贡献：通过 PR 提交新 Subagent、改进既有定义、报告问题。

三、每个 Subagent 必须包含的七要素

CONTRIBUTING.md 要求每个 Subagent 定义至少覆盖：

• 清晰的角色定义（Clear role definition）
• 专长领域清单（List of expertise areas）
• 所需的 MCP 工具（Required MCP tools, if any）
• 通信协议示例（Communication protocol examples）
• 核心能力（Core capabilities）
• 示例使用场景（Example usage scenarios）
• 最佳实践（Best practices）

以仓库现成的 python-pro 为范本，可以直观看到这七要素如何落到实际文件：

• frontmatter（角色与激活条件）：name: python-pro、description写明"构建类型安全的生产级 Python 代码时调用本 agent"、tools: Read, Write, Edit, Bash, Glob, Grep、model: sonnet；
• 角色定义：正文首段即声明"senior Python developer，掌握 Python 3.11+ 生态"；
• 专长清单：后续分段覆盖类型系统（TypeVar/ParamSpec/Protocol/TypedDict）、异步并发（AsyncIO/concurrent.futures）、Web 框架（FastAPI/Django/SQLAlchemy/Pydantic）、数据科学、性能优化、安全最佳实践等；
• 通信协议示例：文件中的Communication Protocol章节给出了标准 JSON 交互样例（如request_type: "get_python_context"），便于多 agent 协作时解析；
• 示例使用场景与最佳实践：Development Workflow章节按 Codebase Analysis → Implementation → Quality Assurance 三阶段展开，并附状态上报 JSON 示例与质量检查清单。

新贡献者可以完全复刻这一文件结构，替换为自身领域的角色、专长与协议内容。

四、添加新 Agent 时 MUST 更新的三处文件

CONTRIBUTING.md 用MUST强调了三处联动更新，缺一不可：

1. 主 README.md

在主 README 对应分类小节中按字母序加入 agent 链接，格式为：

- **agent-name** - Brief description

例如 README 中语言分类的条目写法（见 README.md）：

- [**typescript-pro**](https://link.gitcode.com/i/f5ec9bc407bffb494cec7706835c4f88) - TypeScript specialist

2. 分类 README.md（如categories/02-language-specialists/README.md）

分类 README 是一个独立成篇的导航文档，需同步更新：

• Available Subagents小节：追加详细描述（角色简介 + "Use when" 使用时机）；
• Quick Selection Guide表格：在语言/框架 → Subagent → 适用场景的映射表中插入新行；
• 若适用，更新Common Technology Stacks小节（如把新 agent 组合进"Modern Web Application / Mobile Development / Enterprise Backend"等推荐技术栈组合）。

以 02-language-specialists/README.md 为例，其 Quick Selection Guide 的每一行都保持| 语言/框架 | **agent-name** | 最佳适用场景 |的统一格式，新条目必须维持同样对齐与风格，避免破坏表格可读性。

3. 你的 Agent 文件（如categories/02-language-specialists/your-agent.md）

遵循标准模板结构（见下节"模板结构"），包含全部必需章节，且 frontmatter 与 README 中的描述保持口径一致。

五、Agent 文件的标准模板结构

CONTRIBUTING.md 依赖仓库 README 中定义的标准化模板（README.md），新 agent 应严格对齐：

--- name: subagent-name description: When this agent should be invoked tools: Read, Write, Edit, Bash, Glob, Grep model: sonnet --- You are a [role description and expertise areas]... [Agent-specific checklists, patterns, and guidelines]... ## Communication Protocol Inter-agent communication specifications... ## Development Workflow Structured implementation phases...

两个影响实际运行的关键字段值得注意：

• model（智能模型路由）：决定该 agent 默认由哪个 Claude 模型处理——opus用于深度推理（如架构评审、安全审计）、sonnet用于日常编码、haiku用于快速任务；也支持设model: inherit跟随主会话模型。贡献者可按任务复杂度合理选择；
• tools（最小权限原则）：只读型 agent（reviewers/auditors）建议Read, Grep, Glob；研究型 agent 追加WebFetch, WebSearch；代码编写型 agent 使用Read, Write, Edit, Bash, Glob, Grep。每个 agent 只声明完成任务所需的最小工具集，需要时可再扩展 MCP 服务。

六、插件更新时的版本管理要求

这是 CONTRIBUTING.md 中最容易被忽略、却直接影响用户体验的规则：任何categories/<category>下*.md文件变更后，必须同步 bump 版本，否则用户通过claude plugin update无法收到更新。

1. 提升分类插件版本

修改categories/<category>/.claude-plugin/plugin.json中的version字段。以语言分类为实例（categories/02-language-specialists/.claude-plugin/plugin.json）：

{ "name": "voltagent-lang", "version": "1.0.4", "description": "Language-specific expert agents with deep framework knowledge - Python, TypeScript, Go, Rust, Java, and more", "license": "MIT", "agents": [ "./angular-architect.md", "./cpp-pro.md", ... ] }

注意agents数组必须一一列出该分类下的全部 agent 文件，新增 agent 时同时要在数组中追加对应条目（这是 CLAUDE 插件加载 agent 清单的依据）。

2. 保持市场插件版本同步

修改根目录.claude-plugin/marketplace.json，将对应 plugin 条目的version更新为与分类插件一致的版本号。该文件的每个 plugin 条目均包含name、source（指向分类目录的相对路径）、description、version、category与keywords（.claude-plugin/marketplace.json）。例如：

{ "name": "voltagent-lang", "source": "./categories/02-language-specialists", "description": "Language-specific expert agents with deep framework knowledge - Python, TypeScript, Go, Rust, Java, and more", "version": "1.0.4", "category": "development", "keywords": ["python", "typescript", "golang", "rust", "java", ...] }

两处版本号必须保持完全一致，否则claude plugin update的版本比对会失效。这属于版本管理的双写约束，PR 自检时应重点核对。

七、如何添加一个 Tool（Claude Code Skill）

Tools 是增强目录体验的 Claude Code Skills（发现、浏览、管理 Subagent），与 agent 文件是两条独立的贡献线。CONTRIBUTING.md 规定：

1. 在tools/下创建以工具名命名的文件夹；
2. 包含必需文件：
   • README.md——安装与使用文档；
   • 命令文件（.md）——每个命令一个文件，带 YAML frontmatter（含name与description）；
   • 辅助脚本（.sh、.py）——需要共享工具函数时的公共脚本；
3. 遵循 Skill 最佳实践：frontmatter 中的name/description要有描述性，description中写入触发短语，错误处理要友好；
4. 更新主 README：在 🧰 Tools 小节添加工具条目；
5. 提交前本地测试。

仓库自带的 tools/subagent-catalog 是这一规范的最佳样例：

• 目录结构：README.md+search.md、fetch.md、list.md、invalidate.md四个命令文件 +config.sh共享脚本；
• 命令文件带 YAML frontmatter，如 search.md 开头：

  --- name: search description: "Search the awesome-claude-code-subagents catalog. Use when user wants to find, discover, or browse available subagents by name, category, or capability." ---

• 共享脚本 config.sh 集中管理配置（12 小时缓存 TTL、缓存文件路径、GitHub raw URL）并提供subagent_catalog_ensure_cache等函数，被各命令文件source复用——这正是"辅助脚本共享工具函数"的落地方式；
• 错误处理：fetch.md中给出了"not found → 建议先 search""multiple matches → 列出让用户指定""network error → 检查网络重试"的分支表，符合"以用户友好信息处理错误"的要求。

八、行为准则与 PR 流程

行为准则（Code of Conduct）

CONTRIBUTING.md 明确要求贡献者：保持尊重与包容、提供建设性反馈、提交前测试贡献、遵循现有格式与结构。这也是主 README 中"不接受以推广产品/公司为主要目的的 PR、Subagent 必须对 Claude Code 用户真正有用且保持厂商中立"（README.md）一以贯之的社区基调。

Pull Request 流程

1. Fork 仓库并克隆到本地（git clone https://gitcode.com/gh_mirrors/aw/awesome-claude-code-subagents）；
2. 创建功能分支：git checkout -b feature/new-subagent；
3. 按模板添加 Subagent；
4. 更新所有必需位置：主 README（分类小节、字母序）、分类 README（描述、表格）；
5. 校验所有链接可正确解析（仓库是只读的，提交前请自行检查相对路径）；
6. 提交 PR 并附清晰描述，说明该 Subagent 的用途。

质量指南（Quality Guidelines）

CONTRIBUTING.md 的验收底线可浓缩为四句话：

• Subagent 应结构良好且经过测试；
• 包含清晰的文档；
• 提供实用的示例；
• 确保与 Claude Code 的兼容性。

建议在 PR 描述中直接列出：选择的分类、更新了哪三处文件、plugin.json 与 marketplace.json 的版本号、以及本地测试结论。

九、许可证与贡献者的注意事项

CONTRIBUTING.md 末尾明确：

• MIT License：贡献即表示同意你的贡献以 MIT 许可发布；
• 免责声明：仓库中所有 Subagent 均按"as is"提供、不附带任何担保；维护者不审计、不保证任何贡献的安全性与正确性，也不对使用引发的问题承担责任。

这意味着贡献者有义务对自身提交的 agent 定义负责，使用者也应在接入生产环境前自行审查。这一立场同样写在主 README.md 与 LICENSE 中。

十、一份可复用的贡献检查清单

综合上述规范，提交一个完整 PR 前请逐项核对：

• 分类选择正确（categories/<编号>-<主题>/）
• Agent 文件包含七要素（角色、专长、MCP 工具、通信协议、核心能力、使用场景、最佳实践）
• frontmatter 四字段齐全（name、description、tools、model）
• 主 README 分类小节已按字母序添加链接
• 分类 README 的 Available Subagents、Quick Selection Guide、Common Technology Stacks 已同步
• categories/<分类>/.claude-plugin/plugin.json的version已 bump，且agents数组包含新文件
• .claude-plugin/marketplace.json对应条目版本与分类插件一致
• 若新增 Tool：tools/下目录、README.md、命令文件（带 frontmatter）、共享脚本齐备，并已更新主 README 的 Tools 小节
• 本地用 Claude Code 实测通过，全部链接解析正常
• 分支名规范、PR 描述清晰

遵循这份清单，你的贡献将能无缝融入 158+ Subagent 的目录体系，并被插件更新通道（claude plugin update）正确推送给所有用户。

• AI 技能/插件
• 人工智能