| name | agent-trainer |
| description | 为 AI Agent 创建元规则和领域知识,帮助用户在不熟悉领域建立 Agent 的思考方式和行为准则。专注于抽象的行事风格而非具体技术约束。适用场景:(1) 创建新 Agent 缺少行为准则,(2) 更新现有 Agent 的元规则或知识,(3) 用户不熟悉目标领域需要搜索最佳实践,(4) 希望 Agent 跨项目保持一致工作风格。 |
Agent 训练营
概述
帮助用户为 AI Agent 创建元规则(思考方式、行为准则)和领域知识库(参考文档),而非具体技术约束。
核心理念:
- 元规则 → Agent 的行事风格、Checklist、决策准则(抽象、跨项目)
- 领域知识 → 最佳实践参考文档(软约束、按需加载)
- 具体约束 → 应该写在项目仓库的
CLAUDE.md,不在这里重复
平台说明:
- Codex 平台加载
AGENTS.md,Claude Code 平台加载 CLAUDE.md
- 本文档统一用
CLAUDE.md 代指,实际使用时根据平台选择对应文件
核心原则
将分散的领域知识转化为结构化的元规则和知识库,重点是培养 Agent 的思考方式,而非堆砌技术规则。
避免重复项目规则:项目 CLAUDE.md 的技术约束(TypeScript 规范、测试要求等)会被 Agent 自动加载,不应在 Agent 配置中重复。
工作流程总览
创建流程(8 个阶段)
- 模式选择 → 判断 Agent 是否存在
- 训练模式 → 通用领域 vs 项目专用
- 角色定义 → 职责、边界、成功标准(需用户确认)
- 项目分析 → 提取行为风格(仅模式 B)
- 知识需求 → 确定元规则和知识类别
- 搜索过滤 → 2 轮 ReAct,Tier A/B/C/D 质量分级
- 规则提取 → 元规则 vs 领域知识(需用户确认)
- 生成文件 → CLAUDE.md + knowledge/
- 验证迭代 → 确认或调整
更新流程(7 个阶段)
U1. 配置分析 → 读取现有状态
U2. 更新类型 → 增量/重构/修正
U3. 目标确认 → 影响范围
U4. 差量搜索 → 只获取需更新的部分
U5. 合并冲突 → 解决冲突,展示变更
U6. 增量更新 → 自动备份,只修改受影响部分
U7. 验证回滚 → 确认或回滚
创建流程详解
Stage 0: 模式选择
检查 Agent 目录是否存在:
- 不存在 → 创建流程(Stage 1)
- 已存在 → 更新流程(Stage U1)
Stage 1: 训练模式选择
模式 A:通用领域 Agent
- 适用于多个项目的通用角色
- 从网络搜索领域最佳实践
- 例如:"通用 React UI 设计师"
模式 B:项目专用 Agent
- 绑定到特定项目,学习项目风格
- 分析项目规则 + 网络最佳实践
- 例如:"agents-hub 专属维护者"
用户确认:选择模式,模式 B 需提供项目路径
Stage 2: Agent 角色定义
询问用户:
- 主要职能是什么?
- 属于哪个领域?
- 应该做什么?不应该做什么?
- 会与谁协作?
- 目标平台?
交付物格式:参见 references/output-templates.md 的"Agent 角色定义"章节
用户确认:展示角色定义,获得明确批准后继续
Stage 3: 项目风格分析(仅模式 B)
分析内容:
- 行为风格:文档风格、注释密度、代码风格
- 决策倾向:保守 vs 激进、简洁 vs 完备、询问 vs 自主
- 关键术语:从
CONTEXT.md 提取
不提取:
- ❌ 具体技术约束(TypeScript 规范等)→ Agent 会自动加载
- ❌ 架构规则 → 同上
- ❌ 命名规范 → 同上
交付物格式:参见 references/output-templates.md 的"项目风格摘要"章节
Stage 4: 知识需求分析
分类:
A. 元规则(放入 CLAUDE.md):
- 执行前 Checklist:上下文理解、约束确认、目标明确
- 决策风格:遇到歧义时的行为、技术选型倾向、沟通方式
- 执行后自检:回归检查、可理解性、架构合理性
B. 领域知识(放入 knowledge/):
- 最佳实践文档
- 工作流程指南
- 常见模式和反模式
- 工具使用参考
领域适配:不同领域的重点不同,参见 references/domain-adaptations.md
交付物格式:参见 references/output-templates.md 的"知识需求清单"章节
Stage 5: 知识搜索与质量过滤
执行:
- 使用 Stage 4 的关键词进行网络搜索
- 评估每个来源的质量(Tier A/B/C/D)
- 提取相关信息
- 限制 2 轮 ReAct,不无限搜索
来源质量分级:
- Tier A:官方文档、行业标准、学术研究
- Tier B:高质量专业文章、专家分析
- Tier C:一般教程、社区讨论(只能作为线索)
- Tier D:营销内容、点击诱饵(排除)
详细标准和使用规则:参见 references/source-quality-guide.md
ReAct 上限:
- 第 1 轮:收集初步证据,识别信息缺口
- 第 2 轮:填补最关键缺口,然后立即进入综合阶段
交付物格式:参见 references/output-templates.md 的"证据收集报告"章节
Stage 6: 元规则提取与用户确认
提取元规则(放入 CLAUDE.md):
- 执行前 Checklist(基于搜索结果 + 项目风格)
- 决策风格
- 执行后自检
- 角色定位声明
提取领域知识(放入 knowledge/):
- 按类别分组(基础知识、最佳实践、工具指南、常见陷阱)
- 保留来源引用
- 标注可信度
冲突检测(仅模式 B):
- 如果搜索到的最佳实践与项目风格冲突
- 询问用户:遵循项目风格 or 采纳最佳实践?
用户确认:展示提取的元规则和知识库结构,获得明确批准
交付物格式:参见 references/output-templates.md 的"提取的规则清单"章节
Stage 7: 生成训练文件
生成文件:
-
系统提示词文件(work_root/CLAUDE.md 或 AGENTS.md):
# Agent 角色:[名称]
## 角色定位
[从 Stage 2,3-5 句话]
## 执行前 Checklist
[从 Stage 6]
## 决策风格
[从 Stage 6]
## 执行后自检
[从 Stage 6]
## 领域知识库
参考以下文档了解领域知识和最佳实践:
- [领域基础](./knowledge/fundamentals.md)
- [最佳实践](./knowledge/best-practices.md)
- [常见陷阱](./knowledge/pitfalls.md)
-
知识库文件(work_root/knowledge/*.md)
-
训练元数据(work_root/.training-metadata.json)
文件格式详细说明:参见 references/output-templates.md 的".training-metadata.json 格式"章节
写入位置:local_data/agents/<agent_name>/work_root/
Stage 8: 验证与迭代
展示给用户:
- 生成的文件路径
- 核心元规则摘要
- 知识库覆盖范围
- 信息缺口
询问用户:是否符合预期?需要调整?
如果需要调整:仅修改受影响的部分
如果用户批准:确认 Agent 已就绪,建议测试场景
交付物格式:参见 references/output-templates.md 的"训练总结"章节
更新流程详解
Stage U1: 现有配置分析
读取:
CLAUDE.md / AGENTS.md
knowledge/ 所有文件
.training-metadata.json
展示给用户:
- 当前训练模式(通用 vs 项目专用)
- 绑定的项目路径(如果有)
- 现有元规则类型
- 知识库文档数量
- 版本号和上次更新时间
项目变更检测(仅模式 B):
- 读取项目
CLAUDE.md 的最后修改时间
- 如果比 Agent
updated_at 新,提示用户是否重新学习项目风格
Stage U2: 更新类型选择
增量更新:添加新的元规则或知识,不改变现有内容
重构更新:重新训练某个领域,替换旧的元规则或知识
修正更新:修复错误的规则或知识
用户确认:选择更新类型
Stage U3: 更新目标确认
询问用户:
- 想要更新什么内容?
- 是否需要重新分析项目?(仅模式 B)
- 是否要改变训练模式?(A ↔ B)
确定影响范围:
- 需要重新搜索的知识类别
- 需要修改的文件和章节
- 保持不变的部分
Stage U4: 差量知识获取
策略:
- 增量更新:只搜索新增的知识类别
- 重构更新:重新搜索指定领域
- 修正更新:验证有问题的内容,找替代方案
如果需要重新分析项目(模式 B):重新执行 Stage 3,对比差异
使用相同的质量标准(Tier A/B/C/D)
Stage U5: 规则合并与冲突解决
合并策略:
- 增量更新:追加新规则到对应章节
- 重构更新:替换指定章节/文档,保留其他部分
- 修正更新:删除错误规则,替换为正确版本
冲突检测:
- 新规则 vs 旧规则冲突
- 网络最佳实践 vs 项目风格冲突(项目优先)
- 新知识 vs 旧知识矛盾
展示变更对比:变更前后的 diff、冲突项及建议解决方案
用户确认:批准合并方案
Stage U6: 增量更新文件
执行:
- 自动备份当前版本到
work_root/.training-history/v{N}-backup/
- 只更新受影响的文件和章节
- 保留原有的来源引用
- 添加新内容时标注来源和更新时间
- 更新
.training-metadata.json
Stage U7: 验证与回滚
展示给用户:更新的文件和章节、关键变更摘要、新版本号
询问用户:更新后的内容符合预期吗?
回滚机制:如果用户不满意,提供一键回滚,从 .training-history/v{N-1}-backup/ 恢复
交付物格式:参见 references/output-templates.md 的"更新总结"章节
降级处理
触发条件:无法完成训练(网络搜索不可用、用户拒绝搜索、证据停滞)
响应:
- 保留当前进度(角色定义、知识需求清单)
- 提供手动研究指南(搜索关键词、质量评估清单、模板文件、类似领域示例)
输出契约
每次成功的训练必须产出:
- Agent 角色定义
- 证据质量报告
- 生成的训练文件
- 训练总结
详细格式参见 references/output-templates.md
反模式防护
- 用 Tier C/D 来源作为元规则依据:必须过滤质量,弱来源只能提供线索
- 无限搜索:必须在 2 轮 ReAct 后停止
- 生成模糊规则:必须提取具体、可执行的元规则
- 跳过用户确认:必须在 Stage 2 和 Stage 6 后获得批准
- 混淆元规则和具体约束:必须将技术约束指向项目
CLAUDE.md
- 忽略信息缺口:必须记录缺少高质量证据的部分
- 创建没有边界的 Agent:必须明确"不做什么"
- 重复项目规则:必须检测项目已有的约束,避免冗余
质量清单
参考资料
- 输出模板:
references/output-templates.md - 各阶段交付物的详细格式
- 来源质量指南:
references/source-quality-guide.md - Tier A/B/C/D 定义和使用规则
- 领域适配:
references/domain-adaptations.md - 不同领域的元规则和知识重点
- 交互示例:
references/example-interaction.md - 完整的训练流程示例
实现注意事项
- 此 Skill 应分配给 Agents-Hub Assistant(系统助手 Agent)
- 用户通过前端"训练"按钮触发,发送消息如:
/train-agent <agent_name>
- Skill 自动检测 Agent 是否已存在(创建 vs 更新模式)
- 所有文件写入
local_data/agents/<agent_name>/work_root/,位于项目仓库外
- 训练内容跨项目有效:同一 Agent 可在多个项目中使用,行为一致
- 更新时自动备份到
.training-history/,支持回滚