使用 AI Coding 工具开发项目时,经常会遇到一种情况:某个错误花了很长时间才解决,相关经验整理到笔记之后,过了一段时间又在另一个项目中遇到类似问题。虽然 AI 能够帮助我们快速修复 Bug,但很多有价值的排查方法并没有真正沉淀下来。

作者的开源项目 Human Edge Agent Skills 中的 skill-from-scars,就是为解决这一问题设计的。它能够帮助开发者分析历史调试记录、失败日志和项目复盘,从中识别反复出现的问题,并将有价值的处理经验整理成具备明确触发条件、执行规则和测试用例的 Agent Skill。

项目地址(100+ star): GitHub - FAIRY123456789/human-edge-agent-skills: 18 portable Agent Skills for voice-native AI, human judgment, microbets, social tact, writing, life systems, and safe deployment. · GitHub

Skill 地址: https://github.com/FAIRY123456789/human-edge-agent-skills/tree/main/skills/skill-from-scars

一、什么样的经验值得做成 Skill

Agent Skill 通常通过 SKILL.md 描述特定任务的处理规则,使兼容的 Agent 在遇到对应问题时能够参考这些规则执行工作。一个有价值的 Skill,需要明确它解决什么问题、什么时候触发、具体应该执行哪些步骤,以及怎样判断结果是否正确。

例如,某次开发中遇到数据库连接失败,记录一篇故障笔记就可能已经足够。但如果多个项目反复出现环境检查遗漏、配置冲突和错误修复顺序的问题,就值得考虑将这些经验整理为一套可重复执行的检查规则。

skill-from-scars 的核心工作,就是从历史问题中找出真正具有复用价值的部分。它会分析失败记录,合并原因相近的问题,并筛选适合编写成 Skill 的候选经验。


二、通过七个维度筛选 Skill 候选

仓库提供了 references/skill-worthiness.md,其中定义了一套简单的 Skill 价值评价规则。

它从七个方面评分:问题是否反复发生、是否具有普遍性、通用模型是否容易处理失败、能否总结明确的决策步骤、效果是否可以测试、是否能够脱离私有环境复用,以及是否包含真正独特的处理经验。

每个维度取 0—2 分,总分为 14 分。仓库建议优先考虑达到 11 分的候选问题。这个阈值属于项目内部的筛选规则,可以帮助开发者减少低价值 Skill 的开发投入。

例如,“把代码写得更优雅”这样的要求比较宽泛,很难设计统一的测试标准。而“多轮对话切换任务时检查旧参数是否仍然有效”,则具有明确的输入、处理规则和预期结果,更容易形成可验证的 Skill。


三、从历史错误中提取执行规则

假设一个 Agent 在多轮对话中经常错误继承上一轮任务的参数。用户已经切换到新的订单查询任务,Agent 却继续使用旧订单 ID,最终返回错误结果。

开发者可以先收集发生过的失败记录,分析问题是否具有共同原因。如果多次错误都与任务对象变化有关,就可以考虑设计一套上下文切换检查规则。

例如,可以形成以下处理步骤:

1. 识别当前任务和目标对象
2. 检查用户是否明确切换主题
3. 判断历史参数是否仍然适用
4. 缺少必要参数时主动追问
5. 验证最终工具调用使用的对象

这些步骤构成了候选 Skill 的主要执行规则。之后还需要明确触发条件,例如用户在连续对话中改变任务目标,或者需要判断是否可以继续使用历史参数。

skill-from-scars 会引导开发者把这些规则与原始失败记录对应起来,避免生成一份缺少实际验证依据的通用建议。


四、使用 Python 生成 Skill 基础目录

仓库提供了 scripts/scaffold_skill.py,可以根据 JSON 设计文件生成基础 Skill 目录。该脚本使用 Python 标准库,无需额外安装第三方依赖。

例如,创建一个 design.json:

{
  "name": "topic-switch-check",
  "description": "Check task changes before reusing conversation parameters.",
  "workflow": [
    "Identify the current task and target.",
    "Detect explicit topic changes.",
    "Check whether prior parameters still apply.",
    "Ask for missing parameters when needed."
  ],
  "eval": {
    "input": "旧订单不用管了,帮我查询新的订单",
    "expected": "不直接继承旧订单ID"
  }
}

在仓库根目录执行:

python skills/skill-from-scars/scripts/scaffold_skill.py design.json output

脚本会创建 output/topic-switch-check/,其中包含 SKILL.md、references/ 目录和 evals/seed.json。开发者可以继续补充详细规则、实际测试数据和参考资料。

需要注意,这个脚本负责生成初始文件结构。Skill 的实际运行效果还需要进一步测试。


五、怎样证明这个 Skill 确实有用

skill-from-scars 特别强调 Baseline 与 Skill 的对比评测。

Baseline 是没有使用新 Skill 时的基础表现。开发者可以准备几条固定测试任务,在相同模型、工具和测试条件下,分别运行普通 Agent 与加载新 Skill 的 Agent,观察两者的行为差异。

以前面的多轮状态问题为例,可以设计三个测试场景:用户明确切换任务、用户继续补充原任务参数、用户表达不完整且需要追问。测试时记录 Agent 是否正确识别任务对象、是否错误继承旧参数,以及工具调用结果是否符合预期。

如果新 Skill 在这些 Case 中表现更加稳定,并且没有明显影响其他正常任务,就获得了初步的有效性证据。后续还可以补充真实用户测试和更多边界任务。

仓库的设计原则是让每个 Skill 都能够说明自己的实际价值。因此,对于尚未经过验证的 Skill,应保留测试状态,继续积累数据。


六、安装与开源地址

skill-from-scars 已在 GitHub 仓库公开,包含完整的 Skill 说明、候选评分规则和 Python 目录生成工具。

项目地址: GitHub - FAIRY123456789/human-edge-agent-skills: 18 portable Agent Skills for voice-native AI, human judgment, microbets, social tact, writing, life systems, and safe deployment. · GitHub

Skill 地址: https://github.com/FAIRY123456789/human-edge-agent-skills/tree/main/skills/skill-from-scars

在支持 gh skill 的环境中,可以预览和安装:

gh skill preview FAIRY123456789/human-edge-agent-skills skill-from-scars
gh skill install FAIRY123456789/human-edge-agent-skills skill-from-scars

安装后,可以尝试提供一份经过脱敏的历史调试记录,并输入:

请使用 skill-from-scars 分析这些失败记录,识别反复出现的共性问题,评估哪些经验适合整理为 Agent Skill,并为最有价值的候选生成 SKILL.md 设计方案和基础评测用例。

在实际使用时,需要先去除日志中的密钥、内部地址、用户数据以及公司保密信息。涉及私有环境的处理经验也应在公开之前完成适当抽象和脱敏。

对于经常进行 AI Coding、Agent 开发和项目维护的开发者,这个 Skill 提供了一种整理技术经验的方式:从反复发生的真实错误中识别共性问题,再形成可以执行、测试和持续改进的规则。

如果你也积累了大量 Debug 日志、失败案例和项目复盘,可以尝试使用它筛选自己的第一个 Skill。欢迎访问仓库阅读源码、提交 Issue,或者通过 Star 支持后续改进。

Logo

更多推荐