AI Agent Skills设计指南：从临时脚本到岗位说明书

最近我在项目里把一堆临时拼凑的 prompt 脚本收拢成了 3 个规范的 skills，折腾了一周多，整个流程才算真正稳定下来。这段时间我在 Claude、Codex 这些 Agent 环境里反复测试 skills，也翻了不少社区里的技能包，最直观的感受是：很多人把 skill 理解为“高级 prompt”，其实它更接近一份给 AI 的岗位说明书。今天这篇就围绕 skills 这个主题，把它的设计思路、目录规范、完整案例和常见坑一次说清楚。如果你正在用 Agent 处理代码、文档、数据分析这类重复性工作，这篇应该能帮你少走不少弯路。

1. Skills 到底是什么：不是工具，是给 Agent 的“岗位说明书”

1.1 从一段临时指令到一份岗位说明书

大部分人第一次接触 skills，是从类似“给一段代码写单元测试”“帮我生成一篇周报”这种需求开始的。常规做法是把需求写进 prompt，模型靠着上下文里的几句说明完成任务。问题是，这些话每次都要重新讲，而且不同人对同一个任务的偏好差异很大。

Skills 做的事情，是把这些“临时指令”标准化成一套可复用的协议。一个 skill 内部通常包含任务拆解步骤、执行策略、必要脚本和参考资料。Agent 在运行时看到任务描述，会先判断是否匹配某个 skill，匹配成功后再把这份完整协议注入上下文，按协议干活。

打个比方：普通 prompt 是你在路边抓到个临时工，交代“把地扫了”；skills 则是一份新人手册，里面写着用什么扫把、按什么路线扫、垃圾分几类、验收标准是什么。这套手册只要写一次，以后每次召唤都能用。

所以我在项目里不再写“帮我审阅这篇文章”，而是给 Agent 挂一个blog-reviewskill。它自己会知道该调用哪些脚本、该检查哪些点、输出格式长什么样。整个过程看起来像是 Agent“学会了”一项技能，实际上是技能本身包含了一整套可执行的上下文。

1.2 Skills 与 Function Calling、插件不是一回事

有一个问题几乎每次讨论都会遇到：skills 和 function calling、插件到底有什么区别？

Function Calling 的本质是将函数转成 JSON Schema，让模型根据用户意图选择函数并填充参数。它适合“调接口”“查数据库”“执行某个动作”这类边界清晰的原子操作。问题是，它不负责描述完成任务的整体流程，也不包含业务规范。比如“生成单元测试”这个任务，靠一个函数调用很难表达清楚测试风格、覆盖率要求、mock 策略这些细节。

Skills 更像是把这些细节全部打包进去的“微 Agent”。它可以在自己的步骤里调用脚本、读取目录、检查输出，甚至嵌套调用其他外部工具。相比插件系统，skills 的触发方式也更贴近模型推理：系统先给模型一个技能清单，模型根据场景自行判断该不该加载某个技能，而不是由一个固定的按钮去激活。

当然，它们并不互斥。实际工程里我经常在一个 skill 内部去调用 function calling 暴露的外部 API，也可以让 skill 的脚本调用现有插件。Skills 提供的是编排层，function calling 是最底层的原子操作。把两者放在对立面是理解上的误区。

1.3 为什么大家都在谈 Skills：热词背后的真实需求

这段时间“前端开发 skills”“codex skills”“superpower skills”这些搜索词热度一直很高，核心原因并不复杂：Agent 的能力上限不再只取决于模型本身，而越来越取决于它有没有一套高质量的任务协议。

同样一个代码审查任务，直接让模型“看下这段代码”和给模型一个封装好的code-reviewskill，输出质量差距非常大。后者会把审查维度、优先级、项目特定规范全部带进来，产出的结论可落地得多。这种差距一旦被体验过，就很难回去了。

另一个原因是技能的可传播性。一个写得好的 skill，可以直接推到团队仓库里复用。前端的同事不用重新调教模型，拉下来放到指定目录就能享受同样的能力。这种知识复利让 skills 迅速从个人效率工具演变成了团队资产，自然有越来越多人在找技能、写技能、分享技能。

2. 解剖一个 Skill：目录结构、SKILL.md 与元数据规范

2.1 一个标准的 Skill 目录长什么样

在主流的 Agent 平台里，一个 Skill 通常是一个独立目录，目录名就是技能名，里面放一个 SKILL.md 核心文件，再按需配几个辅助目录。我第一次看到这个结构的时候觉得它太简单了，后来写多了才发现，克制才是它最难得的地方。

常见的目录结构是这样：

my-skill/ ├── SKILL.md ├── scripts/ │ ├── check_links.py │ └── count_stats.py ├── assets/ │ └── style-guide.pdf └── references/ └── review-checklist.md

SKILL.md是技能的主控文档，负责告诉模型“这个技能解决什么问题、按什么步骤做、必须遵守什么边界”。scripts/放的是可以被模型调用或手动执行的脚本，用来完成文档描述之外的确定性计算。assets/放图片、PDF、模板等非文本资源。references/放参考资料和清单，给模型更多上下文支撑。

这个结构设计的核心思路是把“判断”和“计算”分开。需要推理、判断的部分写进 SKILL.md，交给模型；需要稳定、精确的部分写进 scripts，交给代码。这样既能发挥模型的理解能力，又能保住确定性操作的可靠性。

2.2 SKILL.md 的元数据：description 和 when_to_use 决定触发边界

SKILL.md 顶部通常是一段 YAML frontmatter，用键值对描述技能基本信息。最关键的两个字段是description和when_to_use。

--- name: code-review description: 对代码变更进行结构化审查，覆盖逻辑、性能、可测试性和代码风格。 when_to_use: 当用户要求审查代码、PR、diff 或补丁时使用；仅需解释单行代码含义时不使用。 version: 1.0.0 ---

先说description。它会出现在模型的技能索引里，是模型判断“要不要调用这个技能”的主要依据。描述写得越宽泛，误触发的概率越高。我见过有人把 description 写成“处理代码相关任务”，结果用户问“这段 Python 语法怎么改”都会触发代码审查技能，白白浪费上下文。

when_to_use的作用是反向划边界，明确“什么时候不该用”。这个字段在社区早期很容易被忽略，但它实际上是降低误触发最有效的工具。好的when_to_use还要写否定项：如果任务只是修改一句话、不涉及完整交付物，就不要强行套技能流程。

这两个字段写清楚，整个技能就成功了一半。因为模型在决策是否加载技能的时候，只会看到这几行摘要，而不是整份 SKILL.md。摘要写得不准，后面再精彩也白搭。

2.3 scripts、references、assets：让 Skill 能调“手脚”

SKILL.md 负责说“怎么做”，但有些事只靠文字约束做不靠谱。比如检查文章里有没有残留的 TODO、统计代码块的数目、把日期规范化，这些都是确定性操作，用脚本几秒钟就能完成，而且不会因为模型状态波动出现漏检。

所以我在写 skill 的时候，凡是能落到脚本里的规则，绝不写进 SKILL.md 让模型“自由发挥”。举个例子，一个文档技能要求“所有内部链接必须可访问”，与其在文档里反复强调，不如让脚本去抓链接状态码，再把结果喂给模型做判断。模型只需要负责分析结果、提出修复建议，而不是凭感觉猜测链接好不好用。

references/目录里放的是参考资料，通常是模型在任务执行过程中需要查阅的规范文档、模板段落、历史案例。注意控制这些文件总长度，因为它们最后是要被塞进上下文的。一个 200KB 的 PDF 如果直接作为资源引入，会瞬间吃光上下文额度。更好的做法是提前提取关键段落，或者让脚本按需读取，而不是一股脑全部注入。

3. 从零写一个能实际跑起来的 Skill：博客审校技能完整流程

3.1 拿“博客审校”当练手项目：先拆能力边界

纸上谈兵讲再多结构，不如亲手写一个。我这边选一个适合练手的场景：博客文章发布前审校。这个任务每个人都懂，但真要让 Agent 稳定产出可用结果，需要把能力边界先拆清楚。

我定义的审校范围是：检查文章结构、术语一致性、代码示例完整性、数据引用可查性、结论和论据的匹配度。不属于这个范围的，比如深度改写、风格重写、SEO 关键词布局，我明确不碰。边界画清楚后，技能才不会变成一个什么都想干、什么都干不好的四不像。

有了边界，再想技能的工作流：先通读全文建立整体认知；再用脚本做机械检查；随后按严重程度输出分级问题列表；最后给出具体的修改建议。工作流决定了 SKILL.md 的执行步骤和辅助脚本的形态。

3.2 建立目录与编写 SKILL.md

我习惯在目录里放一个干净的可执行 demo，再慢慢迭代。先建好项目目录：

mkdir -p ~/.claude/skills/blog-review/{scripts,references}

不同的 Agent 环境扫描路径会有一点差异，但逻辑一致：把技能目录放到 agent 会扫描的路径下，它就能通过 SKILL.md 识别到技能。

接着写核心文件SKILL.md。我会把执行步骤写得足够具体，但不会死板到剥夺模型自己的判断空间：

--- name: blog-review description: 对中文技术博客做发布前质检，覆盖结构、术语、代码示例、数据引用和可读性。 when_to_use: 当用户要求“审校”“检查”“优化”一篇博客或技术文章，且完整文章内容已在上下文中时使用。当用户只是问某个段落写得好不好，不需要全文审校时不使用。 version: 1.0.0 --- # 博客审校技能 ## 任务目标 在不改变作者原意和行文风格的前提下，找出文章中的事实错误、逻辑断点、术语不统一、代码示例可运行性等问题，输出一份分级修改清单。 ## 执行步骤 1. 通读全文，判断文章类型、目标读者和核心结论。 2. 检查标题层级：是否有跳级、标题是否能概括对应段落内容。 3. 检查术语：首次出现的专有名词是否解释，全文是否保持一致。 4. 检查代码示例：能否独立运行、有无占位内容、缩进和语法是否完整。 5. 检查数据引用：来源是否标注，数字前后是否矛盾。 6. 检查逻辑链：每个结论是否有论据支撑，是否存在明显跳跃。 7. 输出分级清单：按【严重】【建议】【可选】分类，每条标注位置和修改建议。 ## 输出格式 每个问题一行，格式为： [严重级别] 位置：问题描述。修改建议：具体做法。 ## 硬性约束 - 不要改动原文风格，不要代替作者做内容扩写。 - 不要输出模糊评价，例如“整体不错”“部分内容可优化”，必须落到具体位置和具体问题。 - 如果文章本身没有明显问题，明确写“未发现严重问题”，不要为了显得专业而硬凑问题。

写完这个文件后，我意识到一个问题：SKILL.md 里的步骤不是越多越好，更不是越细越好。步骤过细会让模型变得机械，把全文审校做成逐字逐句的“挑刺”；步骤过粗又起不到约束作用。这里的平衡点是只约束关键检查项和产出格式，给模型保留判断顺序和取舍的空间。

3.3 配套脚本与审校清单

为了让机械检查自动化，我写了一个辅助脚本，专门扫描文章中的代码块，检查是否存在明显的占位内容：

#!/usr/bin/env python3 """扫描 Markdown 中的代码块，找出常见的占位内容或遗留标记。""" import re import sys FENCE_PATTERN = re.compile(r"```(\w*)\n(.*?)```", re.S) def extract_code_blocks(text: str): return FENCE_PATTERN.findall(text) def lint_code_blocks(text: str): problems = [] placeholders = re.compile(r"TODO|待补充|your code here|\.\.\.", re.I) for lang, code in extract_code_blocks(text): if placeholders.search(code): problems.append(f"[{lang}] 代码块中存在占位内容，需要补充或说明。") return problems if __name__ == "__main__": content = sys.stdin.read() for problem in lint_code_blocks(content): print(problem)

脚本写出来很简单，但它的价值是把“代码块里有没有 TODO”“有没有明显省略号”这种高频检查项，从模型的“经验判断”变成了确定性的程序检查。我在实际使用中还会给这个脚本加更多规则，比如检查内链状态、统计文章字数、提取所有标题生成目录。核心思路不变：能脚本化的检查，不靠模型瞎猜。

references/review-checklist.md是给人看的审校清单，也可以作为模型的补充参考：

- [ ] 标题是否准确反映文章核心内容 - [ ] H1/H2/H3 层级是否跳级 - [ ] 首个技术术语是否给出解释 - [ ] 每个代码示例是否可独立运行 - [ ] 数据来源是否标注并可查 - [ ] 结论是否被论据支撑 - [ ] 是否有重复段落或互相矛盾的内容

这个清单我平时写博客不一定全走，但一旦让 Agent 做正式审校，就会要求它严格对照清单过一遍。当 SKILL.md 的指令和参考资料里的清单相互配合时，输出稳定性明显提升。

3.4 把它接入 Agent 并跑通最小用例

目录建好、文件写完，接入 Agent 实际上只是把它放进扫描路径的问题。但这一步有不少细节值得注意。

第一，路径放对之后，必须做一次“冷启动测试”：开一个新的会话，直接把一篇待审校的文章丢给 Agent，看它是否会主动触发blog-reviewskill。如果它没有触发，多半是 description 或 when_to_use 写得不够清晰，这时候我会优先改这两个字段，而不是改 SKILL.md 正文。

第二，要测试负样本：给 Agent 一个简单问题，例如“把这句话改得更通顺”，看它会不会误触发。误触发虽然是上下文浪费，但更讨厌的是模型会按照审校清单把简单请求搞得很复杂，最后答非所问。

第三，最小用例要保留。我每次写完 skill 都会留一份测试文章和对应的预期输出，后续迭代时只要跑一遍用例，就能确认改动没有把原有能力搞坏。这种回归测试观念在写技能的时候很容易被忽略，但它带来的稳定性收益非常大。

4. 常见平台接入、场景扩展与工作流整合

4.1 不同 Agent 环境下的加载路径

以我实际用过的环境为例，Claude 和 Codex 在 skills 的加载路径上存在差异。有些环境支持一条命令把技能注册进配置，有些环境则要求你把技能目录放到固定位置。不过核心逻辑是相同的：Agent 启动后会扫描技能目录，解析所有 SKILL.md 的元数据，建立一份技能索引，然后在对话中按需注入正文。

我踩过的坑是：把技能目录放进了“示例文件夹”，结果 Agent 根本没有扫描它。所以引入新技能后的第一件事，不是立刻去验证技能内容，而是确认它出现在 Agent 的技能清单里。具体怎么做取决于你用哪套环境，但判断标准都一样：技能被正确索引，才谈得上触发和执行。

另外，regardless of 用什么环境，我都会坚持一个原则：技能包要小而精。市面上总有“技能大合集”类的包，动辄几十个 skill 一起装进去。可问题在于，技能索引膨胀后，模型选错技能的概率会显著上升，启动时的上下文也会被索引占掉不少空间。我只装当前业务真正用得到的 3 到 5 个技能，效果远好过囤一堆。

4.2 “Superpowers”这类技能包到底要不要用

社区里现在流行“superpowers”这类技能包，把各种生产力流程封装成大量技能合集。热词里也总能看到，所以它确实解决了一部分人“不知道有哪些 skills、怎么找 skills”的痛点。

我的建议是：可以看，可以借鉴，但不要整套照搬。这类技能包的问题是，技能之间往往有依赖关系，或者内置了大量通用设定。直接塞进你的环境，要么索引爆炸，要么风格和你的工作流不一致。更理智的做法是把合集当作“技能灵感库”，从里面挑两三个真正贴合你任务的，单独拆出来改造。

比如我看到某个“superpowers”包里有一个“撰写技术方案”的 skill，设计得不错，但我不会直接复制，而是会把它的执行步骤拆开，替换成我们团队自己的模板和评审标准。这样既吸收了别人的经验，又不至于被别人的假设绑架。

4.3 三个实战场景：前端开发、论文写作、分镜生成

Skills 能覆盖的领域远比“写代码”宽泛。我按热词里的三个典型场景简单拆一下。

前端开发场景里，最常见的 skill 是代码评审和单测生成。把团队的测试框架约定、覆盖率门槛、命名规范写进 SKILL.md，模型遇到“给这段组件写测试”时，就不再泛泛地生成测试用例，而是会按团队的风格和约定产出更符合落地要求的代码。这种技能对团队协作尤其有用，因为约定被固化下来了。

论文写作场景我用过一个“文献格式检查”的技能。它把参考文献的格式规则、引文顺序要求、图表编号规范写进技能里，配合一个检查脚本，能在论文生成后快速找出格式不一致的地方。比起每次重新描述规则，这种技能可以一次性沉淀几年的写作规范。

分镜生成是另一个很有意思的案例。有人把“脚本转分镜表”做成了 skill，里面规定了镜头编号、景别、时长、机位、对白等字段，模型拿到剧本后能直接输出标准表格。这个任务本身并不复杂，难点在于字段定义和表头规范，而这些恰好是 skills 最擅长固化的东西。

我自己的体会是，凡是“需要反复解释业务规则”的任务，都值得考虑封装成 skill。判断标准很简单：如果你发现自己连续三次对 Agent 说同一段要求，那就是该写 skill 的信号了。

5. 常见问题速查与调试技巧

5.1 安装新 Skills：来源检查、目录放置与首轮测试

不管你是自己写技能，还是从网上下载社区技能，安装一个新 skill 的通用路径就三件事：确认来源、放到正确的扫描目录、跑通最小用例。

来源检查放在第一位，因为 skill 的本质是可执行内容。SKILL.md 里的指令会进入模型上下文，scripts/ 里的脚本会在你机器上运行。一个来路不明的技能包，里面可能藏着恶意脚本，你很难通过看名字判断出来。所以我会坚持：只用自己写的，或者来源可靠、且经过逐行审查的技能。

目录放置前面 4.1 已经提过，不同环境路径不同，核心是让它出现在 Agent 的技能索引里。最后一件事是跑最小用例，无论多小的 skill，都要用一个真实任务验证它能被正确触发、能产出预期格式的结果。这三步缺一不可，我见过的绝大多数安装问题，都出在跳过来源检查或跳过首轮测试上。

5.2 高频翻车现场与排查思路

下面这个表格是我这段时间最常碰到的几个问题：

触发问题的根子大多在元数据上。我会直接把 SKILL.md 里所有内容删掉，只留 frontmatter，然后单独测试 description 和 when_to_use 是否能精准匹配需求。这两段过了，再恢复正文。这种“减到不能再减”的调试方式，比盲目改正文高效得多。

5.3 调试 Skills 的四步套路

被我用到最多的调试套路，大致分成四步。

第一步，验证脚本本身。任何脚本先脱离 Agent 单独跑，输入输出都确认无误再接回去。如果脚本本身就有一堆 bug，那模型再聪明也救不回来。

第二步，构造最小样本。不要一上来就用完整的博客文章、上万行代码去测试，取一个包含典型问题的片段就够了。这样每次调试的反馈回路非常短，能快速看出来 SKILL.md 的指令有没有被执行到位。

第三步，检查注入结果。很多 Agent 环境支持查看最终发给模型的 system prompt，里面有 skill 被加载后的完整内容。我会检查：SKILL.md 正文有没有被截断、脚本输出有没有粘贴对位置、references 的大小是否超出预期。

第四步，做回归记录。修一次，记录一次“什么问题、改了什么、结果如何”。这么做看起来麻烦，但它让我在技能迭代多次之后依然清楚每一处改动的原因，不至于改着改着把原来的能力弄丢。

5.4 安全边界：技能脚本本质上就是可执行代码

最后想认真提醒一点：很多人把 skills 当成“另一段 prompt”，忽略了一个事实——skills 里可以带脚本，脚本会在你本地环境执行。这意味着从不可信渠道获取 skills，等同于直接运行陌生人的代码。

我的安全底线是：不跑来路不明的技能；所有第三方技能必须先人工阅读 SKILL.md 和全部脚本；涉及网络请求的脚本要格外小心，确认它不会把本地数据传出去。曾经有人分享过某个“效率小技能”，实际脚本会读取系统环境变量，这种事不是危言耸听。

某些高风险领域也一样，比如逆向、渗透、样本分析相关的技能。这类技能通常被安全团队用于内部审计和授权测试，设计良好时可以把流程规范化，但前提一定是目标具备合法授权、运行环境是隔离的。普通人不要在未经授权的情况下套用这类技能，这不是技术问题，是底线问题。

我自己实际用下来最值钱的体会，是把 skills 当成“判断力的复利容器”。每次在 Agent 上调试出来的标准做法，沉淀成一个技能，下一次任务就会从一开始站在上次结果的肩膀上。与其耗时间追求一个万能的大技能包，不如把手头三五个高频任务打磨到极致。我还在持续整理手头的技能集合，后面也会继续分享怎么写好 SKILL.md、怎么给技能做版本管理和回归测试。这东西，越早开始积累，越值。