什么是 Skill？

一个 Skill 是一份清晰、严谨、可执行的指令文档，用于明确告诉模型——在什么条件下（When），按照哪些步骤（How），产出什么结果（What）。

常见认知误区

在编写 Skill 之前，建议先了解以下几个常见误区。这些问题往往会直接导致 Skill 难以被正确触发，或在执行过程中表现不稳定。

• 误区一：Skill 等同于一段 Prompt

Skill 并不是一次性的对话提示。它是一个可长期复用、输入输出明确的能力模块，强调的是稳定、确定且易于工程化维护。而 Prompt 更偏向临时性、探索性和即兴交互，两者在设计目标和工程要求上完全不同。

• 误区二：Skill 是写给人看的文档

Skill 的目标不是解释原理，而是下达指令。SKILL.md 文件的内容应使用模型可解析的结构化语言，明确约束其行为边界，并精确描述何时使用（When）、如何执行（How）、输出结果（What）。

• 误区三：Skill 越复杂越强大

复杂度并不与 Skill 的能力强度挂钩。模型的推理与决策成本是显著的。职责单一、边界清晰的 Skill，更容易在正确的时机被选中并稳定执行。过于复杂的 Skill 反而会降低命中率。
模型的上下文窗口是有限且宝贵的公共资源。每一个被加载的 Skill 都在竞争有限的上下文资源。因此，Skill 文档应以最小必要信息为目标，避免冗余解释与不必要的背景铺垫。

Skill 的设计标准与原则

以下标准是构建高命中率、高稳定性 Skill 的基础。可将其作为设计与评审 Skill 时的检查清单。

精准的元数据内容

Skill 的元数据（name 和 description）是模型发现和识别 Skill 的入口，其设计直接影响触发准确率。

指导方式的自由度分级

根据任务复杂度与容错要求，合理控制对模型的约束强度。

自由度等级	适用场景	指导方式	示例
高	存在多种有效方法模型的决策依赖上下文	提供启发式策略（给原则）	---name: code-reviewdescription: 当用户需要对代码进行审核时，基于代码实现与通用开发规范，分析逻辑正确性、可维护性和潜在风险，并给出改进建议。
中	存在首选模式允许一定程度的变通行为受配置参数影响	提供模板/伪代码（给框架）	---name: report-generatordescription: 当用户需要生成报告时，按照“摘要-分析-建议”的结构整理信息，输出清晰、条理化的报告内容template:
低	操作脆弱且易错。一致性至关重要。必须遵循特定序列。	提供可执行的脚本（给代码）	---name: database-migrationdescription: 当用户需要执行数据库迁移时，按预定义顺序执行 SQL 或迁移脚本，确保数据和结构一致性template:

五个核心标准

1、边界明确
模型最容易犯的错误不是“不知道怎么做”，而是“不知道什么时候该做”。Skill 的触发必须有明确的正向条件和负向条件，否则命中率会很低。

2、输入输出结构化
与模型沟通时，需要定义双方都能理解的“共同语言”，避免模糊描述。推荐用类似函数签名的方式明确 Input 和 Output，保证可解析性。

3、步骤明确、可执行
Skill 的核心是“步骤”，必须是指令式、具体动作，而不是概括性描述，确保模型可以按步骤执行。

4、失败策略完备
模型在失败时容易自由发挥，可能产生不可预期的行为。必须明确定义“失败路径”，告诉模型在不同失败情况下如何处理。

5、功能绝对单一
每个 Skill 只做一件事，对应一个核心动作动词。避免把多个功能捆绑在一个 Skill 中，否则复杂性和不确定性会增加，模型难以准确理解。

让 Skill 可维护与可拓展

为了确保 Skill 在长期运行中保持稳定、易用且可持续拓展，需要从信息结构、工作流设计和脚本可靠性三个维度进行规划。

1. 渐进式披露

SKILL.md 应当作为 Skill 的入口和导航，而不是一个包罗万象的大文件。详细的参考资料、示例、脚本或文档应拆分成独立文件，从而减轻模型初次加载的负担，让信息按需流动。

信息架构原则

从简单到复杂。一个 Skill 的目录可以随着功能扩展逐步演化：从单一文件演化为由多个参考文件和脚本组成的结构。

最佳实践

• 保持 SKILL.md 简洁：主体内容尽量控制在 500 行以内
• 避免深度嵌套：所有引用文件最好直接由 SKILL.md 链接，保持一层引用深度
• 为长文件添加目录：对于超过 100 行的参考文件，在文件顶部添加目录

示例结构

text

SKILL.md├── 基础用法│ ├── 检查 PR 状态│ ├── 执行单元测试│ └── 更新 PR 测试状态├── 高级功能 → ci-advanced-features.md└── API 参考 → ci-api-reference.md

2. 工作流与反馈闭环

对于包含多个步骤、且中间结果会影响最终质量的复杂任务，必须显式定义工作流和检查清单，引导模型按步骤执行，并在关键节点建立“验证 → 修正 → 再验证”的反馈闭环。

分析类任务工作流示例（技术方案评估）

步骤	内容	反馈闭环
Step 1	明确业务目标与技术约束（性能、成本、时限）	–
Step 2	列出所有可行的技术方案	–
Step 3	从复杂度、可维护性、风险角度逐一评估	–
Step 4	对关键差异点进行对比分析	若发现关键信息不足，返回 Step 2 或 Step 3
Step 5	给出结论性建议，并说明取舍理由	若结论无法支撑目标约束，重新审视 Step 1

代码类任务工作流示例（依赖版本升级）

阶段	步骤	反馈闭环
Plan	1. 识别需要升级的依赖及当前版本2. 阅读 Release Notes 与 Breaking Changes3. 更新依赖配置文件4. 标注可能受影响的模块	–
Validate	5. 执行依赖冲突检查与静态构建6. 确认无版本冲突或构建失败	若校验失败，回退到步骤 3
Execute	7. 安装新版本依赖8. 运行完整测试集	–
Validate	9. 检查核心功能是否受影响10. 对比升级前后的构建与运行结果	若出现回归问题，回滚升级并记录风险点

3. 可执行脚本的加固原则

当 Skill 依赖可执行脚本时，脚本的健壮性应始终优先于代码的巧妙性。脚本必须做到：失败可预期、输出可理解、参数可解释。

原则	说明	示例
显式处理错误	捕获常见异常，转化为可理解的输出	ERROR: Config file not found: ./deploy.yamlHINT: Please check whether the file path is correct.
输出自解释日志	成功和失败路径都要有明确输出，验证类脚本应列出通过项与失败项	CHECK FAILED: Node.js version mismatch* Required: >= 18.0.0* Detected: 16.14.0
避免魔法数字	为常量添加语义化名称，说明数值来源或设计依据	TIMEOUT_SECONDS = 30 # Wait up to 30s because service startup usually completes within 10–20s

构建与迭代 Skill 的最佳流程

遵循 “评测驱动、失败优先” 的原则。

步骤	核心任务	产出
第一步	建立“无 Skill”基线，识别真实问题	问题清单
第二步	以“失败优先”为原则，定义评测用例	3–5 个评测用例 + 通过/失败标准
第三步	编写最小化 Skill，明确最短成功路径	初版 SKILL.md
第四步	补充边界条件与结构化示例	完善的 Input/Output 定义 + 示例
第五步	评测回归与持续迭代	增量更新 + 回归验证
第六步	结合真实使用路径进行校准	新问题 → 回到第二步

巧妙使用 AI 来创建和迭代 Skill

阶段一：初次创建

步骤	操作
1	让 AI 直接执行真实任务（观察追问、走偏和修正）
2	引导 AI 进行结构化复盘（成功步骤、不确定点、可抽象流程、适用场景）
3	基于复盘生成 Skill 初稿（按规范生成 SKILL.md）
4	人工快速评审并入库（关注边界是否合理、步骤是否可执行）

阶段二：持续迭代

步骤	操作
1	对齐偏差来源（分析问题源自 When / What / How 中的哪一部分）
2	直接修改 Skill 并验证回归（确保未破坏原有“黄金路径”，新错误场景已被覆盖）