AI技能系统建设实录：从SKILL.md规范到Agent工作流

说到这个，我最近被一个奇怪的警告绊住了脚——终端里蹦出一行字：

⚠ Skipped loading 10 skill(s) due to invalid SKILL.md files.

当时我就懵了：啥？十个技能文件全挂了？

仔细一看，问题五花八门：

• 九个缺了 description 字段
• 一个干脆连 YAML frontmatter 都没有

这些技能散落在各个 agent 目录下，比如 debug-investigator、data-flywheel、memory-manager……它们原本各自负责一块领域，结果因为格式不统一，全部被加载器拒之门外。

第一个坑：你以为是小问题，其实是系统性风险

你知道吗？这根本不是“写错几行”那么简单。

Skill 在 Agentic Stack 里，不是一个简单的功能列表，而是一份结构化指令文档。它告诉 AI：

• 什么时候该用我（triggers）
• 我能做什么（description / constraints）
• 具体怎么做（workflow / 步骤）
• 用什么工具（tools）

说白了，就是给 AI 准备的一本岗位操作手册。

写得好，AI 就能在正确的时间做正确的事；
写得差，要么加载失败，要么直接被忽略。

回到正题：怎么修？先看规范，再动手

修复的时候，AI 没有直接批量补上 description，而是做了三件事：

1. 查官方文档：读了 skill-creator 和 writing-skills 这两个技能，确认 frontmatter 的字段要求。
2. 翻本地记忆：运行 recall.py，看看以前有没有“描述字段该怎么写”的教训。
3. 逐个看内容：读每个报错文件前 60 行，根据已有信息推断 description 应该写啥。

这个顺序特别重要：

“写测试之前先理解生产约定，改代码之前先看失败基线。”

这才是真·工程思维。

最小可用模板：别整复杂，先把基础打牢

修完之后，一个合格的 SKILL.md 至少得长这样：

---
name: debug-investigator
description: Investigate and diagnose bugs by analyzing stack traces, logs, and code paths.
triggers: ["debug", "why is this failing", "investigate", "stack trace", "bug"]
tools: [bash, memory_reflect]
constraints: ["reproduce before fixing", "fix root cause, not symptoms"]
---

关键字段：

• name：内部标识，不能重复
• description：一句话说明触发条件和用途（加载器必填！）
• triggers：激活关键词，多个用数组
• tools / constraints：可选但建议写，能帮 AI 控制行为边界

用 TDD 的思路写 Skill：不是写文档，是写测试

修复过程中我还学到一个新招——写 Skill 就像写测试驱动的文档。

核心原则就一句：

如果你没看过 agent 在没有 skill 时的失败表现，你就没法确定这个 skill 教对了没有。

自动化记忆纪律：经验不能靠运气

除了修技能文件，我们还顺带理清了一套记忆管理流程：

• 每次任务前跑 recall.py，查历史教训
• 每次任务后跑 memory_reflect.py，记录动作和结果
• 候选教训自动聚类，人工审核（graduate.py / reject.py）
• 工作区状态实时更新到 WORKSPACE.md

这套机制让“经验”不再是单次对话的碎片，而是变成可复用的知识资产。

一点反思：别只盯着格式，要看体系

10 个技能同时报错，表面看是格式问题，实则是知识管理没标准化。

当技能超过 20 个、分布在多个目录下时，没有统一的 frontmatter 规范，必然出现“有的能加载、有的不能”的混乱状态。

修复过程其实不长，但方法论值得记下来：

1. 先查规范，不盲改
2. 按内容推断描述，不硬编
3. 改完验证，确保加载器不再报错
4. 把教训写进长期记忆，下次提前预防

这才是真正的“AI 技能系统建设”。