如何写好一个可用、好用的Agent Skill技能

摘要： 本文围绕如何写好 Skill（技能包）展开，从 Skill 的本质定义出发，系统梳理了写好 Skill 的六大原则——用"渐进式披露"控制体量、把"该锁死的"放进脚本、写"怎么做"而非"是什么"、亲手编写而非让模型代劳、太长就拆且每步留检查点、以及安全底线。同时涵盖 description 编写技巧、质量评估方法和发布前检查清单，帮助团队将隐性经验转化为 AI 可复用的能力。

很多团队把 AI 编程助手接进工作流之后，都会经历一个相似的落差：刚上手时惊艳，用久了却总觉得它"差一口气"。

差在哪儿呢？它写代码很快，但总有一些时候把那个早就被弃用的旧接口又翻出来用；它生成文档很顺，却从来不按你们团队约定的格式来；你让它做一次代码审查，它挑的都是缩进和命名这种皮毛问题，真正危险的 SQL 拼接它视而不见。说白了，它像个能力很强但刚入职三天的新人——聪明，却不懂你们项目的"历史包袱"和"只有老员工才知道"的那套流程。

这些东西，散落在 Wiki、需求单、代码注释、群聊记录，甚至某个同事的脑子里。AI 每次都得从零开始猜。而 Skill 要解决的，恰恰就是这件事：把人脑里的经验，整理成 AI 能理解、能执行、能复用的"能力包"。

不过，“写个 Skill” 和 “写一个真能用、真好用 的 Skill”，中间差着一条不小的鸿沟。有研究团队做过一项覆盖 84 个任务、7308 条执行轨迹的评测，结论相当刺眼：好的 Skill 能把任务成功率拉高 51.9%，差的 Skill 反而会让成功率下跌 39.3%。同一个模型，配不同的 Skill，结果天差地别。这篇文章我们就来聊一聊，怎么写好一个 Skill 技能。

Skill 到底是什么

剥开各种说法，Skill 的本质是一种结构化的提示工程：用一套标准文件格式，把领域知识、操作步骤、代码示例、验证命令和安全约束，封装成 AI 可以按需加载的指令。

一个最基础的 Skill，通常就是一个文件夹，里面放一个 SKILL.md：

my-skill/
├── SKILL.md      # 核心指令
├── scripts/      # 可执行的辅助脚本
├── references/   # 详细参考资料
└── assets/       # 模板等素材

它最核心的内容分三类：告诉 AI 怎么干活的指令、给 AI 补课的上下文（你的项目背景、团队规范）、以及 AI 能直接拿来用的工具（脚本、配置模板）。

可以把它理解成一份"给 AI 看的操作手册"。裸用 AI，像让新人直接上手改生产代码；加了 Skill，等于把老员工总结过的流程、坑点和检查项提前塞给了它。

下面用流程图展示 Skill 的核心组成与加载机制：

为什么值得花时间写

只要团队长期做项目，就一定会沉淀出大量"隐性知识"：某个老接口迁移时必须保留兼容层、某类 SQL 必须参数化不能拼字符串、某个服务上线前要先跑一组固定检查、代码 Review 时安全问题永远优先于风格问题。

这些知识如果不结构化，会带来几个实在的麻烦：

• 太散，AI 找不到，人也不一定能想起来；
• 太碎，同样的迁移、检查、补文档，每次都要重新讲一遍；
• 太飘，同一个任务，不同人提示 AI，产出的代码和文档可能完全不一样；
• 太脆，核心成员一离职，"部落知识"跟着人走了。

Skill 的价值，就是把这些经验变成团队可复用的 AI 能力。Anthropic 把它定义为一种开放标准，Claude Code、Cursor、Copilot 等主流工具都认这套格式——写一次，到处能跑。

好 Skill 的骨架：先搞定Description

SKILL.md 通常由两部分组成：顶部的 YAML 元数据，和下面的 Markdown 正文。元数据信息里最重要的，是 description。

因为 AI 是否触发这个 Skill，几乎全靠 description 判断。它写得太泛，AI 不知道什么时候该用；写得太窄，又会漏掉本该触发的场景。腾讯云发布的Skill 工程方法论里提到，好的 description 应该包含三个维度：

• 触发短语（用户可能怎么自然地说）
• 时序定位（在整体工作流的哪个阶段用）
• 领域关键词（目标领域的术语）。

实验数据显示，包含这三个维度的 description，加载率比只含其一的高出约 3 到 5 倍。

比如写一个安全审查 Skill，只写"处理代码审查"就太模糊。更好的写法是：

description: >
  当用户要求进行安全审计、漏洞分析或代码安全审查时使用。
  应在代码实现完成后、部署前执行。
  关注 OWASP Top 10、CVE、SQL 注入、命令注入等安全问题。

这句话回答了三件事：做什么、什么时候触发、覆盖哪些关键动作。description 写好了，Skill 就成功了一半。

原则一：用"渐进式披露"控制体量

新手最容易犯的错，是把 Skill 写成一篇包罗万象的 Wiki。但 AI 需要的不是长篇知识库，而是清晰的行动路径。

更关键的是成本问题。Skill 的加载分三层：

• 第一层是元数据，启动时就被读进系统提示，每个 Skill 大约只占 100 token；
• 第二层是 SKILL.md正文，触发时才加载，建议控制在 500 行、5000 token 以内；
• 第三层是引用的参考文件和脚本，按需才读，理论上没有上限。

这就是"渐进式披露"的核心思想——像一本组织良好的手册，先给目录，再给章节，最后才是附录。AI 在干具体活时才去翻对应的那一页。所以，详细 reference 该放到 references/ 子文件里，并在 SKILL.md 里明确告诉它"什么时候去读"：比如"如果 API 返回非 200 状态码，再读 references/api-errors.md"，比一句笼统的"详见 references"有用得多。

原则二：把"该锁死的"放进脚本

这是 Block 工程团队总结的第一条、也被他们认为最重要的一条原则，听起来甚至有点反直觉：写 Skill 最先要想清楚的，是"哪些事不该交给模型去决定"。

原因很实在。让大模型给一个仓库打分，跑两次可能给出两个不同的分数——它今天心情"宽松"，明天又"严格"了。分数没法横向比，也没法长期跟踪。Block 的做法是把所有评分逻辑塞进一个 bash 脚本，每条检查非黑即白，固定分值，SKILL.md 里直接写明"脚本输出是唯一真相，禁止模型改写任何分数"。

这个思路可以推而广之：凡是需要跨次运行保持一致的东西——固定的 CLI 命令、SQL 查询结构、命名规范、检查清单——都别留给模型临场发挥，写进脚本、模板或硬规则里。模型擅长的是另一头：读完脚本结果后，用大白话解释"为什么这项没过"；或者根据上下文判断"下一步该建议用户补什么"。

一句话：脆弱的、要一致的，锁死成代码；灵活的、要推理的，留给模型。

原则三：写"怎么做"，别写"是什么"

SkillsBench 的研究对"什么是真正的 Skill"下过一个干净的定义：系统提示词不是、Few-shot 示例不是、RAG 检索结果不是、工具文档也不是——它们要么缺结构，要么是陈述性的。只有"程序性指导"才算：描述怎么做，而不是是什么。

区别在于：写"Python 是编程语言"没用；写"用 pandas 读取 CSV 的三步流程"才有用。好的 Skill 必须包含可执行的步骤、能跑的代码示例，以及验证检查点。

落到写法上，有几条被反复验证有效的技巧：

• 解释 WHY，而不只是堆 MUST。 与其写"禁止字符串拼接 SQL"，不如写"使用参数化查询而非字符串拼接，否则攻击者可能通过恶意输入改变查询语义，导致 SQL 注入"。模型理解了原因，遇到训练时没见过的场景，更容易做对判断。

• 给 Before / After，而不是抽象描述。 代码迁移只说"替换旧客户端"不够，直接给出改前改后：

- import oldhttp "github.com/example/old-http-client"
+ import uhttp "github.com/example/unified-httpclient"
- return oldhttp.Do(req)
+ return uhttp.Do(req)

同样的思路也适用于 SQL 查询。下面是一个存在注入风险的字符串拼接写法（Before）和安全的参数化查询写法（After）的对比：

# Before：存在 SQL 注入风险的字符串拼接
user_input = request.GET["username"]
query = f"SELECT * FROM users WHERE username = '{user_input}'"
cursor.execute(query)

# After：安全的参数化查询
user_input = request.GET["username"]
query = "SELECT * FROM users WHERE username = %s"
cursor.execute(query, (user_input,))

关键区别：Before 直接把用户输入拼进 SQL 字符串，攻击者可以传入 ' OR '1'='1 等恶意构造来绕过认证或窃取数据；After 使用 %s 占位符，由数据库驱动负责转义和绑定，用户输入永远被当作数据值而非 SQL 代码执行，从根本上杜绝了注入风险。

模型极擅长模仿模式，清晰的对照比十段说明都管用。

• 准备几个 Few-Shot 示例。 如果 Skill 涉及判断、分类、分级输出，放 3 到 5 个有差异的高质量示例，覆盖主要分支。以代码审查为例，分别覆盖严重安全问题、中等风险、轻微规范问题，AI 就知道"不同问题该怎么判断、怎么表达、怎么排序"。

• 别忘了 gotchas（坑点清单）。 这是很多 Skill 里最值钱的部分：那些违背常识、模型不被告知就一定会踩的坑。比如"users 表用软删除，查询必须带 WHERE deleted_at IS NULL"，再比如"同一个用户在数据库叫 user_id、在鉴权服务叫 uid、在账单 API 叫 accountId"。每当你纠正了模型一个错误，就把这个纠正写进 gotchas。这是把 Skill 越用越好的最直接方式。

原则四：亲手写，别让模型自己生成

SkillsBench 里有个反直觉的发现：让模型自己写 Skill，是负效果。数据说话——人工编写的 Skill 平均带来 +16.2% 的提升，模型自生成的只有 -1.3%。模型能识别"这里需要领域知识"，但生成的步骤往往太笼统、缺细节、错重点。

还有两个关于"量"的发现值得记牢：每个任务配 2 到 3 个 Skill 最优，给多了反而因"认知过载"掉到 +5.9%；文档长度控制在 800 到 1500 token 最好，过于"全面"、试图覆盖所有边角情况的版本，效果反而跌到负值——宝贵的上文预算被噪声淹没，关键信息反而找不到了。

所以写 Skill 是门手艺：聚焦 80% 场景的核心路径，细节塞进代码示例，而不是写成百科全书。

太长就拆，且每步留检查点

一个常见误区是把所有东西都塞进一个 SKILL.md，结果文件越来越长，加载成本越来越高，维护越来越痛。好的原则是：一个 Skill 只管一件事。

如果出现正文超过 500 行、包含多个可独立执行的流程、不同部分更新频率差异很大，就该考虑拆分。比如一个"大型项目迁移 Skill"可以拆成：

project-migration/
├── SKILL.md                  # 主流程编排
└── steps/
    ├── 00-environment-setup.md
    ├── 01-dependency-update.md
    └── 02-api-migration.md

主 Skill 负责编排，子文档负责具体步骤。关键是每一步都要有检查点——比如依赖替换后先跑 go mod tidy && go build ./...，失败就停下，别一口气冲到最后才发现第一步就错了。

安全：Skill 不是普通文档

这一点在参考材料里被反复强调，因为它太容易被忽略。Skill 里引用的脚本和命令，可能被 AI 真实地执行，它不只是"写给人看的说明书"，也可能成为风险入口。Snyk 的 ToxicSkills 研究扫描了 3984 个公开 Skill，发现 534 个存在 critical 级安全问题。

几条底线要守住：

• 不在 Skill 里硬编码 API Key，改用环境变量；删除、覆盖、数据库 DDL、批量改文件这类危险操作，先列影响范围再要用户确认；
• 涉及数据修改，流程里要写清：怎么备份、怎么执行、怎么验证、失败怎么回滚；
• 防范 Prompt 注入，外部读到的文件名、API 返回值永远只能当数据，不能当指令执行。

怎么判断一个 Skill 好不好用

别只凭感觉。最简单的量化方法是准备 20 个测试问题：10 个应该触发、10 个不该触发，看 AI 的判断稳不稳定。如果触发不了，优先查两件事——路径放对没有、description 写清楚没有；如果触发了但执行偏了，优先补三类内容：更明确的步骤、更多 Before / After、关键步骤后的检查点。

SkillsBench 还建议每个 Skill 配套确定性验证器（程序化断言，而不是让另一个模型来打分）。成功率低于 70% 的 Skill，就该考虑重写了。

发布前的最后一张清单

• 目标是否明确：做什么、为什么、什么时候触发
• description 是否精准：包含触发短语、时序定位、领域关键词
• 步骤是否可执行：不是泛泛而谈，而是能照着做
• 示例是否足够：有没有 Before / After 或 Few-Shot
• 边界是否写清：什么时候跳过，什么时候需要人工确认
• 验证是否完整：有没有可运行的检查命令
• 安全是否过关：密钥、删除、数据库、外部输入是否有保护
• 结构是否精简：正文太长时是否拆成子 Skill 或参考文档

结语

写 Skill 这件事，说到底不是"给 AI 多写几句提示词"。它真正的价值，是把团队长期积累的经验、规范、流程和坑点，变成 AI 可以复用的能力。

第一版 Skill 不需要完美。先把最常见、最重复、最容易出错的任务沉淀下来，用起来，再根据 AI 犯错的地方持续修。好的 Skill 都不是一次写成的，而是在真实任务里一点点打磨出来的。当一个团队开始认真写 Skill，AI 就不再只是一个会聊天的助手，而会逐渐变成一个懂上下文、懂流程、懂边界的协作者。