别急着翻译 SKILL.md：我做了一个专门拆解 Skill 设计的工具
第一次打开一份复杂的 SKILL.md，很多人的反应都是从头往下读。
每句话似乎都认识，连在一起却不一定明白：为什么这里用了 MUST？为什么执行前要读取这些文件？状态由谁维护？AI 做到什么程度才算完成？如果两条指令发生冲突，到底应该听谁的？
真正难懂的往往不是英文，而是藏在文字背后的工作流。
这也是我写 skill-analyzer 的原因。
它不是翻译器
skill-analyzer 的目标很明确：不只告诉你一份 Skill 写了什么，还要解释它为什么这样写。
比如下面这条规则：
text
Read all contextFiles before implementation.直译很简单：
实现前读取所有上下文文件。
但只翻译到这里，实际上没有解决多少问题。
更值得追问的是：这条规则在防什么？
它防的是 AI 只看当前任务就开始写代码，遗漏需求、设计文档或者项目约束。它还隐含了一层权责划分：外部系统负责决定"应该读取哪些文件"，AI 负责完整读取并理解。换句话说，Context Discovery 和 Context Consumption 被分开了。
这才是规则真正的设计价值。
skill-analyzer 做的，就是把这些藏在字面下面的东西挖出来。
一份 Skill，至少要看懂五件事
分析一份 Skill 时，我最关心的不是它有多少章节，而是下面几个问题。
第一，它到底要解决什么问题。
有些 Skill 负责生成代码，有些负责审查，有些负责操作外部工具，还有些负责控制一套完整工作流。名字和简介只能告诉我们大致方向，真正的能力边界要从触发条件、输入、步骤和输出里判断。
第二，AI 收到它以后会怎么行动。
很多 Skill 表面上是一篇说明文，实际上描述的是一张流程图。里面可能有固定步骤、条件分支、循环、暂停点和人工确认节点。只有把这些内容重新排列成执行顺序，才能看出 AI 在每一步需要什么输入、产生什么输出，以及什么时候可以进入下一步。
第三，谁说了算。
一份 Skill 里可能同时存在用户要求、项目文件、CLI 状态、API 返回值、Artifact、内置规则和操作建议。这些信息不是同一个等级。
用户可以提出需求，但未必能绕过系统状态；Guidance 可以帮助执行，但不能覆盖 MUST；AI 可以读取任务状态，却不一定有权自行修改状态。如果 Skill 没有说明冲突时的优先级，执行结果就很容易随着模型的理解发生漂移。
第四，什么叫完成。
这里需要区分两个经常被混在一起的概念。
Completion Definition 回答的是"做到什么程度算完成"，例如指定功能已经实现。
Completion Evidence 回答的是"凭什么证明它完成了"，例如构建通过、测试通过、场景验证通过。
只有完成定义，没有完成证据，最后仍然可能退化成"AI 觉得差不多了"。对于需要稳定执行的 Skill，这通常是一个明显缺口。
第五，有哪些设计值得复用。
分析 Skill 的意义不应停留在评价别人写得好不好。更实际的收获，是把其中有效的做法提炼出来：先获取真实状态再行动、把上下文范围交给外部系统决定、明确暂停条件、保护任务范围、用客观结果证明完成。
这些方法换一个业务场景仍然成立。
它具体会分析什么
skill-analyzer 会先完整读取目标 Skill，而不是看到主要流程后就停止。文件末尾的 Guardrails、Notes、Constraints 和完成条件，往往比开头的功能介绍更能决定 AI 最终会做什么。
如果目标 Skill 引用了必要的规则文件或上下文文件，也需要继续追踪这些依赖。否则分析出来的只是一个孤立的 SKILL.md，不是它真实运行时受到的完整约束。
完成读取后，它会重新还原执行流程，并从行为约束、上下文管理、状态管理、事实源、指令优先级、任务范围、异常处理和完成证据等角度拆解设计。
最后还会反过来追问：
- 作者在防止 AI 出现什么问题？
- 哪些规则删除后会明显改变行为？
- 哪些内容只是帮助理解的辅助说明？
- 当前设计有没有冲突、遗漏或过度约束？
- 如果自己写 Skill，哪些结构可以直接借鉴？
我希望它给出的不是一份"内容摘要"，而是一张 Skill 的设计剖面图。
哪些时候适合使用
当你下载了一份陌生的 Skill，想判断它是否值得安装时，可以先用它分析整体行为和权限边界。
当你正在学习别人如何设计 Agent 工作流时，可以让它重点还原执行流程，看看规则如何控制 AI 的行动顺序。
当你已经写好自己的 Skill，却发现执行结果不稳定时，可以重点检查指令优先级、状态事实源、暂停条件和完成证据。
它也适合比较同一份 Skill 的两个版本。很多改动看起来只是增加了几条规则，实际影响的可能是 AI 的权限、任务范围或者完成判断方式。
例如可以直接这样使用：
text
使用 skill-analyzer 分析这个 SKILL.md。也可以缩小范围：
text
分析这个 Skill，重点检查指令优先级和完成标准。或者比较版本：
text
比较这个 Skill 的 v1 和 v2，说明工作流和行为边界发生了哪些变化。它不替你做决定
skill-analyzer 不是一个自动打分器，也不会因为规则写得多，就判断一份 Skill 更专业。
长并不等于严谨。重复规则可能是在强化关键约束，也可能只是缺少整理；人工确认节点可以降低风险，太多了也会让工作流变得支离破碎；严格限制 AI 的权限有助于保持稳定，但同样可能损失执行效率。
因此，它会把"原 Skill 的设计"和"对这份设计的评价"分开。
前者回答作者写了什么，后者讨论这些做法是否合理。这样既不会把分析者的偏好冒充成原文规定，也方便使用者根据自己的场景作出判断。
我更关心的是"为什么"
做 skill-analyzer 时，我给它定下的最终标准不是"能把 Skill 讲明白"，而是完成三层转换：
text
看懂它写了什么
↓
理解它为什么这样写
↓
知道自己的 Skill 应该怎么写Skill 的价值从来不只在几段提示词里。它真正决定的是 AI 在什么情况下行动、依据什么行动、遇到问题时是否暂停，以及拿什么证明任务已经完成。
当这些问题能够被说清楚，一份 Skill 才不再是堆叠起来的指令，而是一套可以检查、讨论和持续改进的工作方法。
项目地址：skill-analyzer