如何撰写skill：Skill 的本质

Skill 的本质把 skill 当提示词写是最常见的误解。结果往往是一篇写满背景和口号的文档读起来很对却没有一条能真正改变 Agent 行为的约束。问题出在两者回答的不是同一个问题。提示词回答“这次让模型说什么”是一次性的输入skill 回答“这类任务到了某个阶段必须按什么协议推进”是可复用、可触发、可复盘的流程约束。所以 skill 的本质不是提示词而是把一段隐性工作流显式化成可执行的阶段契约。它要拦住的是行为不是补知识人类开发不是一路写代码。需求含糊时会停下来问方案太大时会停下来拆测试没覆盖时会补报错出现时会找根因准备交付时会验证。这些停顿很少写进流程而是藏在经验和习惯里。Agent 缺的正是这种停顿。它拿到任务后会顺着上下文继续生成需求没澄清就改文件测试没变红就写实现根因没定位就打补丁验证没跑完就宣布完成。它不是不够聪明而是没有在该停的地方停下。skill 要解决的就是这种行为失控——把工程师在关键节点的停顿外化成可触发、可检查的规则。这就决定了一个 skill 该从哪里来。它的来源不该是“我希望 Agent 更聪明”而该是“我已经看到 Agent 在这里稳定犯错”。一个找不到对应失败的 skill多半只是一个包装过的愿望。一份 skill 是一组判断的落地既然要拦住的是具体的失败skill 写下的就不是说明而是判断。每个判断都对应一个可写的字段而每个字段背后都是一种对这段流程的理解。所以写 skill 不是把经验翻译成提示词而是同时完成三件事。第一是理解流程知道这类任务真正经历哪些阶段哪些顺序不能倒哪些输入缺了会让后续产物失真。第二是洞察 Agent知道它在压力下会跳过什么例如省掉澄清、提前实现、用解释替代验证、用局部成功掩盖整体未闭环。第三是完成表达转化把这些隐性判断转成When to Use、Hard Gate、Red Flags、Steps、Done When这类可触发、可检查、可交接的结构。一份好的 skill 至少要回答下面这些问题触发条件什么时候必须进入。不触发条件什么时候不要进入避免抢别的阶段的职责。输入契约要读哪些上下文、证据和上游 artifact并区分必需输入和可选输入。前置门禁必需输入里哪些缺了就不能开始已经越过则必须回退。执行协议进入后按什么顺序做每一步为什么存在哪些阶段不能倒置。防跳跃规则禁止哪些捷径、借口和合理化写清 Agent 在压力下最容易省掉的那一步。输出契约产出什么文件、决策、报告或结构化字段且要能被人、工具和下游 Agent 稳定读取。完成确认用什么证据判断已经完成不把“已经解释过”当成“产物可用”。失败/回退路径做不到时停在哪里、问谁、回到哪个上游 artifact而不是继续编。交接边界完成后交给哪个 skill 或阶段不负责继续做什么。这十项不是格式模板而是十种判断的外化前后顺序、职责边界、上下游接口、停止线、完成标准。还有一项不在字段里却同样是判断——哪些步骤必须重哪些可以轻。把所有任务都拖进同一套重流程和该停时不停一样都是没把成本想清楚。输入契约和前置门禁不是一回事这两项最容易被合并但应该拆开。输入契约回答“吃什么”本 skill 正常工作需要读取哪些上下文、证据和上游 artifact。前置门禁回答“缺什么必须停”这些输入里哪些是阻塞条件缺了就不能继续。前置门禁是输入契约里的强约束子集。历史代码、参考文档缺了往往还能继续只是要标记风险但方案设计前缺了状态为approve的需求评审决策就必须停。混在一起写容易写成一串文件清单反而看不出哪里必须停——前者偏信息结构后者偏行为控制。谁来承载这些判断这些字段不一定都写在 skill 文本里。不同系统都绕不开它们但会放在不同的层来承载。Superpowers 最纯粹几乎把全部判断写进 skill 文本description是触发条件Protocol是执行协议Hard Gate是门禁Red Flags和压力测试是防跳跃Verification和 transcript 是完成证据。它的重心是行为纪律——让 Agent 在正确时刻停下来。OpenSpec 把这些事下沉到 change artifact 和 CLI触发条件在 workflow skill 里输入是openspec/changes/name/下的 proposal、spec delta、design、tasks门禁是 artifact DAGtasks依赖specs design防跳跃靠 CLI 的status和detectCompleted输出是仓库里可归档的长期事实。它的重心不是行为纪律而是变更事实可继续。Claude Code 更底层它不是某个 skill而是 skill 能成立的运行时插槽触发来自 frontmatter 和 slash command门禁来自allowed-tools、user-invocable、context: fork这类运行时元数据输出可以是会话结果、文件修改或子代理产物。它的重心是装载、权限、执行和上下文拼装。三者的差别不在于有没有这些事而在于谁来承载。所有 skill 和 workflow 都必须回答这些判断超出的部分——装载、状态、权限、调度、隔离、恢复、遥测——属于 runtime、artifact store 或工程平台不再是 skill 本身。一句话Skill 是一个阶段协议规定何时进入、凭什么进入、不能跳过什么、产出什么、如何确认完成以及失败时回到哪里。它把一段流程里的隐性判断显式化而不是把经验写成步骤。