最近我在项目里把一堆临时拼凑的 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.mdSKILL.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(rTODO|待补充|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 高频翻车现场与排查思路下面这个表格是我这段时间最常碰到的几个问题现象可能原因解决思路该触发时不触发description 没有覆盖实际任务场景用用户的真实措辞重写描述不该触发时总触发when_to_use 缺少否定条件在 when_to_use 中明确“何时不用”每次调用都要吃大量上下文skills 太大references 注入过重精简正文脚本按需读取外部资料输出格式总是变SKILL.md 的格式说明不够具体给出一个输出模板最好配示例脚本报错导致任务中断脚本只测了理想路径补充异常处理给脚本做边界输入测试触发问题的根子大多在元数据上。我会直接把 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、怎么给技能做版本管理和回归测试。这东西越早开始积累越值。