写好一个 Skill，不是把 Prompt 塞进 SKILL.md 就算完事。格式混乱、触发词模糊、没有错误处理——这些毛病在 Prompt 时代还能将就，在 Skills 体系里会被放大成系统性故障。本文整理了10条经过实战打磨的写法规范，配合最后的海报版 Checklist，帮你在落笔前就排掉 80% 的低级错误。

一、排版与结构：写给机器读，也写给人读

SKILL.md 的第一读者不是人，是 Agent runtime。但糟糕的排版会让两者都看不懂你写的是什么。好的结构是 Skill 可维护、可复用的基础，也是 Agent 能够稳定执行的前提。

1.1 规则一：文件头必须有完整的 Front Matter

每个 SKILL.md 必须以标准 YAML Front Matter 开头，包含 name、version、description、triggers 四个核心字段。没有这四个字段，Agent 在解析时会产生不可预测的行为——你以为它懂了，其实它在猜。

---
name: leave-approval
version: "1.2.0"
description: "处理员工请假申请，支持自动审批与人工升级"
triggers:
  - "请假"
  - "申请休假"
  - "我要请假"
---

1.2 规则二：用三层结构组织正文（Overview → Steps → Constraints）

SKILL.md 的正文应该遵循"概述 → 步骤 → 约束"的三层结构。Overview 解释 Skill 的目的和适用范围，Steps 描述主流程，Constraints 列出所有边界条件和限制。把这三层乱混在一起，是大多数初学者最常见的错误——模型在理解时会把"约束"当"步骤"执行，把"概述"里的例外条件当成主逻辑的一部分。

1.3 规则三：步骤之间保持原子性

每个步骤只做一件事。"收集信息并验证并发送通知"这种连环操作在 SKILL.md 里是毒药——一旦某个环节失败，Agent 不知道应该从哪里重试，要么全重来，要么什么也不做。原子步骤让错误边界清晰，让重试有意义，也让日志可读。

二、描述与触发词：让 Agent 精准识别，不乱入场

触发词写得烂，Agent 会在不该启动的时候启动，在该启动的时候沉默。这不是模型的锅，是你 Skill 写得有问题。描述和触发词是 Skill 被正确调用的入口，也是整个 Skills 体系中最容易被忽视的部分。

2.1 规则四：description 字段要写"做什么"，不要写"是什么"

description: "请假审批技能" 和 description: "处理员工提交的请假申请，判断是否满足自动审批条件，超过阈值时升级到人工审核" 是两回事。前者是命名，后者才是描述。Agent 在 Skill 匹配时依赖 description 做语义理解，写"是什么"等于给它一个没用的标签。

2.2 规则五：触发词覆盖核心同义表达，但不要贪多

触发词不是 SEO 关键词，不要往里塞几十条。覆盖 3-5 个核心语义变体足够，剩下的交给模型的语义理解负责。真正需要警惕的是触发词过于宽泛——比如把"审批"作为触发词，会让请假 Skill 在用户谈报销审批、合同审批时也跳出来，造成误触发。精确比覆盖广更重要。

2.3 规则六：输出格式在 Skill 内部定义，不要依赖外部 System Prompt

很多工程师习惯在 System Prompt 里写"所有回复必须用 JSON 格式"，然后在 Skill 里不管输出格式。这是强耦合的坏习惯。每个 Skill 的输出格式应该在自己的 SKILL.md 里通过 output_schema 字段明确定义——谁的责任谁负责，Skill 才是独立可组合的单元。一旦 System Prompt 变了，你的所有 Skill 的输出行为都会跟着漂移。

三、错误处理、版本管理与测试：别等上线才发现问题

写好主流程只是入门。真正区分"玩具 Skill"和"生产 Skill"的，是对异常、变更和测试的态度。这四条规则是让 Skill 从 demo 变成能扛住真实用户的关键。

3.1 规则七：每个关键步骤都要有 on_error 处理

没有 on_error 的 Skill 是"晴天 Skill"——一切正常时完美运行，遇到异常就裸奔。每个关键步骤都应当明确：失败了怎么办？是重试、降级还是 Escalate 转人工？不同步骤、不同性质的错误，策略应该不同。

steps:
  - id: check_quota
    action: verify_leave_quota
    on_error:
      strategy: escalate
      message: "余额查询失败，转人工处理"

3.2 规则八：约束条件集中写进 constraints，不要散落在步骤描述里

"员工试用期内不得申请年假"这条规则，如果你把它写进某个步骤的描述文字里，Agent 可能在执行其他步骤时完全忽略它。把所有约束集中到独立的 constraints 字段，Agent 在整个执行链路上都能感知到这些边界，而不是只在某个步骤里短暂记得。

3.3 规则九：版本号遵循语义化版本（SemVer），breaking change 必须升主版本

Skill 是被其他系统依赖的模块。你改了触发词、改了输出字段结构，都可能悄悄破坏下游调用方。用 SemVer 管理版本：修 bug 升 patch，加新功能升 minor，改接口/格式升 major。没有版本管理的 Skill 库，是一个等待爆炸的定时炸弹——而且通常在最不该爆的时候爆。

3.4 规则十：每个 Skill 必须有最少三个测试用例（happy path + edge + error）

Happy path 测正常流程，edge case 测边界输入（比如0天假期、跨年请假），error case 测异常处理（比如查不到员工、系统超时）。没有这三类覆盖，你的 Skill 只是在 demo 场景下能跑通，到生产就等着被用户举报。测试用例不需要多，但这三类不能少。

四、总结

十条规则归结为一句话：把你对业务的理解和对异常的预判，用机器可读的结构明确写出来，而不是靠模型去猜。Skill 不是"聪明的 Prompt"，是有契约、有边界、有版本的能力单元。这十条是底线，不是上限。

---

海报版 Checklist

╔══════════════════════════════════════════════════╗
║         ✅ Skills 写法自检清单（10条）           ║
╠══════════════════════════════════════════════════╣
║  【结构】                                        ║
║  □ Front Matter 包含 name / version /            ║
║    description / triggers 四个核心字段           ║
║  □ 正文遵循 Overview → Steps → Constraints       ║
║    三层结构，不混用                              ║
║  □ 每个步骤原子化，一步只做一件事               ║
╠══════════════════════════════════════════════════╣
║  【描述与触发】                                  ║
║  □ description 描述"做什么"，而非"是什么"        ║
║  □ 触发词覆盖 3-5 个核心变体，无歧义宽泛词      ║
║  □ 输出格式通过 output_schema 在 Skill 内定义    ║
╠══════════════════════════════════════════════════╣
║  【错误处理与约束】                              ║
║  □ 每个关键步骤有 on_error 处理策略             ║
║  □ 业务约束集中在 constraints 字段              ║
╠══════════════════════════════════════════════════╣
║  【版本与测试】                                  ║
║  □ 版本号遵循 SemVer，breaking change 升主版本  ║
║  □ 至少覆盖 happy path / edge / error 三类测试  ║
╚══════════════════════════════════════════════════╝