过去这两年AI Agent 的落地方式发生了很明显的变化。早期大家热衷于把所有工具全部接入同一个大模型结果 Agent 的上下文越来越长、指令越来越杂到了真正跑业务的时候反而经常出现“看着什么都会实际什么都做不精确”的情况。最近 Anthropic 生态里频繁出现的Agent Skills这个概念本质上就是在解决这个痛点把某一类任务的处理方法沉淀为可复用的“技能包”让模型在需要的时候按需加载而不是把所有能力都塞在一个会话里。这篇文章我不想只解释概念而是想完整拆解一套 Agent Skills 的落地思路。你会看到它是什么、解决什么问题、目录和文件如何组织、SKILL.md 怎么写以及如何通过真实案例创建一个前端开发辅助 Skill。无论你是刚接触 AI 编程的初学者还是已经在用 Claude Code、OpenCode 这类工具的开发者这篇文章都能提供一套可以直接照做的实操路径。1. 为什么需要 Agent Skills1.1 从“全会”到“精专”的转变先回忆一下我们在大模型里使用知识库或者 Prompt 的常规方式把所有要求写在一个长长的系统提示词里把相关文档、示例、注意事项全部堆进去。这种方式对小任务有效但一旦任务类型变多问题就来了。举个例子一个开发助手既要会写前端组件又要懂 Python 数据处理还要能输出 PPT 大纲。如果把这三类能力的所有细节一次性塞进上下文模型的注意力会被分散而且每轮对话都会重复消耗大量 Token。更关键的是当你调整某一类任务的执行规则时可能会影响到另外两类任务的输出质量。Agent Skills 的思路完全不同。它把“能力”拆成独立的单元一个 Skill 只负责一类任务。每个 Skill 是一个目录包含一份 SKILL.md 和若干辅助文档。系统或用户根据当前任务自动选择需要加载的 Skill。未命中的 Skill 不会占用上下文。这种“按需加载”的设计让 Agent 在保持通用能力的同时也能在特定任务上做到更专业。1.2 Skills 与 Plugins、MCP 的区别很多朋友容易把 Skills 和插件、MCP 混淆这里先做一个简单区分名称核心作用典型例子Plugin / 插件为应用扩展一组预设功能入口浏览器插件、IDE 插件MCP Server为模型提供标准化的外部数据/工具访问通道数据库 MCP、GitHub MCPAgent Skill为模型提供一套任务执行的方法论与领域知识前端组件编写 Skill、PPT 制作 Skill可以这样理解MCP 侧重“你能调用什么外部能力”Skills 侧重“你应该如何把这件事做对”。实际使用中两者并不冲突一个 Skill 内部完全可以依赖某个 MCP Server 获取数据但它给模型的核心价值是那套经过验证的执行流程、检查清单和避坑指南。1.3 适用场景从社区里目前比较热门的 Skills 案例来看比较典型的场景有前端开发类 Skill统一组件规范、样式方案、代码风格生成 Vue/React 组件时自动遵守项目约定。学术研究类 Skill从论文检索到文献综述输出的完整流程包括摘要格式、引用规范。PPT 制作类 Skill输出结构大纲、页面文案、配图建议甚至协作生成一份可直接导入的 Markdown 大纲。测试类 Skill在测试环境自动生成用例、执行断言、整理缺陷报告尤其适合对测试流程有明确规范的项目。数据清洗类 Skill统一缺失值处理、异常值检测、字段类型转换等数据处理规则。无论哪种场景它们背后都有一个共同特征任务有相对稳定的方法论且我们希望每次执行结果都保持一致。这正是 Skills 发挥价值的地方。2. 环境准备与版本说明2.1 你需要准备什么在开始创建 Skill 之前你需要先确认自己当前的运行环境。根据官方生态和社区实践Agent Skills 主要在支持 Anthropic Claude 模型的应用中使用比如 Claude 官方客户端、Claude Code 命令行工具以及部分支持 Skills 标准的第三方 Agent 工具如 OpenCode。环境准备清单大致如下工具用途Claude 账号访问模型能力部分功能需要订阅支持Claude Code 或支持 Skills 的 Agent 客户端加载和执行 Skill文本编辑器编写 SKILL.md 与辅助文档Git可选对 Skill 做版本管理方便复用和回滚关于版本我这里给一个比较稳妥的说明Skills 的目录约定和加载机制在不同客户端中可能存在差异建议你以官方文档的最新说明为准。下面的示例我会采用社区目前较为通用的结构来演示核心是让你掌握设计思路而不是死记某个版本号。2.2 Skills 的目录结构约定一个标准的 Skill 通常放在项目的skills目录下结构类似这样skills/ └── frontend-component/ ├── SKILL.md ├── references/ │ ├── component-style-guide.md │ └── ui-library.md └── procedures/ └── create-component-check.mdSKILL.md是 Skill 的核心文件包含元信息和执行指令。references/用于存放参考文档详细展开知识细节。procedures/用于存放流程检查清单等辅助文件。其中SKILL.md是必须的其他目录可以根据需要灵活组织。如果你的 Skill 比较简单只放一个SKILL.md也完全可以运行。3. 核心原理拆解SKILL.md 的结构与写法3.1 一份最简 SKILL.md先来看一个最小可用的示例--- name: markdown-cleaner description: 清理 Markdown 文档中的多余格式输出符合团队规范的精简版本。 --- # Markdown Cleaner 当你需要对 Markdown 文档进行格式清理时请遵循以下步骤 1. 检测文档内是否包含非正文内容如调试信息、临时注释。 2. 删除连续空行保留单个空行作为段落分隔。 3. 统一标题层级一级标题只能出现一次其余从二级开始。 4. 将列表统一为无序列表风格去除多余嵌套。 5. 输出清理后的完整文档并简要说明修改点。 ## 禁止事项 - 不要修改正文中的代码块内容。 - 不要改变原有语义只做格式层面的清理。这个文件很短但它已经具备了一个 Skill 的完整骨架元信息frontmatter加正文指令。模型通过description字段判断“什么情况下应该加载这个 Skill”一旦加载正文中的步骤就会被严格遵循。3.2 元信息字段详解在---包裹的 frontmatter 中最常见的是四个字段字段作用建议nameSkill 唯一名称使用小写字母和短横线如frontend-componentdescription描述这个 Skill 的作用与触发场景要写清楚“何时用”而不是“是什么”when_to_use进一步说明触发条件可选但推荐补充version版本号可选方便做版本管理description是关键。模型通常会先阅读这个字段来决定是否调用 Skill所以不要写得太笼统。比如“帮助写前端代码”就过于模糊应该改成“当用户要求生成或修改 Vue/React 组件需要遵循项目内组件规范时使用”。3.3 正文指令的写法正文部分是真正影响模型行为的内容建议采用“步骤 约束 示例”的结构。第一步是给流程。把任务拆成 3 到 8 个清晰步骤并且使用可执行的动词分析、提取、生成、检查、输出。第二步是加约束。明确告诉模型“不要做什么”这往往比“要做什么”更能控制输出质量。第三步是给示例。在包含较多格式要求的场景里提供一段输入输出对照能显著提升稳定性。下面是一份典型流程指令的片段## 执行流程 1. 分析用户给出的组件需求提取组件名称、Props 接口、事件接口。 2. 根据 references/component-style-guide.md 中的风格约定生成组件代码。 3. 生成示例用法并标出必须传入的 Props。 4. 检查代码中是否出现硬编码样式如有则替换为设计变量。 5. 输出组件文件内容与一个最小可运行示例。3.4 辅助资源文件的作用当 Skill 包含大量知识细节时不应该把全部内容塞进 SKILL.md否则上下文负担会变大。推荐的做法是把大段知识放到references/下然后在 SKILL.md 中给出明确的引用提示。例如前端开发 Skill 的references/component-style-guide.md里可以写# 组件风格指南 ## 组件结构 - 每个组件必须包含 props 类型定义。 - 禁止在组件内部直接调用全局状态。 - 样式变量统一从设计系统 import。然后在 SKILL.md 的对应步骤中写明2. 参照 references/component-style-guide.md 中的组件结构要求逐项检查生成结果。这样可以在不增加主指令复杂度的前提下保留完整的领域知识。4. 完整实战创建一个前端开发辅助 Skill下面我们一步一步创建一个可以用于前端组件生成与检查的 Skill。我会把整个流程拆成需求分析、目录创建、文件编写、加载验证四个阶段。4.1 需求分析假设你所在团队使用 Vue 3 TypeScript组件库是 Element Plus。你希望 Agent 在生成组件时自动遵守以下规则使用script setup langts语法。所有 Props 必须有类型定义和默认值。组件内不允许直接操作 DOM必须通过 ref 和生命周期函数完成。样式统一使用 scoped并且颜色值从主题变量中读取。生成组件后必须附带一个最小示例。这些规则如果每次都写在对话里不仅麻烦而且容易遗漏。我们可以把它们封装成一个 Skill。4.2 创建目录结构在项目根目录下创建如下结构skills/ └── vue-component/ ├── SKILL.md └── references/ └── vue-style-guide.md命令可以这样执行mkdir -p skills/vue-component/references4.3 编写 SKILL.md文件路径skills/vue-component/SKILL.md--- name: vue-component description: 当用户要求生成、检查或修改 Vue 3 组件且项目使用 TypeScript 和 Element Plus 时使用。遵循组件规范并输出可复用的结构。 when_to_use: 检测到 Vue 3、TypeScript、Element Plus、组件开发等关键词时使用。 version: 1.0.0 --- # Vue 3 组件开发助手 本 Skill 用于在 Vue 3 TypeScript Element Plus 项目环境中创建高质量、可维护的组件。 ## 执行流程 1. 分析用户需求明确组件用途、Props 接口、事件接口和插槽需求。 2. 参考 references/vue-style-guide.md 中的规范逐条核对待生成代码。 3. 生成组件源码文件使用 script setup langts 语法。 4. 生成组件示例用法至少包含一个必须传递的 Props 场景。 5. 输出前检查以下清单 - [ ] 是否缺少 Props 类型定义 - [ ] 是否包含默认值 - [ ] 是否存在 DOM 直接访问 - [ ] 样式颜色是否使用了变量 - [ ] 是否导出了组件所需类型 ## 关键约束 - 禁止使用 Options API。 - 禁止编写无法通过 TypeScript 类型检查的代码。 - 禁止将样式写成非 scoped 全局样式。 - 事件命名必须遵循 kebab-case并以 on 前缀导出。 - 当用户未明确指定样式方案时默认使用 Element Plus 现有的布局和组件结构。 ## 输出格式 完成组件后按以下结构输出 ### 组件代码 此处放置完整组件源码 ### 示例用法 包含组件引入、注册与使用的示例 ### 设计说明 简要说明组件设计思路以及为什么做出当前的关键决策4.4 编写辅助参考文档文件路径skills/vue-component/references/vue-style-guide.md# Vue 3 组件风格指南 ## 通用要求 - 使用 script setup langts 组合式 API 语法。 - 组件名称使用 PascalCase文件名使用 kebab-case。 - Props 使用 withDefaults 与 defineProps 定义明确类型与默认值。 - 事件使用 defineEmits 声明自定义事件名使用 kebab-case。 ## 状态管理 - 组件内部状态使用 ref 或 reactive。 - 禁止直接修改传入的 Props。 - 视图更新需要异步操作时使用 computed 或监听器。 ## DOM 操作 - 禁止在组件中直接使用 document.querySelector 等方式操作 DOM。 - 需要访问元素时使用 ref 模板引用。 - DOM 副作用应在 onMounted 或 watch 回调中处理并在 onUnmounted 中清理。 ## 样式规范 - 所有样式添加 scoped 属性。 - 颜色、间距、字体使用主题变量。 - 禁止使用 !important特殊情况需在代码审查中说明。这个文件把规则细化供模型在生成组件时检索。SKILL.md 中只保留触发条件、执行流程和输出格式避免主指令文档过长。4.5 在 Agent 客户端中加载 Skill不同工具加载 Skill 的方式略有差异。如果你使用 Claude Code 或者支持 Skills 的 Agent 工具通常只需要把skills/目录放在项目根目录然后在对话中描述需求即可。例如你可以这样发起请求请生成一个用户信息展示组件。它需要接收用户昵称、头像 URL、简介文本三个 Props并在卡片中展示。如果 Agent 能够正确识别并加载 Skill它的回答通常会遵循你定义的输出结构并自动参考vue-style-guide.md中的规范。下面是我在测试中得到的一种较理想输出形态已根据 vue-component Skill 的组件规范生成组件以下是完整代码、示例用法与设计说明。 ### 组件代码 此处为完整的 Vue 组件代码包含 SFC 结构、script setup、类型定义、模板 ### 示例用法 此处为组件在父组件中引入、注册和使用的示例 ### 设计说明 本组件采用 scoped 样式与主题变量确保样式隔离Props 提供默认值降低调用成本。如果工具支持 Skill 的可视化管理界面你也可以在界面中手动选择 Skill 或者查看当前加载了哪些 Skill。4.6 验证 Skill 是否生效判断 Skill 是否生效可以看三点输出中是否出现了你定义的专属结构比如“示例用法”“设计说明”这样的固定小节。代码是否符合参考文档中的硬性规则比如是否使用script setup langts。当你的请求里同时包含其他无关信息时Agent 是否仍然稳定执行 Skill 流程。只要这些点符合预期就说明 Skill 加载成功并正在发挥作用。5. 进阶设计不同类型 Skill 的编写要点5.1 测试应用类 Skill测试类 Skill 的核心价值是统一测试设计思路。比如一个用于接口测试的 Skill可以在SKILL.md中定义用例设计步骤、断言规范和数据生成规则。--- name: api-test description: 当需要为 REST API 编写测试用例、执行测试断言或生成测试报告时使用。 --- # API 测试助手 1. 分析接口的请求方法、路径、参数、鉴权方式。 2. 列出正常路径与异常路径用例异常覆盖缺少参数、错误类型、越权访问。 3. 生成 pytest requests 风格的测试代码。 4. 断言必须验证响应状态码、关键业务字段和部分响应时间。 5. 输出测试报告模板包含用例名称、执行时间、通过状态。 ## 约束 - 禁止删除已有测试用例只能新增或标注变更。 - 测试数据使用独立测试库禁止触碰生产环境数据。在测试类的 Skill 中建议把“什么情况下禁止执行”写清楚因为测试环境安全和数据隔离是绝对不能踩的线。5.2 学术研究类 Skill学术研究场景需要的是稳定的检索与归纳流程。你可以把文献筛选标准、摘要格式、引用规范写入 Skill然后让模型按照流程输出综述材料。--- name: academic-research description: 当用户要求进行文献调研、论文摘要写作或综述整理时使用。 --- # 学术研究助手 1. 分析研究主题拆解为 3 到 5 个核心检索问题。 2. 针对每个检索问题筛选相关文献优先选择近三年发表的高被引论文。 3. 对文献进行总结每篇文献包含研究问题、方法、结论和局限。 4. 按照引用规范输出参考文献列表。 5. 检查是否存在未标注来源的观点如有则补充来源。 ## 引用规范 - 正文引用使用 [作者, 年份] 形式。 - 参考文献列表按照作者字母顺序排列。 - 严禁虚构文献条目。5.3 PPT 制作类 SkillPPT 类 Skill 不必直接生成二进制文件更常见的是生成结构化内容大纲和文案再由其他工具渲染。你可以把每一页的内容框架、字数限制、视觉建议写进 Skill。--- name: ppt-builder description: 当用户需要制作演示文稿大纲、页面文案或单页内容时使用。 --- # PPT 制作助手 1. 与用户确认演示主题、目标听众、预计时长。 2. 依据“总-分-总”结构生成大纲控制页数在 8 到 15 页。 3. 每页给出标题、要点、详细备注三部分。 4. 要点每页不超过 5 条每条不超过 15 个字。 5. 备注部分补充讲稿素材供演讲者扩展。这一类 Skill 的关键是“结构先行”因为 PPT 的核心是信息层级清晰而不是堆字数。6. 常见问题与排查思路问题现象常见原因解决思路Skill 完全没有被触发description写得过于模糊或触发关键词未命中重新编写description加入任务关键词和场景说明触发了 Skill但输出没有遵循步骤SKILL.md 正文步骤不够具体或与其他指令冲突精简 SKILL.md 正文将细节移入 references并在输出前添加检查清单某些步骤被跳过步骤太长、模型上下文被无关内容干扰控制步骤数量在 5 到 8 步并增加“输出前必须检查”的强制清单Skill 与已有对话指令矛盾对话中的临时要求优先级高于 Skill在 SKILL.md 中明确优先级规则或在对话中说明当前以 Skill 为主Skill 目录未被识别目录结构错误或文件名大小写问题确认SKILL.md文件名大小写正确目录放到了正确的skills根目录下同一场景多个 Skill 冲突多个 Skill 的 description 高度重叠合并同类 Skill或通过when_to_use细化触发边界排查时建议按“是否加载 → 是否执行 → 是否执行完整”的顺序推进。先确认模型是否识别并加载了 Skill再检查执行过程是否按步骤走最后看有没有漏掉关键约束。大多数问题都出在description不够明确或者正文步骤缺少可验证的检查项上。7. 最佳实践与工程建议7.1 设计原则Skill 设计最核心的原则是“高内聚、低耦合”。一个 Skill 只解决一类问题避免把两个完全无关的场景写进同一个 Skill。第二点是用可验证的语言描述输出。与其写“输出高质量代码”不如写“输出必须包含 Props 类型定义与默认值”这样模型有明确的检查依据。第三点是保持触发条件的唯一性。修改 Skill 时先检查是否存在其他 Skill 的description与它重叠。只要触发条件清晰模型的加载准确率就会高很多。7.2 指令质量写 SKILL.md 正文时推荐把“要做的事”和“不要做的事”分开写后者的价值往往更高。例如## 禁止事项 - 禁止删除已有代码中的注释。 - 禁止在未询问用户的情况下修改全局配置。 - 禁止把函数内部变量直接暴露到组件外部。同时可以在关键步骤后加入“输出前检查”清单强制模型在最终回复前完成自检。## 输出前检查 - [ ] 是否遗漏了必填 Props - [ ] 是否存在未使用的外部依赖 - [ ] 示例用法是否可以单独运行这样即使模型生成的代码存在小问题也会在输出前自行纠正。7.3 版本管理与团队协作Skills 本质上是一份带逻辑的文档非常适合用 Git 管理。建议在仓库中单独维护skills目录并且为每个 Skill 维护一个version字段。修改规则时要同步更新版本号并在变更说明中记录改动点。团队协作时可以将 Skill 分为“团队公共 Skill”和“项目私有 Skill”两类。公共 Skill 放在独立仓库私有 Skill 放在项目仓库内。配合 CI 检查 SKILL.md 的基本结构和重复触发条件可以显著降低维护成本。7.4 安全与权限边界当 Skill 涉及数据库、支付、生产环境或其他高权限操作时必须在指令中明确设置安全边界。建议遵循最小权限原则所有破坏性操作删除、批量更新、写操作默认禁止除非用户显式批准。涉及生产环境的数据读写必须插入确认步骤。测试数据与线上数据严格隔离Skill 内部禁止自动连接生产数据库。如果 Skill 需要调用外部服务尽量让 API 密钥通过环境变量注入不要写在 Skill 文档中。8. 总结与学习路线本文围绕 Anthropic 生态中的 Agent Skills 展开从背景、目录结构、SKILL.md 语法、完整实战案例、进阶场景到排错方法都做了系统整理。你应该已经掌握最核心的内容Skill 通过一份结构化的 SKILL.md 文件把任务方法论沉淀下来按需加载避免长上下文带来的混乱并在特定场景中保持稳定的输出质量。接下来可以继续深入的方向有三个。第一是探索更多成熟的 Skill 示例观察社区里优秀 Skill 的指令组织方式与 references 拆分逻辑。第二是动手改造你手头重复度最高的任务比如把常用的代码检查流程、测试用例生成流程、文档整理流程逐步封装成 Skill。第三是关注官方文档与工具更新因为 Skills 的加载机制、项目结构约定和客户端支持程度还会持续演进。如果在实际项目中发现 Skill 在某个具体场景下效果不佳可以先按本文第 6 节的排查清单逐项检查。记住Skill 的价值不是“写一份完美的文件”而是“在反复迭代中把执行标准固定下来”。从一个小场景开始让 Agent 先稳定做好一件事再逐步扩展你的技能库这可能是最靠谱的落地路径。 Agent Skills 落地指南：从 SKILL.md 到前端开发实战
过去这两年AI Agent 的落地方式发生了很明显的变化。早期大家热衷于把所有工具全部接入同一个大模型结果 Agent 的上下文越来越长、指令越来越杂到了真正跑业务的时候反而经常出现“看着什么都会实际什么都做不精确”的情况。最近 Anthropic 生态里频繁出现的Agent Skills这个概念本质上就是在解决这个痛点把某一类任务的处理方法沉淀为可复用的“技能包”让模型在需要的时候按需加载而不是把所有能力都塞在一个会话里。这篇文章我不想只解释概念而是想完整拆解一套 Agent Skills 的落地思路。你会看到它是什么、解决什么问题、目录和文件如何组织、SKILL.md 怎么写以及如何通过真实案例创建一个前端开发辅助 Skill。无论你是刚接触 AI 编程的初学者还是已经在用 Claude Code、OpenCode 这类工具的开发者这篇文章都能提供一套可以直接照做的实操路径。1. 为什么需要 Agent Skills1.1 从“全会”到“精专”的转变先回忆一下我们在大模型里使用知识库或者 Prompt 的常规方式把所有要求写在一个长长的系统提示词里把相关文档、示例、注意事项全部堆进去。这种方式对小任务有效但一旦任务类型变多问题就来了。举个例子一个开发助手既要会写前端组件又要懂 Python 数据处理还要能输出 PPT 大纲。如果把这三类能力的所有细节一次性塞进上下文模型的注意力会被分散而且每轮对话都会重复消耗大量 Token。更关键的是当你调整某一类任务的执行规则时可能会影响到另外两类任务的输出质量。Agent Skills 的思路完全不同。它把“能力”拆成独立的单元一个 Skill 只负责一类任务。每个 Skill 是一个目录包含一份 SKILL.md 和若干辅助文档。系统或用户根据当前任务自动选择需要加载的 Skill。未命中的 Skill 不会占用上下文。这种“按需加载”的设计让 Agent 在保持通用能力的同时也能在特定任务上做到更专业。1.2 Skills 与 Plugins、MCP 的区别很多朋友容易把 Skills 和插件、MCP 混淆这里先做一个简单区分名称核心作用典型例子Plugin / 插件为应用扩展一组预设功能入口浏览器插件、IDE 插件MCP Server为模型提供标准化的外部数据/工具访问通道数据库 MCP、GitHub MCPAgent Skill为模型提供一套任务执行的方法论与领域知识前端组件编写 Skill、PPT 制作 Skill可以这样理解MCP 侧重“你能调用什么外部能力”Skills 侧重“你应该如何把这件事做对”。实际使用中两者并不冲突一个 Skill 内部完全可以依赖某个 MCP Server 获取数据但它给模型的核心价值是那套经过验证的执行流程、检查清单和避坑指南。1.3 适用场景从社区里目前比较热门的 Skills 案例来看比较典型的场景有前端开发类 Skill统一组件规范、样式方案、代码风格生成 Vue/React 组件时自动遵守项目约定。学术研究类 Skill从论文检索到文献综述输出的完整流程包括摘要格式、引用规范。PPT 制作类 Skill输出结构大纲、页面文案、配图建议甚至协作生成一份可直接导入的 Markdown 大纲。测试类 Skill在测试环境自动生成用例、执行断言、整理缺陷报告尤其适合对测试流程有明确规范的项目。数据清洗类 Skill统一缺失值处理、异常值检测、字段类型转换等数据处理规则。无论哪种场景它们背后都有一个共同特征任务有相对稳定的方法论且我们希望每次执行结果都保持一致。这正是 Skills 发挥价值的地方。2. 环境准备与版本说明2.1 你需要准备什么在开始创建 Skill 之前你需要先确认自己当前的运行环境。根据官方生态和社区实践Agent Skills 主要在支持 Anthropic Claude 模型的应用中使用比如 Claude 官方客户端、Claude Code 命令行工具以及部分支持 Skills 标准的第三方 Agent 工具如 OpenCode。环境准备清单大致如下工具用途Claude 账号访问模型能力部分功能需要订阅支持Claude Code 或支持 Skills 的 Agent 客户端加载和执行 Skill文本编辑器编写 SKILL.md 与辅助文档Git可选对 Skill 做版本管理方便复用和回滚关于版本我这里给一个比较稳妥的说明Skills 的目录约定和加载机制在不同客户端中可能存在差异建议你以官方文档的最新说明为准。下面的示例我会采用社区目前较为通用的结构来演示核心是让你掌握设计思路而不是死记某个版本号。2.2 Skills 的目录结构约定一个标准的 Skill 通常放在项目的skills目录下结构类似这样skills/ └── frontend-component/ ├── SKILL.md ├── references/ │ ├── component-style-guide.md │ └── ui-library.md └── procedures/ └── create-component-check.mdSKILL.md是 Skill 的核心文件包含元信息和执行指令。references/用于存放参考文档详细展开知识细节。procedures/用于存放流程检查清单等辅助文件。其中SKILL.md是必须的其他目录可以根据需要灵活组织。如果你的 Skill 比较简单只放一个SKILL.md也完全可以运行。3. 核心原理拆解SKILL.md 的结构与写法3.1 一份最简 SKILL.md先来看一个最小可用的示例--- name: markdown-cleaner description: 清理 Markdown 文档中的多余格式输出符合团队规范的精简版本。 --- # Markdown Cleaner 当你需要对 Markdown 文档进行格式清理时请遵循以下步骤 1. 检测文档内是否包含非正文内容如调试信息、临时注释。 2. 删除连续空行保留单个空行作为段落分隔。 3. 统一标题层级一级标题只能出现一次其余从二级开始。 4. 将列表统一为无序列表风格去除多余嵌套。 5. 输出清理后的完整文档并简要说明修改点。 ## 禁止事项 - 不要修改正文中的代码块内容。 - 不要改变原有语义只做格式层面的清理。这个文件很短但它已经具备了一个 Skill 的完整骨架元信息frontmatter加正文指令。模型通过description字段判断“什么情况下应该加载这个 Skill”一旦加载正文中的步骤就会被严格遵循。3.2 元信息字段详解在---包裹的 frontmatter 中最常见的是四个字段字段作用建议nameSkill 唯一名称使用小写字母和短横线如frontend-componentdescription描述这个 Skill 的作用与触发场景要写清楚“何时用”而不是“是什么”when_to_use进一步说明触发条件可选但推荐补充version版本号可选方便做版本管理description是关键。模型通常会先阅读这个字段来决定是否调用 Skill所以不要写得太笼统。比如“帮助写前端代码”就过于模糊应该改成“当用户要求生成或修改 Vue/React 组件需要遵循项目内组件规范时使用”。3.3 正文指令的写法正文部分是真正影响模型行为的内容建议采用“步骤 约束 示例”的结构。第一步是给流程。把任务拆成 3 到 8 个清晰步骤并且使用可执行的动词分析、提取、生成、检查、输出。第二步是加约束。明确告诉模型“不要做什么”这往往比“要做什么”更能控制输出质量。第三步是给示例。在包含较多格式要求的场景里提供一段输入输出对照能显著提升稳定性。下面是一份典型流程指令的片段## 执行流程 1. 分析用户给出的组件需求提取组件名称、Props 接口、事件接口。 2. 根据 references/component-style-guide.md 中的风格约定生成组件代码。 3. 生成示例用法并标出必须传入的 Props。 4. 检查代码中是否出现硬编码样式如有则替换为设计变量。 5. 输出组件文件内容与一个最小可运行示例。3.4 辅助资源文件的作用当 Skill 包含大量知识细节时不应该把全部内容塞进 SKILL.md否则上下文负担会变大。推荐的做法是把大段知识放到references/下然后在 SKILL.md 中给出明确的引用提示。例如前端开发 Skill 的references/component-style-guide.md里可以写# 组件风格指南 ## 组件结构 - 每个组件必须包含 props 类型定义。 - 禁止在组件内部直接调用全局状态。 - 样式变量统一从设计系统 import。然后在 SKILL.md 的对应步骤中写明2. 参照 references/component-style-guide.md 中的组件结构要求逐项检查生成结果。这样可以在不增加主指令复杂度的前提下保留完整的领域知识。4. 完整实战创建一个前端开发辅助 Skill下面我们一步一步创建一个可以用于前端组件生成与检查的 Skill。我会把整个流程拆成需求分析、目录创建、文件编写、加载验证四个阶段。4.1 需求分析假设你所在团队使用 Vue 3 TypeScript组件库是 Element Plus。你希望 Agent 在生成组件时自动遵守以下规则使用script setup langts语法。所有 Props 必须有类型定义和默认值。组件内不允许直接操作 DOM必须通过 ref 和生命周期函数完成。样式统一使用 scoped并且颜色值从主题变量中读取。生成组件后必须附带一个最小示例。这些规则如果每次都写在对话里不仅麻烦而且容易遗漏。我们可以把它们封装成一个 Skill。4.2 创建目录结构在项目根目录下创建如下结构skills/ └── vue-component/ ├── SKILL.md └── references/ └── vue-style-guide.md命令可以这样执行mkdir -p skills/vue-component/references4.3 编写 SKILL.md文件路径skills/vue-component/SKILL.md--- name: vue-component description: 当用户要求生成、检查或修改 Vue 3 组件且项目使用 TypeScript 和 Element Plus 时使用。遵循组件规范并输出可复用的结构。 when_to_use: 检测到 Vue 3、TypeScript、Element Plus、组件开发等关键词时使用。 version: 1.0.0 --- # Vue 3 组件开发助手 本 Skill 用于在 Vue 3 TypeScript Element Plus 项目环境中创建高质量、可维护的组件。 ## 执行流程 1. 分析用户需求明确组件用途、Props 接口、事件接口和插槽需求。 2. 参考 references/vue-style-guide.md 中的规范逐条核对待生成代码。 3. 生成组件源码文件使用 script setup langts 语法。 4. 生成组件示例用法至少包含一个必须传递的 Props 场景。 5. 输出前检查以下清单 - [ ] 是否缺少 Props 类型定义 - [ ] 是否包含默认值 - [ ] 是否存在 DOM 直接访问 - [ ] 样式颜色是否使用了变量 - [ ] 是否导出了组件所需类型 ## 关键约束 - 禁止使用 Options API。 - 禁止编写无法通过 TypeScript 类型检查的代码。 - 禁止将样式写成非 scoped 全局样式。 - 事件命名必须遵循 kebab-case并以 on 前缀导出。 - 当用户未明确指定样式方案时默认使用 Element Plus 现有的布局和组件结构。 ## 输出格式 完成组件后按以下结构输出 ### 组件代码 此处放置完整组件源码 ### 示例用法 包含组件引入、注册与使用的示例 ### 设计说明 简要说明组件设计思路以及为什么做出当前的关键决策4.4 编写辅助参考文档文件路径skills/vue-component/references/vue-style-guide.md# Vue 3 组件风格指南 ## 通用要求 - 使用 script setup langts 组合式 API 语法。 - 组件名称使用 PascalCase文件名使用 kebab-case。 - Props 使用 withDefaults 与 defineProps 定义明确类型与默认值。 - 事件使用 defineEmits 声明自定义事件名使用 kebab-case。 ## 状态管理 - 组件内部状态使用 ref 或 reactive。 - 禁止直接修改传入的 Props。 - 视图更新需要异步操作时使用 computed 或监听器。 ## DOM 操作 - 禁止在组件中直接使用 document.querySelector 等方式操作 DOM。 - 需要访问元素时使用 ref 模板引用。 - DOM 副作用应在 onMounted 或 watch 回调中处理并在 onUnmounted 中清理。 ## 样式规范 - 所有样式添加 scoped 属性。 - 颜色、间距、字体使用主题变量。 - 禁止使用 !important特殊情况需在代码审查中说明。这个文件把规则细化供模型在生成组件时检索。SKILL.md 中只保留触发条件、执行流程和输出格式避免主指令文档过长。4.5 在 Agent 客户端中加载 Skill不同工具加载 Skill 的方式略有差异。如果你使用 Claude Code 或者支持 Skills 的 Agent 工具通常只需要把skills/目录放在项目根目录然后在对话中描述需求即可。例如你可以这样发起请求请生成一个用户信息展示组件。它需要接收用户昵称、头像 URL、简介文本三个 Props并在卡片中展示。如果 Agent 能够正确识别并加载 Skill它的回答通常会遵循你定义的输出结构并自动参考vue-style-guide.md中的规范。下面是我在测试中得到的一种较理想输出形态已根据 vue-component Skill 的组件规范生成组件以下是完整代码、示例用法与设计说明。 ### 组件代码 此处为完整的 Vue 组件代码包含 SFC 结构、script setup、类型定义、模板 ### 示例用法 此处为组件在父组件中引入、注册和使用的示例 ### 设计说明 本组件采用 scoped 样式与主题变量确保样式隔离Props 提供默认值降低调用成本。如果工具支持 Skill 的可视化管理界面你也可以在界面中手动选择 Skill 或者查看当前加载了哪些 Skill。4.6 验证 Skill 是否生效判断 Skill 是否生效可以看三点输出中是否出现了你定义的专属结构比如“示例用法”“设计说明”这样的固定小节。代码是否符合参考文档中的硬性规则比如是否使用script setup langts。当你的请求里同时包含其他无关信息时Agent 是否仍然稳定执行 Skill 流程。只要这些点符合预期就说明 Skill 加载成功并正在发挥作用。5. 进阶设计不同类型 Skill 的编写要点5.1 测试应用类 Skill测试类 Skill 的核心价值是统一测试设计思路。比如一个用于接口测试的 Skill可以在SKILL.md中定义用例设计步骤、断言规范和数据生成规则。--- name: api-test description: 当需要为 REST API 编写测试用例、执行测试断言或生成测试报告时使用。 --- # API 测试助手 1. 分析接口的请求方法、路径、参数、鉴权方式。 2. 列出正常路径与异常路径用例异常覆盖缺少参数、错误类型、越权访问。 3. 生成 pytest requests 风格的测试代码。 4. 断言必须验证响应状态码、关键业务字段和部分响应时间。 5. 输出测试报告模板包含用例名称、执行时间、通过状态。 ## 约束 - 禁止删除已有测试用例只能新增或标注变更。 - 测试数据使用独立测试库禁止触碰生产环境数据。在测试类的 Skill 中建议把“什么情况下禁止执行”写清楚因为测试环境安全和数据隔离是绝对不能踩的线。5.2 学术研究类 Skill学术研究场景需要的是稳定的检索与归纳流程。你可以把文献筛选标准、摘要格式、引用规范写入 Skill然后让模型按照流程输出综述材料。--- name: academic-research description: 当用户要求进行文献调研、论文摘要写作或综述整理时使用。 --- # 学术研究助手 1. 分析研究主题拆解为 3 到 5 个核心检索问题。 2. 针对每个检索问题筛选相关文献优先选择近三年发表的高被引论文。 3. 对文献进行总结每篇文献包含研究问题、方法、结论和局限。 4. 按照引用规范输出参考文献列表。 5. 检查是否存在未标注来源的观点如有则补充来源。 ## 引用规范 - 正文引用使用 [作者, 年份] 形式。 - 参考文献列表按照作者字母顺序排列。 - 严禁虚构文献条目。5.3 PPT 制作类 SkillPPT 类 Skill 不必直接生成二进制文件更常见的是生成结构化内容大纲和文案再由其他工具渲染。你可以把每一页的内容框架、字数限制、视觉建议写进 Skill。--- name: ppt-builder description: 当用户需要制作演示文稿大纲、页面文案或单页内容时使用。 --- # PPT 制作助手 1. 与用户确认演示主题、目标听众、预计时长。 2. 依据“总-分-总”结构生成大纲控制页数在 8 到 15 页。 3. 每页给出标题、要点、详细备注三部分。 4. 要点每页不超过 5 条每条不超过 15 个字。 5. 备注部分补充讲稿素材供演讲者扩展。这一类 Skill 的关键是“结构先行”因为 PPT 的核心是信息层级清晰而不是堆字数。6. 常见问题与排查思路问题现象常见原因解决思路Skill 完全没有被触发description写得过于模糊或触发关键词未命中重新编写description加入任务关键词和场景说明触发了 Skill但输出没有遵循步骤SKILL.md 正文步骤不够具体或与其他指令冲突精简 SKILL.md 正文将细节移入 references并在输出前添加检查清单某些步骤被跳过步骤太长、模型上下文被无关内容干扰控制步骤数量在 5 到 8 步并增加“输出前必须检查”的强制清单Skill 与已有对话指令矛盾对话中的临时要求优先级高于 Skill在 SKILL.md 中明确优先级规则或在对话中说明当前以 Skill 为主Skill 目录未被识别目录结构错误或文件名大小写问题确认SKILL.md文件名大小写正确目录放到了正确的skills根目录下同一场景多个 Skill 冲突多个 Skill 的 description 高度重叠合并同类 Skill或通过when_to_use细化触发边界排查时建议按“是否加载 → 是否执行 → 是否执行完整”的顺序推进。先确认模型是否识别并加载了 Skill再检查执行过程是否按步骤走最后看有没有漏掉关键约束。大多数问题都出在description不够明确或者正文步骤缺少可验证的检查项上。7. 最佳实践与工程建议7.1 设计原则Skill 设计最核心的原则是“高内聚、低耦合”。一个 Skill 只解决一类问题避免把两个完全无关的场景写进同一个 Skill。第二点是用可验证的语言描述输出。与其写“输出高质量代码”不如写“输出必须包含 Props 类型定义与默认值”这样模型有明确的检查依据。第三点是保持触发条件的唯一性。修改 Skill 时先检查是否存在其他 Skill 的description与它重叠。只要触发条件清晰模型的加载准确率就会高很多。7.2 指令质量写 SKILL.md 正文时推荐把“要做的事”和“不要做的事”分开写后者的价值往往更高。例如## 禁止事项 - 禁止删除已有代码中的注释。 - 禁止在未询问用户的情况下修改全局配置。 - 禁止把函数内部变量直接暴露到组件外部。同时可以在关键步骤后加入“输出前检查”清单强制模型在最终回复前完成自检。## 输出前检查 - [ ] 是否遗漏了必填 Props - [ ] 是否存在未使用的外部依赖 - [ ] 示例用法是否可以单独运行这样即使模型生成的代码存在小问题也会在输出前自行纠正。7.3 版本管理与团队协作Skills 本质上是一份带逻辑的文档非常适合用 Git 管理。建议在仓库中单独维护skills目录并且为每个 Skill 维护一个version字段。修改规则时要同步更新版本号并在变更说明中记录改动点。团队协作时可以将 Skill 分为“团队公共 Skill”和“项目私有 Skill”两类。公共 Skill 放在独立仓库私有 Skill 放在项目仓库内。配合 CI 检查 SKILL.md 的基本结构和重复触发条件可以显著降低维护成本。7.4 安全与权限边界当 Skill 涉及数据库、支付、生产环境或其他高权限操作时必须在指令中明确设置安全边界。建议遵循最小权限原则所有破坏性操作删除、批量更新、写操作默认禁止除非用户显式批准。涉及生产环境的数据读写必须插入确认步骤。测试数据与线上数据严格隔离Skill 内部禁止自动连接生产数据库。如果 Skill 需要调用外部服务尽量让 API 密钥通过环境变量注入不要写在 Skill 文档中。8. 总结与学习路线本文围绕 Anthropic 生态中的 Agent Skills 展开从背景、目录结构、SKILL.md 语法、完整实战案例、进阶场景到排错方法都做了系统整理。你应该已经掌握最核心的内容Skill 通过一份结构化的 SKILL.md 文件把任务方法论沉淀下来按需加载避免长上下文带来的混乱并在特定场景中保持稳定的输出质量。接下来可以继续深入的方向有三个。第一是探索更多成熟的 Skill 示例观察社区里优秀 Skill 的指令组织方式与 references 拆分逻辑。第二是动手改造你手头重复度最高的任务比如把常用的代码检查流程、测试用例生成流程、文档整理流程逐步封装成 Skill。第三是关注官方文档与工具更新因为 Skills 的加载机制、项目结构约定和客户端支持程度还会持续演进。如果在实际项目中发现 Skill 在某个具体场景下效果不佳可以先按本文第 6 节的排查清单逐项检查。记住Skill 的价值不是“写一份完美的文件”而是“在反复迭代中把执行标准固定下来”。从一个小场景开始让 Agent 先稳定做好一件事再逐步扩展你的技能库这可能是最靠谱的落地路径。