team-skill-evolve

name	team-skill-evolve
description	根据真实反馈、失败案例和执行日志复盘团队技能库，并提出可审核的技能进化建议。Review real feedback, failures, and execution logs to propose auditable improvements to the team skill library.
license	MIT
metadata	{"author":"coolbeevip","version":"1.0"}
triggers	["技能复盘","改进技能","技能自进化","根据反馈优化 skill","复盘 agent 失败","优化触发词","技能过度设计","技能写太多代码","没有复用现有代码","skill evolution","improve this skill","review skill feedback","refine agent workflow","analyze agent failure","update skill triggers","skill over-engineered","agent wrote too much code","missed existing reuse"]

技能自进化

这个技能用于维护团队技能库自身。它把真实使用中的失败、反复纠正、误触发、输出不稳定和脚本缺口，转化为可审核、可验证、可回滚的技能改进建议。默认只做复盘和建议；只有用户明确要求“实现”“修改”“合入”“更新文件”时，才修改技能文件或辅助脚本。

当用户反馈“技能过度设计”“写太多代码”“没有复用现有代码”“agent wrote too much code”“missed existing reuse”等问题时，本技能应把它归入最小实现模式的技能反馈：检查相关技能是否缺少触发词、复用优先规则、平台能力优先规则、安全边界或验证清单。

自进化不是让 agent 自己随意改写技能，而是建立受控闭环：

1. 从真实反馈中识别问题。
2. 判断问题属于触发、输入、输出、流程、脚本、验证还是文档边界。
3. 提出最小改动建议和验证方式。
4. 经用户确认后再修改。
5. 修改后执行结构校验和必要的轻量验证。

触发边界

• 适合触发：用户反馈技能误触发、输出不稳定、过度设计、没有复用现有实现、脚本缺口或要求根据使用反馈更新技能。
• 不适合触发：用户要维护某个业务项目中的 Codex 运行时检索层时，转交 team-codex-harness；用户只是执行普通产品、交付或技术债流程时，使用对应业务技能。

输入物

• 当前对话中的用户反馈、纠正、阻塞描述或失败复盘。
• 用户提供的 issue、PR 评论、运行日志、人工修正记录或技能执行产物。
• 相关技能目录中的 SKILL.md。
• 相关技能明确引用的辅助文件，例如 CONTEXT-FORMAT.md、模板或 scripts/ 下脚本。
• 最小实现相关改动应读取 ./references/GOLDEN-SCENARIOS.md 和 ./references/BENCHMARK-TEMPLATE.md，用于人工回归和 benchmark 记录。
• 根目录 AGENTS.md、仓库规范和当前技能目录结构。
• 可选：python3 scripts/check_skills.py 的结构校验结果。

如果用户没有指定要复盘哪个技能，应先根据反馈内容、触发词和产物路径判断候选技能。无法唯一判断时，只问一个最关键的问题：要复盘哪个技能或哪次失败。

输出物

默认输出对话中的《技能进化建议报告》，不落盘、不改文件。报告必须包含：

• 反馈来源：用户请求、失败日志、评论或文件路径。
• 影响技能：一个或多个 team-* 技能名。
• 问题分类：触发、输入物、输出物、工作流、脚本、校验、边界或文案。
• 证据：来自对话、文件、日志或用户纠正的具体事实。
• 建议改动：按最小可行改动描述，不做无关重写。
• 风险与取舍：说明可能影响哪些技能或工作流。
• 验证方式：结构校验、脚本 --help、语法检查、黄金用例或人工检查。
• 是否建议立即修改：yes / no，并说明原因。

用户明确要求实现时，输出物可以包括：

• 更新后的 skills/**/SKILL.md。
• 更新后的技能局部辅助文件。
• 新增或更新的技能局部 scripts/。
• 根目录维护脚本，例如 scripts/check_skills.py。

不要把一次性反馈、真实业务需求、PRD、风险报告或工程 issue 写入本仓库。需要沉淀反馈时，优先建议使用外部 issue、Notion 或用户指定的业务项目工作区。

触发判断

出现以下信号时，可以建议用户进入本技能，但不要自动修改文件：

• 用户说“不是这个意思”“刚才触发错了”“这个 skill 没做好”。
• 同一个技能被用户连续纠正，或输出被要求大改。
• Agent 找不到唯一 slug、误读 archive、写错产物路径或混淆上下游边界。
• 用户指出技能结果过度设计、写太多代码、引入不必要依赖、没有复用现有代码或忽略平台原生能力。
• 技能流程依赖临时生成复杂代码，且该逻辑可能重复使用。
• 脚本执行失败后暴露出缺少参数、dry-run、安全边界或错误提示。
• 同类失败在不同任务中重复出现。

用户直接提出“复盘技能”“改进 skill”“技能自进化”“根据反馈优化流程”等诉求时，直接执行本技能。

最小实现反馈处理

当反馈指向“太复杂、过度设计、写太多、没有复用现有代码”时，复盘时按以下顺序判断：

1. 相关技能是否缺少“最小改动、不要过度设计、简单实现、优先复用现有代码、少写代码”这类触发词。
2. 工作流是否要求先查现有 helper、组件、模式、脚本或服务。
3. 工作流是否要求先考虑标准库、平台能力和已安装依赖，再考虑新增依赖或新抽象。
4. 输出格式是否要求说明复用了什么、跳过了什么复杂方案、什么时候再升级。
5. 安全边界是否写清楚，避免把输入校验、权限、数据一致性、错误处理或用户明确要求误判为可裁剪复杂度。

建议改动仍必须保持最小：优先补触发词、单条工作流、检查清单或完成标准，不重写整个技能。

工作流

1. 识别目标：确认本轮是复盘建议、实现已批准建议，还是验证已完成改动。
2. 收集证据：读取用户反馈、失败日志、相关 SKILL.md、被引用辅助文件和仓库规范。
3. 定位问题：判断是触发不准、输入不清、输出不稳、流程缺步骤、脚本缺口、校验不足、边界不清或文案问题。
4. 判断是否值得改技能：只有当问题可复现、影响明显、或能减少后续反复确认时，才建议修改。
5. 设计最小改动：优先补充触发词、边界规则、输入/输出说明、工作流步骤或验证要求；不要重写整个技能。
6. 如果涉及确定性、批量、API、路径解析、幂等或格式转换，优先建议新增或修改技能局部 scripts/。
7. 默认输出《技能进化建议报告》，等待用户确认。
8. 用户明确要求实现后，再修改文件，并保持改动集中在相关技能和必要的维护脚本。
9. 修改后执行轻量验证：
   • python3 scripts/check_skills.py（如果脚本存在）。
   • 修改 Python 脚本时执行语法检查或 --help。
   • 对受影响技能跑 2 到 3 个黄金用例的人工触发检查。
   • 如果改动影响最小实现模式，至少从 ./references/GOLDEN-SCENARIOS.md 选 3 个场景，并用 ./references/BENCHMARK-TEMPLATE.md 的口径记录 LOC、新增文件、新增依赖、验收和安全边界。
10. 最终回复说明修改了哪些技能、验证结果、剩余风险和建议的下一步。

改动边界

• 默认不改文件；必须有用户明确授权才实现改动。
• 不把一次失败直接泛化成强规则，除非证据足够或规则本身低风险。
• 不把某个业务项目的临时约束写成所有项目通用规则。
• 不删除用户已有改动；遇到无关工作区变更时保持原样。
• 不新增 README.md、变更日志或无关文档文件。
• 不把根目录公共脚本写成技能运行时依赖，除非它是本仓库维护检查工具。
• 如果修改公共 _team_common.py，必须按仓库规范同步 vendored 副本并执行对应检查。

问题分类标准

• 触发问题：技能未触发、误触发、触发词缺少常见说法，或 description 无法覆盖真实场景。
• 输入物问题：没有说明必须读取什么、如何确定唯一 slug、缺少文件时应问什么。
• 输出物问题：产物路径、格式、状态值、下游消费边界或最终回复要求不稳定。
• 工作流问题：步骤顺序不对、缺少 ready gate、过早写文件、没有用户确认点。
• 脚本问题：重复出现临时代码、API 调用易错、批量处理需要幂等或 dry-run。
• 校验问题：修改后没有结构校验、脚本检查、黄金用例或人工核对路径。
• 边界问题：读取了不该读的 archive、误改上游产物、把建议当成已确认事实。
• 最小实现问题：缺少复用优先、平台能力优先、少依赖、少抽象或过度设计检查，或错误地把必要安全边界当成可裁剪范围。
• 文案问题：说明过长、抽象、不可执行，或用户可见语言不符合项目约定。

建议报告格式

## 结论

是否建议修改：yes/no
影响技能：team-xxx
优先级：P0/P1/P2

## 证据

- ...

## 问题分类

- ...

## 建议改动

- ...

## 风险与取舍

- ...

## 验证方式

- ...

## 待用户确认

1. 是否按上述最小改动实现？

优先级定义：

• P0：技能存在会导致错误产物、误改文件、错误发布或安全风险的问题，应尽快修。
• P1：高频返工、误触发、输入输出边界不清，会明显影响团队效率。
• P2：可读性、触发覆盖或验证便利性改进，不阻塞当前使用。

实现规则

用户确认实现后：

• 修改前先检查工作区状态，避免覆盖无关改动。
• 只读取和修改与建议直接相关的技能目录、脚本或维护校验脚本。
• SKILL.md frontmatter 必须保持：
  • name 等于目录名。
  • description 同时包含中文和英文。
  • license: MIT。
  • metadata.author: coolbeevip。
  • metadata.version: "1.0"。
  • triggers 至少 3 条中文、3 条英文。
• 新增技能必须包含 ## 输入物 和 ## 输出物。
• 技能内引用辅助文件必须使用相对 SKILL.md 的路径，例如 ./scripts/example.py。
• 修改脚本后至少执行语法检查或 --help。
• 完成后运行 python3 scripts/check_skills.py；如果该脚本不存在，按仓库规范手动检查 frontmatter、触发词、输入物、输出物和引用路径。

黄金用例

每次修改技能后，至少人工检查 2 到 3 个用例：

• 正向触发：用户用常见说法提出该技能场景时，是否会触发正确技能。
• 边界触发：用户只是在讨论或咨询时，技能是否避免过早改文件。
• 输入不足：缺少 slug、路径或反馈证据时，是否只问一个关键问题。
• 输出路径：产物是否写到规范路径，是否避免修改 archive 或旧需求。
• 下游衔接：输出是否能被下游技能读取，不制造新的隐含假设。

完成标准

• 复盘模式下，问题、证据、影响技能、最小改动、风险和验证方式已经明确，并等待用户授权。
• 实现模式下，只修改了用户批准的相关技能、辅助文件或维护脚本。
• 所有修改均通过适用的结构检查、脚本检查和黄金用例检查。
• 没有把单次业务约束泛化为团队通用规则，也没有覆盖无关工作区变更。
• 最终结论明确说明是否完成、仍有什么风险以及下一步是否需要用户确认。

最终回复

如果本轮只做复盘，最终回复应包含：

• 是否建议修改。
• 建议修改的技能和优先级。
• 最小改动摘要。
• 等待用户确认的下一步。

如果本轮已实现修改，最终回复应包含：

• 修改文件列表。
• 关键行为变化。
• 已执行的验证命令和结果。
• 未覆盖的风险或需要人工确认的点。