skill-from-scars：从反复踩过的坑，到可复用的 Agent Skill

使用 AI Coding 工具开发项目时经常会遇到一种情况某个错误花了很长时间才解决相关经验整理到笔记之后过了一段时间又在另一个项目中遇到类似问题。虽然 AI 能够帮助我们快速修复 Bug但很多有价值的排查方法并没有真正沉淀下来。作者的开源项目Human Edge Agent Skills中的skill-from-scars就是为解决这一问题设计的。它能够帮助开发者分析历史调试记录、失败日志和项目复盘从中识别反复出现的问题并将有价值的处理经验整理成具备明确触发条件、执行规则和测试用例的 Agent Skill。项目地址100 starGitHub - FAIRY123456789/human-edge-agent-skills: 18 portable Agent Skills for voice-native AI, human judgment, microbets, social tact, writing, life systems, and safe deployment. · GitHubSkill 地址https://github.com/FAIRY123456789/human-edge-agent-skills/tree/main/skills/skill-from-scars一、什么样的经验值得做成 SkillAgent 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. · GitHubSkill 地址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 支持后续改进。