anthropics-skills | 01 - Skill 到底是什么：从提示词到可复用能力包

系列《把经验封装成能力Agent Skills 设计与落地》本文是系列第一篇。我们先不急着写SKILL.md而是先回答一个更基础的问题为什么有了提示词、脚本、插件和 MCP 之后还需要 Skill1. 一个熟悉的重复场景很多人第一次使用 Agent 工具时都会经历一个相似阶段一开始觉得它什么都能做但很快发现当你想让它稳定完成一个复杂任务时每次都要反复解释同一批信息。比如你想让 Agent 帮你写一篇技术文章。你可能需要告诉它这篇文章的目标读者是谁。标题风格要偏工程化不要太营销。文章结构要先讲问题再讲原理再给实践建议。代码示例不要太长关键逻辑要配中文解释。输出格式要是 Markdown。最后要给一个实践任务方便读者动手。如果只是写一篇文章这样解释一次也没什么。但如果你每周都要写技术文章或者团队里很多人都要按同一套标准写文档、做代码审查、处理 PDF、跑页面测试、生成周报这些重复说明就会变成成本。更麻烦的是这些说明通常散落在不同地方一部分在你的脑子里。一部分在聊天记录里。一部分在团队文档里。一部分在某个脚本目录里。一部分是你踩坑之后才知道的经验。Agent 并不会天然知道这些上下文。你不给它就猜你给得不全它就漏你每次临时补充它的表现就会随聊天状态波动。Skill 要解决的正是这个问题。2. Skill 的一句话定义Skill 是一个面向 Agent 的可复用能力包。它把完成某类任务所需的指令、流程、脚本、参考资料和资源文件组织在一个自包含目录中让 Agent 在合适的任务场景下按需加载并按照稳定流程完成工作。在这个仓库的 README 里Skills 被描述为folders of instructions, scripts, and resources that Claude loads dynamically to improve performance on specialized tasks.翻译成工程师更熟悉的话Skill 不是一句提示词而是一组被结构化管理的任务上下文。它通常至少包含一个SKILL.md文件my-skill/ └── SKILL.md更完整的 Skill 可能会包含脚本、参考资料和资源文件my-skill/ ├── SKILL.md ├── scripts/ ├── references/ └── assets/其中SKILL.md负责说明这个 Skill 做什么、什么时候触发、执行哪些步骤、遵守哪些约束。scripts/存放确定性强、适合程序执行的操作比如格式转换、校验、打包、测试。references/存放较长的背景资料、API 文档、规范说明、案例集合。assets/存放模板、字体、图片、示例文件等静态资源。这个结构看起来很简单但它背后有一个关键思想不要把 Agent 的能力只寄托在一次聊天里的临时提示词上而是把可复用经验沉淀成可以被加载、执行、迭代和分发的工程资产。3. 为什么普通提示词不够用提示词当然有价值。很多时候一句清晰的 prompt 就足以完成任务。但提示词有几个天然限制。3.1 提示词容易散落如果你为某个任务写了一段效果很好的 prompt它可能存在聊天记录、个人笔记、团队文档或某个 README 里。下次要用时你需要自己找出来再复制给 Agent。团队协作时这个问题会更明显。每个人都有自己的提示词版本表达略有不同效果也会不同。久而久之团队并没有真正共享一套稳定能力而是在共享一堆松散经验。3.2 提示词难以携带工具和资源很多真实任务不只是“告诉模型怎么想”还需要使用工具。比如处理.docx文件时模型需要知道它本质上是一个 ZIP 包内部是 XML还可能需要调用脚本解包、修改、校验、重新打包。再比如测试 Web 应用时模型可能需要启动本地服务、打开浏览器、等待页面加载、截屏、读取控制台日志。这些任务只靠提示词描述会很脆弱。更好的方式是把稳定操作封装成脚本把脚本的使用方法写进 Skill让 Agent 在需要时调用。3.3 提示词难以表达渐进式上下文一个复杂任务可能有大量资料但 Agent 并不需要一开始读完所有内容。以 API 集成为例如果用户正在写 Python就不需要加载 TypeScript、Java、Go 的全部示例如果用户只问流式输出就不需要读完整的模型迁移指南。Skill 可以把主流程放在SKILL.md把大段资料拆到references/并在主文件中说明什么时候读哪个文件。这样既减少上下文浪费也降低模型读错材料的概率。3.4 提示词难以评估和迭代如果一个 prompt 效果不好你当然可以改。但改了什么、为什么改、是否真的变好往往没有记录。Skill 更适合工程化迭代。你可以为它准备测试 prompt比较有无 Skill 时的输出差异记录失败案例再针对触发条件、执行流程、脚本能力和参考资料做小步优化。这也是 Skill 和普通提示词最大的区别之一Skill 不只是“怎么说”还包括“怎么组织、怎么执行、怎么验证、怎么演进”。4. Skill 的核心价值Skill 的价值可以概括为四件事降低重复沟通、固化工作流程、复用确定性工具、统一团队标准。4.1 降低重复沟通当一个任务被 Skill 化后用户不需要每次都重新解释完整背景。只要任务意图命中 Skill 的触发条件Agent 就可以加载对应说明。比如你可以把“中文技术文章写作规范”做成 Skill。以后用户只要说“帮我把这段素材整理成一篇技术博客”Agent 就能知道文章结构、语言风格、代码说明方式、结尾实践任务等默认要求。4.2 固化工作流程好的 Skill 不只是给模型一堆要求而是明确流程。例如一个文档共创 Skill 可能要求 Agent 先收集上下文再设计结构再分章节起草最后做读者视角检查。这个流程一旦写入 Skill就不依赖某次聊天中用户是否提醒。流程固化之后Agent 的表现会更稳定团队也更容易对齐“我们希望它怎么做事”。4.3 复用确定性工具模型擅长理解意图、归纳信息和生成内容但不擅长做需要严格一致性的文件操作。例如检查.docx是否符合 Office XML 规范。将 PDF 转成图片并进行视觉校验。启动本地 Web 服务并执行 Playwright 测试。将 React 项目打包成单个 HTML 文件。扫描输出文件是否满足格式约束。这些操作更适合脚本。Skill 可以把“什么时候调用脚本、脚本参数是什么、失败后如何处理”写清楚让 Agent 和程序各自做擅长的事。4.4 统一团队标准团队里很多规范并不是代码层面的而是流程层面的。比如代码审查时先看正确性再看可维护性最后看风格。技术方案必须说明备选方案和放弃原因。事故复盘必须包含时间线、影响面、根因、改进项和 owner。对外文档必须统一术语、语气和免责声明。这些规范如果只靠口头传播很容易漂移。写成 Skill 后它就变成一种可以复用、审查和迭代的团队资产。5. Skill 不是什么理解 Skill 时也要避免把它想得过大。它有自己的边界。5.1 Skill 不是万能插件Skill 不能凭空获得系统权限也不能替代宿主环境提供的工具能力。它告诉 Agent 如何完成任务但能不能读文件、跑命令、访问浏览器、调用外部服务仍然取决于运行环境提供了什么能力。换句话说Skill 更像“任务说明书 工具包”不是“自动拥有一切权限的插件”。5.2 Skill 不是完整应用一个 Skill 通常不应该承载完整业务系统。它可以包含脚本但这些脚本应该服务于某类 Agent 工作流而不是把 Skill 目录变成一个复杂应用仓库。如果你的需求已经需要独立服务、数据库、前端页面、后台任务和权限系统那它更适合做成应用或平台。Skill 可以作为这个平台的 Agent 使用指南但不应该替代平台本身。5.3 Skill 不等同于 MCPMCP 更像是一种让模型连接外部工具和服务的协议。它回答的是Agent 如何以标准方式调用外部能力Skill 更像是任务层面的能力说明和资源组织。它回答的是面对某类任务Agent 应该按什么流程做、读哪些资料、用哪些脚本、遵守哪些约束两者可以互补。一个 Skill 可以告诉 Agent 在什么场景下使用某个 MCP 工具也可以说明调用顺序、输入输出格式和异常处理方式。5.4 Skill 不是把所有知识塞进一个文件新手写 Skill 时很容易把所有材料都复制到SKILL.md。这会让文件越来越长也会让 Agent 每次触发都加载大量无关内容。更好的方式是SKILL.md保持主流程清晰。大段参考资料拆到references/。稳定操作放进scripts/。模板和静态资源放进assets/。在主流程里说明“什么时候读哪个文件”。这也是后续文章会重点展开的“渐进式加载”思想。6. 什么任务适合做成 Skill不是所有事情都值得 Skill 化。判断一个任务是否适合做成 Skill可以看五个标准。6.1 高频如果一个任务只做一次直接写 prompt 就够了。Skill 更适合那些反复出现的任务比如周报、代码审查、文档转换、测试验证、API 接入、方案评审。6.2 稳定Skill 适合沉淀相对稳定的流程。如果规则每天都变过早封装反而会制造维护负担。稳定不代表永远不变而是说它有一套可描述的默认流程即使后续迭代也是在这个基础上小步优化。6.3 可描述如果你无法说清楚这个任务的输入、输出、关键步骤和约束Agent 也很难稳定执行。一个适合 Skill 化的任务至少应该能回答用户通常会怎么提出这个需求Agent 应该先做什么再做什么哪些信息必须确认输出应该长什么样哪些情况应该拒绝、暂停或询问用户6.4 可验证可验证的任务更容易迭代。比如“把 CSV 清洗成规范表格”可以检查列名、行数、空值、格式“生成周报”可以检查是否包含目标、进展、风险、下周计划“测试 Web 页面”可以检查页面是否加载、按钮是否可点击、控制台是否有错误。如果任务高度主观也可以做 Skill但需要更依赖人工评审和风格示例。6.5 有明确边界好的 Skill 应该有清晰边界。它知道自己负责什么也知道什么时候不应该介入。比如xlsx类 Skill 可以负责读写表格文件但如果用户只是想写一个数据库 ETL 脚本它就不应该被触发。边界越清楚误触发越少用户体验越稳定。7. 一个最小 Skill 长什么样先看一个非常小的示例。假设我们想创建一个“中文提交说明”Skill要求 Agent 根据改动生成中文变更主题和有序变更列表。--- name: chinese-commit-summary description: 生成中文代码提交说明。用户要求总结代码变更、生成 commit message、整理变更主题或提交内容时使用。输出必须包含一个中文变更主题和一个有序变更内容列表。 --- # Chinese Commit Summary 当用户要求总结代码变更时先阅读相关 diff 或文件再生成中文提交说明。 ## 输出格式 变更主题[一句话概括本次变更] 变更内容 1. [第一项变更] 2. [第二项变更] 3. [第三项变更] ## 写作要求 1. 优先描述用户可感知的行为变化。 2. 不夸大影响范围。 3. 如果包含风险或未验证项在末尾单独说明。这个 Skill 很小但已经具备几个关键元素name是稳定标识。description说明能力和触发场景。正文定义了执行方式和输出格式。约束明确避免每次都重新说明。后续如果这个 Skill 变复杂可以继续增加references/style-guide.md团队提交说明风格规范。scripts/check_commit_summary.py检查输出是否包含主题和有序列表。examples/存放优秀提交说明样例。这就是从一句提示词逐步演进为能力包的过程。8. 从这个仓库看 Skill 的几种类型这个项目本身就是一个很好的参考样本。它包含多种类型的 Skill。8.1 文档处理类例如docx、pdf、pptx、xlsx。这类 Skill 的特点是文件格式复杂单靠模型解释不够需要脚本参与。它们通常会包含文件解包、格式转换、内容提取、校验、重新打包等确定性步骤。8.2 开发工具类例如webapp-testing、mcp-builder、web-artifacts-builder。这类 Skill 更像开发工作流指南。它们会告诉 Agent 如何启动服务、如何测试页面、如何构建 MCP Server、如何打包前端产物。8.3 设计与创作类例如algorithmic-art、canvas-design、frontend-design、theme-factory。这类 Skill 的重点不一定是脚本而是审美原则、创作约束、输出风格和资源模板。8.4 知识库型例如claude-api。这类 Skill 的重点是让 Agent 在写代码前先读取权威资料避免凭过时记忆猜 API。它通常会把资料按语言、平台、功能拆分主文件只负责路由和关键约束。这些类型说明Skill 不是某一种固定形态。只要它能把某类任务所需的上下文、流程和工具稳定组织起来就可以成为一个有价值的 Skill。9. 常见误区9.1 把 Skill 当成更长的 promptSkill 不是把 prompt 写长而是把任务流程结构化。一个 3000 行的SKILL.md不一定比一个 100 行的SKILL.md更好。如果内容没有分层反而会增加模型负担。9.2 只写原则不写流程很多 Skill 看起来写了很多“应该怎样”但没有告诉 Agent “先做什么、再做什么、遇到异常怎么办”。这样的 Skill 容易变成口号无法稳定改变行为。9.3 忽视触发条件description是 Skill 被召回的入口。如果 description 写得太抽象Agent 可能不会在该用时使用它如果写得太宽泛又可能在不该用时误触发。后续我们会单独用一篇文章讲 description 的写法因为它往往比正文更影响 Skill 的实际效果。9.4 把确定性任务交给模型硬做如果一个任务可以用脚本稳定完成就不要让模型每次重新“理解并手工操作”。比如格式校验、文件转换、批量重命名、结构检查这些都更适合程序。Agent 应该负责判断何时使用脚本、如何解释结果、失败后如何恢复而不是替代脚本做所有事情。9.5 没有评估就开始推广一个 Skill 在作者机器上看起来好用不代表团队里所有人都能稳定使用。至少应该准备几条真实测试 prompt覆盖常规场景、边界场景和容易误触发的场景。Skill 是可以迭代的资产。没有评估就很难知道它是在变好还是只是变长。10. 小结这篇文章只回答一个基础问题Skill 到底是什么我们可以把它记成一句话Skill 是面向 Agent 的可复用能力包用来把某类任务所需的指令、流程、脚本、参考资料和资源文件组织起来让 Agent 在合适场景下稳定复用。它和普通提示词相比更强调结构化、可复用、可验证和可维护它和脚本相比更强调任务上下文和人机协作流程它和 MCP 相比更偏任务层编排而不是外部工具协议它和完整应用相比则更轻量更适合沉淀 Agent 工作流。接下来几篇文章会继续展开为什么 Skill 能把隐性经验变成显性流程。一个SKILL.md的最小结构应该怎么写。为什么 description 是 Skill 触发效果的关键。如何通过渐进式加载控制上下文成本。11. 实践任务现在可以做一个很小的练习。请从你最近一周反复让 Agent 做过的任务里挑一个写下四句话这个任务叫什么用户通常会怎么提出这个需求Agent 应该输出什么这个任务里有哪些每次都要重复说明的规则例如任务名称中文技术文章大纲生成 触发方式用户说“帮我把这个主题整理成文章大纲” 期望输出Markdown 格式的大纲包含目标读者、核心问题、分节标题和实践任务 重复规则面向工程师结构要清晰不要营销腔每篇都要有一个可执行练习这四句话就是一个 Skill 的雏形。下一篇我们会继续讨论如何把这类隐性经验整理成显性流程并判断它是否真的值得 Skill 化。