如何创建好的 Agent Skill

如何创建好的 Agent Skill 如何创建好的 Agent Skill Modified January 7 • 不需要大量领域特定知识 不需要加载触发机制 ——43 行内容一次性加载，无需分层。 类型 2：工具操作型 代表 ：docx（197 行）、xlsx、pptx、pdf 结构特点 ： • 决策树快速路由到正确工作流 • MANDATORY 强制加载指令 • 详细的代码示例 • 大量 reference 文档（每个 300 600 行） • 低自由度，精确步骤 赋能 ： 把一个通用的、可能会把 Word 文档写坏的 Agent，变成一个 能精确操作复杂文件格式的专家 Agent 。 这个 Agent 知道：创建新文档用 docx js，编辑现有文档用 OOXML 直接操作，处理修订痕迹用 redlining 工作流。它知道每种操作的具体步骤，不会犯破坏文件的错误。 适用场景 ： • 文件格式操作 • 操作容易出错，需要精确指导 • 需要大量领域特定知识 需要精心设计的加载触发 ——决策树根据任务类型路由，每个工作流开始前强制加载对应文档。 类型 3：流程导向型 代表 ：mcp builder（237 行） 结构特点 ： • 清晰的多阶段工作流（如四阶段） • 每个阶段有具体的产出和检查点 • reference 按阶段/按选择组织 • 中等自由度 赋能 ： 把一个通用的、可能遗漏关键步骤的 Agent，变成一个 能系统性构建复杂项目的工程师 Agent 。 这个 Agent 知道构建 MCP 服务器要经过：研究规划 → 实现 → 测试 → 评估四个阶段。每个阶段它知道要做什么、产出什么、什么时候可以进入下一阶段。 适用场景 ： • 复杂的多步骤任务 • 需要阶段性检查点 • 有多种技术选择（如 TypeScript vs Python） 需要阶段性加载触发 ——进入每个阶段时加载对应的 reference 文档。 类型 4：哲学+执行型 代表 ：canvas design（130 行）、algorithmic art 结构特点 ： • 两步流程：Philosophy（创建理念）→ Express（执行创作） • 反复强调工艺品质和大师级执行 • 给予创意空间 • reference 是参考示例，非必需 赋能 ： 把一个通用的、输出平庸作品的 Agent，变成一个 有创作哲学的艺术家 Agent 。 这个 Agent 不会直接开始画画。它会先创建一个设计哲学——"Brutalist Joy"或"Chromatic Silence"——然后用这个哲学指导视觉表达。它追求的是"看起来像花了无数小时精心制作"的品质。 适用场景 ： • 创意生成任务 • 需要独特性和原创性 • 品质比效率更重要 加载触发可选 ——核心工作流自包含在 SKILL.md，reference 只是参考示例。 类型 5：导航型 代表 ：internal comms（33 行） 结构特点 ： • SKILL.md 极简，只是路由器 • 详细内容在 examples/ 子目录中 • 快速识别场景，路由到对应文件 结构示例 ： Code block Plain Text Copy How to use this skill 1. Identify the communication type from the request 2. Load the appropriate guideline file : 进度/计划/问题更新 公司通讯 常见问题回答 其他类型 3. Follow the specific instructions in that file 赋能 ： 把一个通用的 Agent，变成一个 能处理多种场景的专业写手 Agent 。 这个 Agent 收到"帮我写周报"时，会识别这是 3P 更新，然后加载对应的指南，按照公司的格式和风格来写。 适用场景 ： • 有多个明确的子场景 • 每个子场景有独立的详细指南 • 不需要同时加载所有场景 需要简单路由触发 ——识别场景类型，加载对应文件。 类型选择总结 你的任务特点 推荐类型 行数参考 需要加载触发 需要品味和创意 极简心智型 30 50 否 需要独特性和工艺品质 哲学+执行型 100 150 可选 有多个场景需要分发 导航型 20 50 是（简单） 复杂多步骤项目 流程导向型 150 300 是 精确操作特定格式 工具操作型 200 500 是（精心） 五、加载触发机制：最被忽视的设计 这一节只对 有 reference 目录的中等/复杂 Skill 重要。如果你的 Skill 是简单的单文件（如 frontend design），可以跳过。 5.1 问题 Skill 设计的核心理念是 按需加载上下文 ——把详细知识存在 reference 文件里，需要时才加载，保持 context window 精简。 但现实是：Agent 经常不读该读的文档，或者读太多不该读的文档。 5.2 解决方案 技巧 1：MANDATORY 规则命令语法 在工作流步骤中嵌入强制加载指令： Code block Plain Text Copy 创建新文档 MANDATORY READ ENTIRE FILE ：在继续之前，你必须完整阅读 （约 500 行）。 绝对不要设置任何行数限制。 关键词："MANDATORY"、"必须"、"绝对不要"——不留模糊空间。 技巧 2：条件触发路由表 Code block Plain Text Copy | 任务类型 | 必须加载 | 不要加载 | | | | | | 创建新文档 | | , | | 简单编辑 | | , | | 修订痕迹 | | | 同时告诉 Agent 该读什么、不该读什么——解决"不读"和"读太多"两个问题。 技巧 3：场景检测 Code block Plain Text Copy 场景 A：新项目 用户说："从头构建 X"、"创建一个新的..." 必须加载 ： 场景 B：修复 Bug 用户说："X 坏了"、"修复这个 bug" 必须加载 ： 基于用户输入的关键词自动路由。 六、设计检查清单 写完一个 Skill，过一遍这个清单： Code block Plain Text Copy 基础规范 [ ] 有 YAML frontmatter，包含 name 和 description [ ] description 包含"做什么"和"什么时候用" [ ] SKILL.md < 500 行 内容质量 [ ] 没有解释 Claude 已知的基础概念 [ ] 没有机械的 Step 1, 2, 3 [ ] 有明确的反模式清单（NEVER list） [ ] 有决策树或选择指导（如果有多种路径） [ ] 有常见陷阱和边缘情况 加载机制（仅有 reference 的 Skill） [ ] 每个 reference 有明确的加载触发条件 [ ] 触发条件嵌入在工作流步骤中 [ ] 有防止过度加载的机制 自由度 [ ] 创意任务 → 高自由度（原则而非步骤） [ ] 脆弱操作 → 低自由度（精确脚本） 七、评估你的 Skill 怎么知道你写的 Skill 好不好？ 我们在 shareAI skills 仓库创建了一个 skill judge Skill，专门用于多维度评估 Agent Skill 的设计质量。 评估维度 维度 分值 检查内容 规范合规 20 frontmatter 格式、description 完整性 渐进式披露 20 三层加载机制、MANDATORY 触发器 上下文效率 15 不解释基础概念、不过度冗长 自由度校准 15 创意任务高自由度、脆弱操作低自由度 模式识别 15 是否遵循 5 种官方模式之一 实用可用性 15 决策树、代码示例、边缘情况覆盖 评分标准 • 90 100 ：优秀，生产就绪 • 80 89 ：良好，需要小改进 • 70 79 ：合格，需要改进 • < 70 ：需要重新设计 使用方法 把你的 SKILL.md 内容发给加载了 skill judge 的 Agent，它会给你一份详细的评估报告，包括： • 不需要大量领域特定知识 不需要加载触发机制 ——43 行内容一次性加载，无需分层。 类型 2：工具操作型 代表 ：docx（197 行）、xlsx、pptx、pdf 结构特点 ： • 决策树快速路由到正确工作流 • MANDATORY 强制加载指令 • 详细的代码示例 • 大量 reference 文档（每个 300 600 行） • 低自由度，精确步骤 赋能 ： 把一个通用的、可能会把 Word 文档写坏的 Agent，变成一个 能精确操作复杂文件格式的专家 Agent 。 这个 Agent 知道：创建新文档用 docx js，编辑现有文档用 OOXML 直接操作，处理修订痕迹用 redlining 工作流。它知道每种操作的具体步骤，不会犯破坏文件的错误。 适用场景 ： • 文件格式操作 • 操作容易出错，需要精确指导 • 需要大量领域特定知识 需要精心设计的加载触发 ——决策树根据任务类型路由，每个工作流开始前强制加载对应文档。 类型 3：流程导向型 代表 ：mcp builder（237 行） 结构特点 ： • 清晰的多阶段工作流（如四阶段） • 每个阶段有具体的产出和检查点 • reference 按阶段/按选择组织 • 中等自由度 赋能 ： 把一个通用的、可能遗漏关键步骤的 Agent，变成一个 能系统性构建复杂项目的工程师 Agent 。 这个 Agent 知道构建 MCP 服务器要经过：研究规划 → 实现 → 测试 → 评估四个阶段。每个阶段它知道要做什么、产出什么、什么时候可以进入下一阶段。 适用场景 ： • 复杂的多步骤任务 • 需要阶段性检查点 • 有多种技术选择（如 TypeScript vs Python） 需要阶段性加载触发 ——进入每个阶段时加载对应的 reference 文档。 类型 4：哲学+执行型 代表 ：canvas design（130 行）、algorithmic art 结构特点 ： • 两步流程：Philosophy（创建理念）→ Express（执行创作） • 反复强调工艺品质和大师级执行 • 给予创意空间 • reference 是参考示例，非必需 赋能 ： 把一个通用的、输出平庸作品的 Agent，变成一个 有创作哲学的艺术家 Agent 。 这个 Agent 不会直接开始画画。它会先创建一个设计哲学——"Brutalist Joy"或"Chromatic Silence"——然后用这个哲学指导视觉表达。它追求的是"看起来像花了无数小时精心制作"的品质。 适用场景 ： • 创意生成任务 • 需要独特性和原创性 • 品质比效率更重要 加载触发可选 ——核心工作流自包含在 SKILL.md，reference 只是参考示例。 类型 5：导航型 代表 ：internal comms（33 行） 结构特点 ： • SKILL.md 极简，只是路由器 • 详细内容在 examples/ 子目录中 • 快速识别场景，路由到对应文件 结构示例 ： 赋能 ： 把一个通用的 Agent，变成一个 能处理多种场景的专业写手 Agent 。 这个 Agent 收到"帮我写周报"时，会识别这是 3P 更新，然后加载对应的指南，按照公司的格式和风格来写。 适用场景 ： • 有多个明确的子场景 • 每个子场景有独立的详细指南 • 不需要同时加载所有场景 需要简单路由触发 ——识别场景类型，加载对应文件。 类型选择总结 你的任务特点 推荐类型 行数参考 需要加载触发 需要品味和创意 极简心智型 30 50 否 需要独特性和工艺品质 哲学+执行型 100 150 可选 有多个场景需要分发 导航型 20 50 是（简单） 复杂多步骤项目 流程导向型 150 300 是 精确操作特定格式 工具操作型 200 500 是（精心） 你的任务特点 你的任务特点 推荐类型 推荐类型 行数参考 行数参考 需要加载触发 需要加载触发 需要品味和创意 需要品味和创意 极简心智型 极简心智型 30 50 30 50 否 否 需要独特性和工艺品质 需要独特性和工艺品质 哲学+执行型 哲学+执行型 100 150 100 150 可选 可选 有多个场景需要分发 有多个场景需要分发 导航型 导航型 20 50 20 50 是（简单） 是（简单） 复杂多步骤项目 复杂多步骤项目 流程导向型 流程导向型 150 300 150 300 是 是 精确操作特定格式 精确操作特定格式 工具操作型 工具操作型 200 500 200 500 是（精心） 是（精心） 五、加载触发机制：最被忽视的设计 这一节只对 有 reference 目录的中等/复杂 Skill 重要。如果你的 Skill 是简单的单文件（如 frontend design），可以跳过。 5.1 问题 5.1 问题 Skill 设计的核心理念是 按需加载上下文 ——把详细知识存在 reference 文件里，需要时才加载，保持 context window 精简。 但现实是：Agent 经常不读该读的文档，或者读太多不该读的文档。 5.2 解决方案 5.2 解决方案 技巧 1：MANDATORY 规则命令语法 在工作流步骤中嵌入强制加载指令： 关键词："MANDATORY"、"必须"、"绝对不要"——不留模糊空间。 技巧 2：条件触发路由表 同时告诉 Agent 该读什么、不该读什么——解决"不读"和"读太多"两个问题。 技巧 3：场景检测 基于用户输入的关键词自动路由。 六、设计检查清单 写完一个 Skill，过一遍这个清单： 七、评估你的 Skill 怎么知道你写的 Skill 好不好？ 我们在 shareAI skills 仓库创建了一个 skill judge Skill，专门用于多维度评估 Agent Skill 的设计质量。 评估维度 评估维度 维度 分值 检查内容 规范合规 20 frontmatter 格式、description 完整性 渐进式披露 20 三层加载机制、MANDATORY 触发器 上下文效率 15 不解释基础概念、不过度冗长 自由度校准 15 创意任务高自由度、脆弱操作低自由度 模式识别 15 是否遵循 5 种官方模式之一 实用可用性 15 决策树、代码示例、边缘情况覆盖 维度 维度 分值 分值 检查内容 检查内容 规范合规 规范合规 20 20 frontmatter 格式、description 完整性 frontmatter 格式、description 完整性 渐进式披露 渐进式披露 20 20 三层加载机制、MANDATORY 触发器 三层加载机制、MANDATORY 触发器 上下文效率 上下文效率 15 15 不解释基础概念、不过度冗长 不解释基础概念、不过度冗长 自由度校准 自由度校准 15 15 创意任务高自由度、脆弱操作低自由度 创意任务高自由度、脆弱操作低自由度 模式识别 模式识别 15 15 是否遵循 5 种官方模式之一 是否遵循 5 种官方模式之一 实用可用性 实用可用性 15 15 决策树、代码示例、边缘情况覆盖 决策树、代码示例、边缘情况覆盖 评分标准 • 90 100 ：优秀，生产就绪 • 80 89 ：良好，需要小改进 • 70 79 ：合格，需要改进 • < 70 ：需要重新设计 使用方法 把你的 SKILL.md 内容发给加载了 skill judge 的 Agent，它会给你一份详细的评估报告，包括： • 各维度得分 • 具体问题指出 • 改进建议 仓库地址： https://github.com/shareAI lab/shareAI skills 结语 好的 Agent Skill 不是教程。 好的 Agent Skill 是专家知识的外化形式。 它把一个领域专家的思维方式、决策原则、反模式直觉、边缘情况经验，压缩成一个可加载的 Markdown 文件。 当 Agent 加载这个文件时，它不是在"学习操作步骤"——它是在 继承一种专家思维 。 写 Skill 之前，问自己： • 这个领域的顶级专家是如何思考的？ • 他们做决策的核心原则是什么？ • 他们踩过什么坑？ • 他们绝对不会做什么？ • 什么知识是模型不知道但必须知道的？ 想清楚这些，再动手写。 记住那个核心公式： 好 Skill = 高压缩比 + 高信息密度。 垃圾 Skill = 压缩了 Claude 已经知道的东西。 工具让模型能做事。技能让模型知道怎么做。 这就是 Agent Skill 的全部奥秘——把专家大脑压缩成可加载的 Markdown 文件，让通用模型在需要时变成领域专家。不需要训练，不需要微调，编辑文本，即时生效。 相关链接 ： shareAI skills 仓库：https://github.com/shareAI lab/shareAI skills skill judge 评估工具：https://github.com/shareAI lab/shareAI skills/tree/main/skills/skill judge Kode（开源版 Claude Code）：https://github.com/shareAI lab/Kode 🔗 原文链接： https://mp.weixin.qq.com/s/hcqMHkTU... https://mp.weixin.qq.com/s/hcqMHkTU... 原创 飞鸟白菜 shareAI2026年1月4日 07:44 浙江 Skill + Agent + Input = 自动化🌍 这篇文章不是泛泛而谈教你怎么给Agent创建Skill。 我们分析了 Anthropic 官方的 Skill 规范文档，精细阅读分析了 17 个官方 Skill 示例的源码，提炼出判断 Skill 好坏的核心标准，并追溯每一条标准的来源和深层逻辑。 如果你想创建真正有价值的 Agent Skill，这篇文章会告诉你：什么是好的、什么是坏的、为什么，以及怎么做。 一、首先理解：Skill 到底是什么 1.1 一个根本性的误解 1.1 一个根本性的误解 当大多数人听到"Agent Skill"时，脑子里想的是： 教 AI 如何做某件事 。 这是根本性的误解。 Claude 已经知道如何写代码。它知道如何调试。它知道如何设计系统架构。它知道什么是 PDF、什么是 Word 文档、什么是 API。 这些，不需要你教。 那 Skill 到底是什么？ 1.2 Skill 是知识外化机制 1.2 Skill 是知识外化机制 传统 AI 的知识锁在模型参数里。想让模型学会新技能？ Skill 改变了这一切： 这就像给 base model 外挂了一个可热插拔的 LoRA 适配器，但完全不需要训练。你用自然语言编辑一个 Markdown 文件，模型的行为就改变了。 这是从"训练 AI"到"教育 AI"的范式转变。 理解这一点，你才能理解为什么大多数 Skill 是垃圾——因为它们"教"的是 AI 已经知道的东西。 1.3 Tool vs Skill：一个关键区分 1.3 Tool vs Skill：一个关键区分 很多人把这两个概念混淆了。让我们澄清： 概念 本质 作用 例子 Tool（工具） 模型能 做 什么 执行动作 bash、read file、write file、WebSearch Skill（技能） 模型 知道怎么做 指导决策 PDF 处理、MCP 构建、前端设计、代码审查 概念 概念 本质 本质 作用 作用 例子 例子 Tool（工具） Tool（工具） 模型能 做 什么 模型能 做 什么 执行动作 执行动作 bash、read file、write file、WebSearch bash、read file、write file、WebSearch Skill（技能） Skill（技能） 模型 知道怎么做 模型 知道怎么做 指导决策 指导决策 PDF 处理、MCP 构建、前端设计、代码审查 PDF 处理、MCP 构建、前端设计、代码审查 工具是能力的边界——没有 bash 工具，模型无法执行命令。 技能是知识的注入——没有前端设计 Skill，模型写出的 UI 千篇一律。 核心公式 ： 同一个 Claude 模型，加载不同的 Skill，就变成不同的专家。这就是 Skill 的价值所在。 换一种说法： 模型能力是基座，Skill 质量决定了这个基座能发挥到什么程度。一个优秀的 Skill，能让通用 Agent 在特定领域的表现超越没有 Skill 加持的更强模型。 二、判断标准：从哪里来，为什么重要 我们提炼出 6 条判断 Skill 好坏的核心标准。每一条都有明确的来源，要么来自官方规范，要么来自对官方示例的系统分析，要么来自实践中发现的关键问题。 标准 1：Token 效率——每个段落是否值得它的开销 标准 1：Token 效率——每个段落是否值得它的开销 来源 ：Anthropic 官方 skill creator 规范 官方原话： Concise is Key. The context window is a public good. Skills share the context window with everything else Claude needs: system prompt, conversation history, other Skills' metadata, and the actual user request. Default assumption: Claude is already very smart. Only add context Claude doesn't already have. Challenge each piece of information: "Does Claude really need this explanation?" and "Does this paragraph justify its token cost?" 深层逻辑 ： Context window 是公共资源。一个 Skill 占用的 token，会挤压其他内容的空间——系统提示、对话历史、其他 Skill 的元数据、用户的实际请求。 当你写一段"什么是 PDF"的解释时，你在浪费这个公共资源。Claude 已经知道什么是 PDF。这 100 个 token 本可以用来存放更有价值的信息。 如何判断 ： 对 Skill 中的每个段落，问三个问题： 1. Claude 真的不知道这个吗？ 2. 删掉它会影响任务完成吗？ 3. 这 100 个 token 能换来什么价值？ 如果答案是"Claude 已经知道"或"删掉无所谓"，删掉。 核心公式 ： 这个公式是判断 Skill 价值的根本标准。你可以把 Skill 理解为 专家大脑的压缩文件 ——把一个设计师 10 年的审美积累压缩成 43 行，把一个文档专家的操作经验压缩成 200 行决策树。压缩的必须是 Claude 没有的东西，否则就是垃圾压缩。 标准 2：心智模型 vs 机械步骤——传递的是什么 标准 2：心智模型 vs 机械步骤——传递的是什么 来源 ：分析 17 个官方 Skill 示例，特别是 frontend design、canvas design 发现 ： 官方最精简的 Skill——frontend design，只有 43 行。但它极其有效。 它没有教 Claude 如何写 CSS。它没有解释什么是 flexbox。它没有列出 Step 1、Step 2、Step 3。 它做的事情是： 它激活的是 设计师的思维方式 ——在动手写代码之前，先想清楚几个关键问题。这是专家和新手的本质区别。 深层逻辑 ： 专家和新手的差异不在于"会不会操作"，而在于"如何思考问题"。一个资深设计师和一个初学者，都会写 CSS。但设计师在写第一行代码之前，脑子里已经有了清晰的审美方向、用户场景、差异化定位。 好的 Skill 传递的是这种思维方式，而不是机械的操作步骤。 对比 ： 维度 平庸 Skill 优秀 Skill 内容 Step 1, Step 2, Step 3 思考框架、决策原则 假设 Agent 不会做 Agent 会做，但不知道怎么想 效果 Agent 照本宣科 Agent 像专家一样思考 维度 维度 平庸 Skill 平庸 Skill 优秀 Skill 优秀 Skill 内容 内容 Step 1, Step 2, Step 3 Step 1, Step 2, Step 3 思考框架、决策原则 思考框架、决策原则 假设 假设 Agent 不会做 Agent 不会做 Agent 会做，但不知道怎么想 Agent 会做，但不知道怎么想 效果 效果 Agent 照本宣科 Agent 照本宣科 Agent 像专家一样思考 Agent 像专家一样思考 标准 3：反模式清单——明确什么不能做 标准 3：反模式清单——明确什么不能做 来源 ：分析官方 Skill 的普遍特征 发现 ： 几乎所有优秀的官方 Skill 都包含明确的"NEVER"清单。 frontend design： canvas design： 深层逻辑 ： 专家知识的一半是"知道什么能做"，另一半是"知道什么绝对不能做"。 一个资深设计师看到紫色渐变配白色背景，会本能地皱眉——"太 AI 感了"。这种"什么不能做"的直觉，是踩过无数坑之后形成的。 Claude 没有踩过这些坑。它不知道 Inter 字体已经被用滥了，不知道紫色渐变是 AI 生成内容的标志。 好的 Skill 要把这些"绝对不能做"的事情明确写出来。这比"应该做什么"更有价值，因为它划定了品质的底线。 如何判断 ： 你的 Skill 里有没有明确的"NEVER"清单？有没有告诉 Agent 什么是"垃圾做法"？ 标准 4：Description 触发机制——何时被激活 标准 4：Description 触发机制——何时被激活 来源 ：官方 skill creator 规范 官方原话： This is the primary triggering mechanism for your skill, and helps Claude understand when to use the skill. Include both what the Skill does and specific triggers/contexts for when to use it. Include all "when to use" information here Not in the body. The body is only loaded after triggering. 深层逻辑 ： Skill 的加载分三层： 关键点： description 是唯一始终可见的部分 。Agent 根据 description 决定是否激活这个 Skill。如果 description 太模糊，Skill 就无法在正确的时机被触发。 好的 description ： 特点： • 描述功能（what it does） • 列出触发场景（when to use） • 包含关键词（.docx files, tracked changes） 差的 description ： 问题：太模糊，Agent 不知道什么时候该用它。 标准 5：自由度校准——与任务脆弱性匹配 标准 5：自由度校准——与任务脆弱性匹配 来源 ：分析 docx（低自由度）vs frontend design（高自由度）的设计差异 官方 skill creator 规范： Match the level of specificity to the task's fragility and variability: High freedom (text based instructions) : Use when multiple approaches are valid, decisions depend on context. Medium freedom (pseudocode or scripts with parameters) : Use when a preferred pattern exists, some variation is acceptable. Low freedom (specific scripts, few parameters