AI Agent Claude-Skills-完全构建指南 目录 简介 第一章：基础知识 第二章：规划与设计 第三章：测试与迭代 第四章：分发与共享 第五章：模式与故障排除 第六章：资源与参考 参考 A：快速检查清单 参考 B：YAML Frontmatter 参考 C：完整的 Skill 示例 简介 Skill 是一组指令——打包成一个简单的文件夹——用于教导 Claude 如何处理特定任务或工作流程。Skills 是根据你的特定需求定制 Claude 最强大的方式之一。你无需在每次对话中重复解释自己的偏好、流程和领域知识，Skills 让你只需教导 Claude 一次，便能每次受益。 Skills 在你拥有可重复工作流程时效果最佳：从规范中生成前端设计、使用一致方法论进行研究、按照团队风格指南创建文档，或编排多步骤流程。它们与 Claude 的内置能力（如代码执行和文档创建）协同良好。对于构建 MCP 集成的用户，Skills 提供了另一个强大层级——帮助将原始工具访问转化为可靠、优化的工作流程。 本指南涵盖构建高效 Skills 所需了解的一切内容——从规划与结构到测试与分发。无论你是为自己、团队还是社区构建 Skill，你都将在全文中找到实用模式和真实案例。 你将学到： Skills 结构的技术要求和最佳实践 独立 Skill 和 MCP 增强工作流的模式 我们在不同使用场景中观察到的有效模式 如何测试、迭代和分发你的 Skills 适合人群： 希望 Claude 持续遵循特定工作流程的开发者 希望 Claude 遵循特定工作流程的高级用户 希望在组织中标准化 Claude 工作方式的团队 本指南的两条路径 构建独立 Skills？重点关注「基础知识」、「规划与设计」和第 1-2 类。增强 MCP 集成？「Skills + MCP」章节和第 3 类适合你。两条路径共享相同的技术要求，你可根据使用场景选择相关内容。 你将从本指南中获得什么： 读完本指南后，你将能够在单次会话中构建一个可运行的 Skill。预计使用 skill-creator 构建并测试你的第一个 Skill 约需 15-30 分钟。 让我们开始吧。 第一章：基础知识 什么是 Skill？ Skill 是一个包含以下内容的文件夹： SKILL.md （必须）：带有 YAML frontmatter 的 Markdown 格式指令 scripts/ （可选）：可执行代码（Python、Bash 等） references/ （可选）：按需加载的文档 assets/ （可选）：输出中使用的模板、字体、图标 核心设计原则 递进式披露（Progressive Disclosure） Skills 使用三级系统： 第一级（YAML frontmatter） ：始终加载到 Claude 的系统提示中。提供恰到好处的信息，让 Claude 知道何时应使用每个 Skill，而无需将全部内容加载到上下文中。 第二级（SKILL.md 正文） ：当 Claude 认为该 Skill 与当前任务相关时加载。包含完整的指令和指导。 第三级（链接文件） ：打包在 Skill 目录中的附加文件，Claude 可以按需选择浏览和发现。 这种递进式披露在保持专业能力的同时最大限度地减少了 token 消耗。 可组合性（Composability） Claude 可以同时加载多个 Skills。你的 Skill 应能与其他 Skills 协同工作，而不是假设自己是唯一可用的能力。 可移植性（Portability） Skills 在 Claude.ai、Claude Code 和 API 上的工作方式完全相同。创建一次，即可在所有平台使用，无需修改——前提是运行环境支持 Skill 所需的任何依赖项。 面向 MCP 构建者：Skills + 连接器 💡 在没有 MCP 的情况下构建独立 Skills？跳到「规划与设计」——你随时可以回来查看这部分。 如果你已经有一个可运行的 MCP 服务器，那你已经完成了最难的部分。Skills 是顶层的知识层——捕获你已知的工作流程和最佳实践，让 Claude 能够持续地应用它们。 厨房类比 MCP 提供专业厨房：工具、食材和设备的访问权限。 Skills 提供菜谱：一步步地说明如何创造有价值的成果。 两者结合，让用户无需自己摸索每一个步骤就能完成复杂任务。 两者如何协作 MCP（连接性） Skills（知识） 将 Claude 连接到你的服务（Notion、Asana、Linear 等） 教导 Claude 如何有效使用你的服务 提供实时数据访问和工具调用 捕获工作流程和最佳实践 Claude 能做 什么 Claude 应该怎么做 这对你的 MCP 用户意味着什么 没有 Skills： 用户连接了你的 MCP，但不知道下一步该做什么 支持工单询问"我如何用你的集成做 X" 每次对话从零开始 因为用户每次提示方式不同，结果不一致 用户将问题归咎于你的连接器，而真正的问题是工作流程指导缺失 有了 Skills： 预构建的工作流程在需要时自动激活 一致、可靠的工具使用 每次交互中都嵌入了最佳实践 降低了你的集成的学习曲线 第二章：规划与设计 从使用场景出发 在编写任何代码之前，先确定你的 Skill 应该实现的 2-3 个具体使用场景。 良好的使用场景定义示例： 使用场景：项目冲刺规划 触发条件：用户说"帮我规划这个冲刺"或"创建冲刺任务" 步骤： 1. 从 Linear（通过 MCP）获取当前项目状态 2. 分析团队速度和容量 3. 建议任务优先级 4. 在 Linear 中创建带有适当标签和估算的任务 结果：已规划完成的冲刺，并创建了任务 问自己： 用户想完成什么？ 这需要哪些多步骤工作流程？ 需要哪些工具（内置或 MCP）？ 应该嵌入哪些领域知识或最佳实践？ 常见 Skill 使用场景类别 在 Anthropic，我们观察到三类常见使用场景： 第 1 类：文档与资产创建 用途： 创建一致、高质量的输出，包括文档、演示文稿、应用、设计、代码等。 真实案例： frontend-design skill（另见用于 docx、pptx、xlsx 和 ppt 的 Skills） "创建具有高设计质量的独特、生产级前端界面。在构建 Web 组件、页面、artifact、海报或应用时使用。" 核心技巧： 内嵌样式指南和品牌标准 一致输出的模板结构 定稿前的质量检查清单 无需外部工具——使用 Claude 的内置能力 第 2 类：工作流程自动化 用途： 受益于一致方法论的多步骤流程，包括跨多个 MCP 服务器的协调。 真实案例： skill-creator skill "创建新 Skills 的交互式指南。引导用户完成使用场景定义、frontmatter 生成、指令编写和验证。" 核心技巧： 带有验证节点的分步工作流程 常见结构的模板 内置审查和改进建议 迭代精炼循环 第 3 类：MCP 增强 用途： 工作流程指导，以增强 MCP 服务器提供的工具访问能力。 真实案例： sentry-code-review skill（来自 Sentry） "通过 Sentry 的 MCP 服务器，使用 Sentry 错误监控数据自动分析并修复 GitHub Pull Request 中检测到的 bug。" 核心技巧： 按顺序协调多个 MCP 调用 嵌入领域专业知识 提供用户否则需要自行指定的上下文 处理常见 MCP 问题的错误处理 定义成功标准 你如何知道你的 Skill 在正常工作？ 这些是有抱负的目标——粗略的基准，而非精确的阈值。力求严谨，但要接受其中会有一定程度的主观判断。我们正在积极开发更完善的测量指导和工具。 量化指标： Skill 在 90% 的相关查询上触发 测量方法：运行 10-20 个应该触发你的 Skill 的测试查询。追踪它自动加载的次数 vs. 需要显式调用的次数。 在 X 次工具调用内完成工作流程 测量方法：在启用和不启用 Skill 的情况下比较相同任务。统计工具调用次数和消耗的 token 总量。 每个工作流程 0 次 API 调用失败 测量方法：在测试运行期间监控 MCP 服务器日志。追踪重试率和错误代码。 定性指标： 用户不需要提示 Claude 下一步该做什么 评估方法：在测试期间，记录你需要重定向或澄清的频率。向测试用户征求反馈。 工作流程无需用户纠正即可完成 评估方法：将相同请求运行 3-5 次。比较输出的结构一致性和质量。 跨会话结果一致 评估方法：新用户能否在最少指导下第一次就完成任务？ 技术要求 文件结构 your-skill-name/ ├── SKILL.md # 必须——主 Skill 文件 ├── scripts/ # 可选——可执行代码 │ ├── process_data.py # 示例 │ └── validate.sh # 示例 ├── references/ # 可选——文档 │ ├── api-guide.md # 示例 │ └── examples/ # 示例 └── assets/ # 可选——模板等 └── report-template.md # 示例 关键规则 SKILL.md 命名： 必须完全命名为 SKILL.md （区分大小写） 不接受任何变体（SKILL.MD、skill.md 等） Skill 文件夹命名： 使用 kebab-case： notion-project-setup ✅ 不使用空格： Notion Project Setup ❌ 不使用下划线： notion_project_setup ❌ 不使用大写： NotionProjectSetup ❌ 不包含 README.md： 不要在你的 Skill 文件夹内包含 README.md 所有文档放在 SKILL.md 或 references/ 中 注意：通过 GitHub 分发时，你仍然需要在仓库级别为人类用户提供 README——参见「分发与共享」章节。 YAML Frontmatter：最重要的部分 YAML frontmatter 是 Claude 决定是否加载你的 Skill 的方式。务必把这部分做好。 最小必要格式： --- name: your-skill-name description: What it does. Use when user asks to [specific phrases]. --- 这就是你开始所需的全部内容。 字段要求： name （必须）： 仅使用 kebab-case 无空格或大写字母 应与文件夹名称匹配 description （必须）： 必须同时包含： 该 Skill 的功能 何时使用它（触发条件） 少于 1024 个字符 无 XML 标签（ < 或 > ） 包含用户可能说的具体任务 如相关，提及文件类型 license （可选）： 将 Skill 开源时使用 常用：MIT、Apache-2.0 compatibility （可选）： 1-500 个字符 说明环境要求：例如目标产品、所需系统包、网络访问需求等 metadata （可选）： 任意自定义键值对 建议：author、version、mcp-server 示例： metadata: author: ProjectHub version: 1.0.0 mcp-server: projecthub 安全限制 Frontmatter 中禁止： XML 尖括号（ < > ） 名称中含有 "claude" 或 "anthropic" 的 Skills（保留字） 原因： Frontmatter 出现在 Claude 的系统提示中。恶意内容可能注入指令。 编写高效的 Skills Description 字段 根据 Anthropic 工程博客的说法："这些元数据……提供恰到好处的信息，让 Claude 知道何时应使用每个 Skill，而无需将全部内容加载到上下文中。"这是递进式披露的第一级。 结构： [它做什么] + [何时使用] + [核心能力] 良好 description 的示例： # 好——具体且可执行 description: Analyzes Figma design files and generates developer handoff documentation. Use when user uploads .fig files, asks for "design specs", "component documentation", or "design-to-code handoff". # 好——包含触发短语 description: Manages Linear project workflows including sprint planning, task creation, and status tracking. Use when user mentions "sprint", "Linear tasks", "project planning", or asks to "create tickets". # 好——清晰的价值主张 description: End-to-end customer onboarding workflow for PayFlow. Handles account creation, payment setup, and subscription management. Use when user says "onboard new customer", "set up subscription", or "create PayFlow account". 糟糕 description 的示例： # 太模糊 description: Helps with projects. # 缺少触发条件 description: Creates sophisticated multi-page documentation systems. # 过于技术性，没有用户触发词 description: Implements the Project entity model with hierarchical relationships. 编写主体指令 在 frontmatter 之后，用 Markdown 编写实际指令。 推荐结构： 根据你的 Skill 调整此模板。用你的具体内容替换括号中的部分。 --- name: your-skill description: [...] --- # Your Skill Name ## Instructions ### Step 1: [First Major Step] Clear explanation of what happens. ```bash python scripts/fetch_data.py --project-id PROJECT_ID Expected output: [describe what success looks like] ``` (Add more steps as needed) Examples Example 1: [common scenario] User says: "Set up a new marketing campaign" Actions: 1. Fetch existing campaigns via MCP 2. Create new campaign with provided parameters Result: Campaign created with confirmation link (Add more examples as needed) Troubleshooting Error: [Common error message] Cause: [Why it happens] Solution: [How to fix] (Add more error cases as needed) 指令最佳实践 具体且可执行 ✅ 好： Run `python scripts/validate.py --input {filename}` to check data format. If validation fails, common issues include: - Missing required fields (add them to the CSV) - Invalid date formats (use YYYY-MM-DD) ❌ 差： Validate the data before proceeding. 包含错误处理 ## Common Issues ### MCP Connection Failed If you see "Connection refused": 1. Verify MCP server is running: Check Settings > Extensions 2. Confirm API key is valid 3. Try reconnecting: Settings > Extensions > [Your Service] > Reconnect 清晰引用捆绑的资源 Before writing queries, consult `references/api-patterns.md` for: - Rate limiting guidance - Pagination patterns - Error codes and handling 使用递进式披露 保持 SKILL.md 专注于核心指令。将详细文档移至 references/ 并添加链接。（参见「核心设计原则」了解三级系统的工作方式。） 第三章：测试与迭代 Skills 可以根据你的需求进行不同严格程度的测试： 在 Claude.ai 中手动测试 - 直接运行查询并观察行为。迭代快速，无需配置。 在 Claude Code 中脚本化测试 - 自动化测试用例，实现跨版本的可重复验证。 通过 Skills API 程序化测试 - 构建评估套件，系统地针对定义的测试集运行。 根据你的质量要求和 Skill 的可见度选择合适的方法。供小团队内部使用的 Skill 与部署给数千名企业用户的 Skill，其测试需求截然不同。 专业建议：在扩展之前先在单一任务上迭代 我们发现，最有效的 Skill 创建者会在单个具有挑战性的任务上持续迭代直到 Claude 成功，然后将成功的方法提炼成 Skill。这利用了 Claude 的上下文学习能力，比广泛测试提供更快的信号反馈。一旦有了可用的基础，再扩展到多个测试用例以提升覆盖率。 推荐的测试方法 基于早期经验，有效的 Skills 测试通常涵盖三个方面： 1. 触发测试 目标： 确保你的 Skill 在正确时机加载。 测试用例： ✅ 在明显任务上触发 ✅ 在换句话的请求上触发 ❌ 不在无关话题上触发 示例测试套件： 应该触发： - "Help me set up a new ProjectHub workspace" - "I need to create a project in ProjectHub" - "Initialize a ProjectHub project for Q4 planning" 不应触发： - "What's the weather in San Francisco?" - "Help me write Python code" - "Create a spreadsheet" (unless ProjectHub skill handles sheets) 2. 功能测试 目标： 验证 Skill 能产生正确的输出。 测试用例： 生成有效的输出 API 调用成功 错误处理正常工作 边缘情况有所覆盖 示例： Test: Create project with 5 tasks Given: Project name "Q4 Planning", 5 task descriptions When: Skill executes workflow Then: - Project created in ProjectHub - 5 tasks created with correct properties - All tasks linked to project - No API errors 3. 性能对比 目标： 证明 Skill 相比基线有所改善。 使用「定义成功标准」中的指标。以下是一个对比示例： 基线对比： Without skill: - User provides instructions each time - 15 back-and-forth messages - 3 failed API calls requiring retry - 12,000 tokens consumed With skill: - Automatic workflow execution - 2 clarifying questions only - 0 failed API calls - 6,000 tokens consumed 使用 skill-creator Skill Anthropic 维护的 skill-creator Skill 可以帮助你构建和迭代 Skills。如果你有一个 MCP 服务器并了解你的 2-3 个主要工作流程，你可以在单次会话中构建并测试一个功能性 Skill——通常只需 15-30 分钟。 创建 Skills： 从自然语言描述生成 Skills 生成带有 frontmatter 的规范格式 SKILL.md 建议触发短语和结构 审查 Skills： 标记常见问题（模糊描述、缺少触发词、结构问题） 识别潜在的过度/不足触发风险 根据 Skill 的目标用途建议测试用例 迭代改进： 使用 Skill 过程中遇到边缘情况或失败时，将这些示例带回 skill-creator 示例："Use the issues & solution identified in this chat to improve how the skill handles [specific edge case]" 使用方法： "Use the skill-creator skill to help me build a skill for [your use case]" 注意：skill-creator 帮助你设计和完善 Skills，但不执行自动化测试套件或生成定量评估结果。 基于反馈的迭代 Skills 是动态文档。计划根据以下信号进行迭代： 触发不足的信号： Skill 在应该加载时没有加载 用户手动启用它 关于何时使用它的支持问题 解决方案：在 description 中添加更多细节和针对性内容——对于技术术语，可能需要包含关键词 过度触发的信号： Skill 在无关查询时加载 用户禁用它 对用途感到困惑 解决方案：添加负面触发词，更加具体 执行问题： 结果不一致 API 调用失败 需要用户纠正 解决方案：改进指令，添加错误处理 第四章：分发与共享 Skills 让你的 MCP 集成更加完整。当用户比较各种连接器时，拥有 Skills 的连接器提供了更快的价值路径，让你在仅有 MCP 的替代方案中脱颖而出。 当前分发模型（2026 年 1 月） 个人用户获取 Skills 的方式： 下载 Skill 文件夹 压缩文件夹（如需要） 通过 Claude.ai 的 Settings > Capabilities > Skills 上传 或放置在 Claude Code skills 目录中 组织级 Skills： 管理员可以在整个工作区部署 Skills（2025 年 12 月 18 日上线） 自动更新 集中管理 开放标准 我们将 Agent Skills 作为开放标准发布。与 MCP 一样，我们相信 Skills 应该可以跨工具和平台移植——无论使用 Claude 还是其他 AI 平台，同一个 Skill 都应该能够工作。也就是说，有些 Skills 被设计为充分利用特定平台的能力；作者可以在 Skill 的 compatibility 字段中注明这一点。我们一直在与生态系统的各方成员合作推进这一标准，并对早期采用者的积极反响感到振奋。 通过 API 使用 Skills 对于程序化使用场景——如构建利用 Skills 的应用程序、智能体或自动化工作流——API 提供对 Skill 管理和执行的直接控制。 核心能力： /v1/skills 端点，用于列举和管理 Skills 通过 container.skills 参数将 Skills 添加到 Messages API 请求 通过 Claude Console 进行版本控制和管理 与 Claude Agent SDK 协同工作，用于构建自定义智能体 何时使用 API vs. Claude.ai： 使用场景 最佳平台 终端用户直接与 Skills 交互 Claude.ai / Claude Code 开发期间的手动测试和迭代 Claude.ai / Claude Code 个人、临时工作流 Claude.ai / Claude Code 以编程方式使用 Skills 的应用程序 API 大规模生产部署 API 自动化流水线和智能体系统 API 注意：API 中的 Skills 需要代码执行工具（Code Execution Tool）beta 版，该工具提供了 Skills 运行所需的安全环境。 更多实现细节，请参阅： Skills API 快速入门 创建自定义 Skills Agent SDK 中的 Skills 当前推荐方法 从在 GitHub 上用公开仓库托管你的 Skill 开始，包含清晰的 README（面向人类访问者——这与你的 Skill 文件夹分开，Skill 文件夹不应包含 README.md）以及带截图的示例用法。然后在你的 MCP 文档中添加一个章节，链接到该 Skill，解释同时使用两者为何有价值，并提供快速入门指南。 1. 在 GitHub 上托管 开源 Skills 使用公开仓库 清晰的 README，包含安装说明 示例用法和截图 2. 在你的 MCP 仓库中建立文档 从 MCP 文档链接到 Skills 解释同时使用两者的价值 提供快速入门指南 3. 创建安装指南 ## Installing the [Your Service] skill 1. Download the skill: - Clone repo: `git clone https://github.com/yourcompany/ skills` - Or download ZIP from Releases 2. Install in Claude: - Open Claude.ai > Settings > skills - Click "Upload skill" - Select the skill folder (zipped) 3. Enable the skill: - Toggle on the [Your Service] skill - Ensure your MCP server is connected 4. Test: - Ask Claude: "Set up a new project in [Your Service]" 定位你的 Skill 你描述 Skill 的方式决定了用户是否理解其价值并真正尝试使用它。在 README、文档或推广材料中介绍你的 Skill 时，请遵循以下原则： 聚焦结果，而非功能： ✅ 好： "The ProjectHub skill enables teams to set up complete project workspaces in seconds — including pages, databases, and templates — instead of spending 30 minutes on manual setup." ❌ 差： "The ProjectHub skill is a folder containing YAML frontmatter and Markdown instructions that calls our MCP server tools." 突出 MCP + Skills 的组合： "Our MCP server gives Claude access to your Linear projects. Our skills teach Claude your team's sprint planning workflow. Together, they enable AI-powered project management." 第五章：模式与故障排除 这些模式来自早期采用者和内部团队创建的 Skills。它们代表了我们观察到的常见有效方法，而非规定性模板。 选择方法：问题优先 vs. 工具优先 把它想象成家得宝（Home Depot）。你可能带着一个问题走进去——"我需要修厨房橱柜"——然后员工引导你找到合适的工具。或者你可能挑好了一把新电钻，然后询问如何用它完成你的特定工作。 Skills 的工作方式相同： 问题优先 ："我需要设置一个项目工作区" → 你的 Skill 按正确顺序编排合适的 MCP 调用。用户描述结果；Skill 处理工具。 工具优先 ："我已连接了 Notion MCP" → 你的 Skill 教导 Claude 最优工作流程和最佳实践。用户拥有访问权限；Skill 提供专业知识。 大多数 Skills 偏向某一方向。了解哪种框架适合你的使用场景，有助于你选择下方合适的模式。 模式 1：顺序工作流程编排 适用场景： 用户需要按特定顺序执行的多步骤流程。 示例结构： ## Workflow: Onboard New Customer ### Step 1: Create Account Call MCP tool: `create_customer` Parameters: name, email, company ### Step 2: Setup Payment Call MCP tool: `setup_payment_method` Wait for: payment method verification ### Step 3: Create Subscription Call MCP tool: `create_subscription` Parameters: plan_id, customer_id (from Step 1) ### Step 4: Send Welcome Email Call MCP tool: `send_email` Template: welcome_email_template 核心技巧： 明确的步骤顺序 步骤间的依赖关系 每个阶段的验证 失败时的回滚指令 模式 2：多 MCP 协调 适用场景： 工作流程跨越多个服务。 示例： 设计到开发的交接 ### Phase 1: Design Export (Figma MCP) 1. Export design assets from Figma 2. Generate design specifications 3. Create asset manifest ### Phase 2: Asset Storage (Drive MCP) 1. Create project folder in Drive 2. Upload all assets 3. Generate shareable links ### Phase 3: Task Creation (Linear MCP) 1. Create development tasks 2. Attach asset links to tasks 3. Assign to engineering team ### Phase 4: Notification (Slack MCP) 1. Post handoff summary to #engineering 2. Include asset links and task references 核心技巧： 清晰的阶段划分 MCP 之间的数据传递 进入下一阶段前的验证 集中的错误处理 模式 3：迭代精炼 适用场景： 输出质量随迭代提升。 示例： 报告生成 ## Iterative Report Creation ### Initial Draft 1. Fetch data via MCP 2. Generate first draft report 3. Save to temporary file ### Quality Check 1. Run validation script: `scripts/check_report.py` 2. Identify issues: - Missing sections - Inconsistent formatting - Data validation errors ### Refinement Loop 1. Address each identified issue 2. Regenerate affected sections 3. Re-validate 4. Repeat until quality threshold met ### Finalization 1. Apply final formatting 2. Generate summary 3. Save final version 核心技巧： 明确的质量标准 迭代改进 验证脚本 知道何时停止迭代 模式 4：上下文感知工具选择 适用场景： 相同的结果，根据上下文使用不同的工具。 示例： 文件存储 ## Smart File Storage ### Decision Tree 1. Check file type and size 2. Determine best storage location: - Large files (>10MB): Use cloud storage MCP - Collaborative docs: Use Notion/Docs MCP - Code files: Use GitHub MCP - Temporary files: Use local storage ### Execute Storage Based on decision: - Call appropriate MCP tool - Apply service-specific metadata - Generate access link ### Provide Context to User Explain why that storage was chosen 核心技巧： 清晰的决策标准 备选方案 关于选择的透明度 模式 5：领域特定智能 适用场景： 你的 Skill 在工具访问之外增加了专业知识。 示例： 金融合规 ## Payment Processing with Compliance ### Before Processing (Compliance Check) 1. Fetch transaction details via MCP 2. Apply compliance rules: - Check sanctions lists - Verify jurisdiction allowances - Assess risk level 3. Document compliance decision ### Processing IF compliance passed: - Call payment processing MCP tool - Apply appropriate fraud checks - Process transaction ELSE: - Flag for review - Create compliance case ### Audit Trail - Log all compliance checks - Record processing decisions - Generate audit report 核心技巧： 逻辑中嵌入领域专业知识 行动前先合规 全面的文档记录 清晰的治理 故障排除 Skill 无法上传 错误："Could not find SKILL.md in uploaded folder" 原因：文件没有完全命名为 SKILL.md 解决方案： 重命名为 SKILL.md（区分大小写） 用 ls -la 验证，应显示 SKILL.md 错误："Invalid frontmatter" 原因：YAML 格式问题 常见错误： # 错误——缺少分隔符 name: my-skill description: Does things # 错误——未闭合的引号 name: my-skill description: "Does things # 正确 --- name: my-skill description: Does things --- 错误："Invalid skill name" 原因：名称含有空格或大写字母 # 错误 name: My Cool Skill # 正确 name: my-cool-skill Skill 不触发 症状： Skill 从不自动加载 修复： 修改你的 description 字段。参见「Description 字段」章节中的好/坏示例。 快速检查清单： 是否太通用？（"Helps with projects" 无效） 是否包含用户实际会说的触发短语？ 如果适用，是否提及了相关文件类型？ 调试方法： 询问 Claude："When would you use the [skill name] skill?" Claude 会引用 description 内容。根据缺失的内容进行调整。 Skill 触发过于频繁 症状： Skill 在无关查询时加载 解决方案： 1. 添加负面触发词 description: Advanced data analysis for CSV files. Use for statistical modeling, regression, clustering. Do NOT use for simple data exploration (use data-viz skill instead). 2. 更加具体 # 太宽泛 description: Processes documents # 更具体 description: Processes PDF legal documents for contract review 3. 明确范围 description: PayFlow payment processing for e-commerce. Use specifically for online payment workflows, not for general financial queries. MCP 连接问题 症状： Skill 加载但 MCP 调用失败 检查清单： 验证 MCP 服务器是否已连接 Claude.ai：Settings > Extensions > [你的服务] 应显示"Connected"状态 检查身份验证 API 密钥有效且未过期 已授予正确的权限/范围 OAuth token 已刷新 独立测试 MCP 让 Claude 直接调用 MCP（不使用 Skill） "Use [Service] MCP to fetch my projects" 如果这也失败，问题在 MCP 而非 Skill 验证工具名称 Skill 引用了正确的 MCP 工具名称 检查 MCP 服务器文档 工具名称区分大小写 指令未被遵循 症状： Skill 加载但 Claude 不遵循指令 常见原因： 指令太冗长 保持指令简洁 使用项目符号和编号列表 将详细参考内容移至单独文件 指令被埋没 将关键指令放在最前面 使用 ## Important 或 ## Critical 标题 如有必要，重复关键要点 语言模糊 # 差 Make sure to validate things properly # 好 CRITICAL: Before calling create_project, verify: - Project name is non-empty - At least one team member assigned - Start date is not in the past 高级技巧： 对于关键验证，考虑打包一个以编程方式执行检查的脚本，而不是依赖语言指令。代码是确定性的；语言解读则不然。参见 Office skills 了解此模式的示例。 模型"偷懒" 添加明确的鼓励： ## Performance Notes - Take your time to do this thoroughly - Quality is more important than speed - Do not skip validation steps 注意：将此内容添加到用户提示中比放在 SKILL.md 中更有效。 大上下文问题 症状： Skill 看起来变慢或响应质量下降 原因： Skill 内容太大 同时启用的 Skills 太多 所有内容被加载而非递进式披露 解决方案： 优化 SKILL.md 大小 将详细文档移至 references/ 链接引用而非内联 将 SKILL.md 控制在 5,000 字以内 减少启用的 Skills 数量 评估是否同时启用了超过 20-50 个 Skills 建议选择性启用 考虑将相关能力打包成 Skill "套件" 第六章：资源与参考 如果你在构建第一个 Skill，从最佳实践指南开始，然后根据需要参考 API 文档。 官方文档 Anthropic 资源： 最佳实践指南 Skills 文档 API 参考 MCP 文档 博客文章： Introducing Agent Skills Engineering Blog: Equipping Agents for the Real World Skills Explained How to Create Skills for Claude Building Skills for Claude Code Improving Frontend Design through Skills 示例 Skills 公开 Skills 仓库： GitHub：anthropics/skills 包含 Anthropic 创建的可供定制的 Skills 工具与实用程序 skill-creator skill： 内置于 Claude.ai 并可用于 Claude Code 可以从描述生成 Skills 提供审查和建议 使用方法："Help me build a skill using skill-creator" 验证： skill-creator 可以评估你的 Skills 询问："Review this skill and suggest improvements" 获取支持 技术问题： 一般问题：Claude Developers Discord 社区论坛 Bug 报告： GitHub Issues：anthropics/skills/issues 请包含：Skill 名称、错误信息、复现步骤 参考 A：快速检查清单 使用此检查清单在上传前后验证你的 Skill。如果你想更快上手，可以使用 skill-creator skill 生成初稿，然后通过此清单确保没有遗漏任何内容。 开始之前 已确定 2-3 个具体使用场景 已确定所需工具（内置或 MCP） 已阅读本指南和示例 Skills 已规划文件夹结构 开发过程中 文件夹以 kebab-case 命名 SKILL.md 文件存在（拼写准确） YAML frontmatter 有 --- 分隔符 name 字段：kebab-case，无空格，无大写字母 description 包含功能描述（WHAT）和使用时机（WHEN） 无 XML 标签（ < > ） 指令清晰且可执行 包含错误处理 提供了示例 引用已清晰链接 上传之前 已测试在明显任务上的触发 已测试在换句话请求上的触发 已验证不会在无关话题上触发 功能测试通过 工具集成正常工作（如适用） 已压缩为 .zip 文件 上传之后 在真实对话中测试 监控触发不足/过度触发情况 收集用户反馈 迭代 description 和指令 在 metadata 中更新版本号 参考 B：YAML Frontmatter 必填字段 --- name: skill-name-in-kebab-case description: What it does and when to use it. Include specific trigger phrases. --- 所有可选字段 name: skill-name description: [required description] license: MIT # 可选：开源许可证 allowed-tools: "Bash(python:*) Bash(npm:*) WebFetch" # 可选：限制工具访问 metadata: # 可选：自定义字段 author: Company Name version: 1.0.0 mcp-server: server-name category: productivity tags: [project-management, automation] documentation: https://example.com/docs support: support@example.com 安全说明 允许： 任何标准 YAML 类型（字符串、数字、布尔值、列表、对象） 自定义 metadata 字段 较长的 description（最多 1024 个字符） 禁止： XML 尖括号（ < > ）——安全限制 YAML 中的代码执行（使用安全 YAML 解析） 以 "claude" 或 "anthropic" 为前缀命名的 Skills（保留字） 参考 C：完整的 Skill 示例 完整的、生产就绪的 Skills 演示了本指南中的各种模式，请参阅： Document Skills - PDF、DOCX、PPTX、XLSX 创建 Example Skills - 各种工作流程模式 Partner Skills Directory - 查看来自各合作伙伴的 Skills，包括 Asana、Atlassian、Canva、Figma、Sentry、Zapier 等 这些仓库持续更新，并包含本指南之外的更多示例。克隆它们，根据你的使用场景进行修改，并将其作为模板使用。 Claude Code Skills 实战经验 Skills 已经成为 Claude Code 中使用最广泛的扩展点（extension points）之一。它们灵活、容易制作，分发起来也很简单。 但也正因为太灵活，你很难知道怎样用才最好。什么类型的 Skills 值得做？写出好 Skill 的秘诀是什么？什么时候该把它们分享给别人？ 我们在 Anthropic 内部大量使用 Claude Code 的 Skills（技能扩展），目前活跃使用的已经有几百个。以下就是我们在用 Skills 加速开发过程中总结出的经验。 什么是 Skills？ 如果你还不了解 Skills，建议先看看 我们的文档 或最新的 Skilljar 上关于 Agent Skills 的课程 ，本文假设你已经对 Skills 有了基本的了解。 我们经常听到一个误解，认为 Skills"只不过是 markdown 文件"。但 Skills 最有意思的地方恰恰在于它们不只是文本文件——它们是文件夹，可以包含脚本、资源文件、数据等等，智能体可以发现、探索和使用这些内容。 在 Claude Code 中，Skills 还拥有 丰富的配置选项 ，包括注册动态钩子（hooks）。 我们发现，Claude Code 中最有意思的那些 Skills，往往就是创造性地利用了这些配置选项和文件夹结构。 在梳理了我们所有的 Skills 之后，我们注意到它们大致可以归为几个反复出现的类别。最好的 Skills 清晰地落在某一个类别里；让人困惑的 Skills 往往横跨了好几个。这不是一份终极清单，但如果你想检查团队里是否还缺了什么类型的 Skills，这是一个很好的思路。 九种 Skill 类型 1. 库与 API 参考 帮助你正确使用某个库、命令行工具或 SDK 的 Skills。它们既可以针对内部库，也可以针对 Claude Code 偶尔会犯错的常用库。这类 Skills 通常会包含一个参考代码片段的文件夹，以及一份 Claude 在写代码时需要避免的踩坑点（gotchas）列表。 示例： billing-lib — 你的内部计费库：边界情况、容易踩的坑（footguns）等 internal-platform-cli — 内部 CLI 工具的每个子命令及其使用场景示例 frontend-design — 让 Claude 更好地理解你的设计系统 2. 产品验证 描述如何测试或验证代码是否正常工作的 Skills。通常会搭配 Playwright、tmux 等外部工具来完成验证。 验证类 Skills 对于确保 Claude 输出的正确性非常有用。值得安排一个工程师花上一周时间专门打磨你的验证 Skills。 可以考虑一些技巧，比如让 Claude 录制输出过程的视频，这样你就能看到它到底测试了什么；或者在每一步强制执行程序化的状态断言。这些通常通过在 Skill 中包含各种脚本来实现。 示例： signup-flow-driver — 在无头浏览器中跑完注册→邮件验证→引导流程，每一步都可以插入状态断言的钩子 checkout-verifier — 用 Stripe 测试卡驱动结账 UI，验证发票最终是否到了正确的状态 tmux-cli-driver — 针对需要 TTY 的交互式命令行测试 3. 数据获取与分析 连接你的数据和监控体系的 Skills。这类 Skills 可能会包含带有凭证的数据获取库、特定的仪表盘 ID 等，以及常用工作流和数据获取方式的说明。 示例： funnel-query — "要看注册→激活→付费的转化，需要关联哪些事件？"，再加上真正存放规范 user_id 的那张表 cohort-compare — 对比两个用户群的留存或转化率，标记统计显著的差异，链接到分群定义 grafana — 数据源 UID、集群名称、问题→仪表盘对照表 4. 业务流程与团队自动化 把重复性工作流自动化为一条命令的 Skills。这类 Skills 通常指令比较简单，但可能会依赖其他 Skills 或 MCP（Model Context Protocol，模型上下文协议）。对于这类 Skills，把之前的执行结果保存在日志文件中，有助于模型保持一致性并反思之前的执行情况。 示例： standup-post — 汇总你的任务追踪器、GitHub 活动和之前的 Slack 消息→生成格式化的站会汇报，只报变化部分（delta-only） create--ticket — 强制执行 schema（合法的枚举值、必填字段）加上创建后的工作流（通知审查者、在 Slack 中发链接） weekly-recap — 已合并的 PR + 已关闭的工单 + 部署记录→格式化的周报 5. 代码脚手架与模板 为代码库中的特定功能生成框架样板代码（boilerplate）的 Skills。你可以把这些 Skills 和脚本组合使用。当你的脚手架（scaffolding）有自然语言需求、无法纯靠代码覆盖时，这类 Skills 特别有用。 示例： new--workflow — 用你的注解搭建新的服务/工作流/处理器 new-migration — 你的数据库迁移文件模板加上常见踩坑点 create-app — 新建内部应用，预配好你的认证、日志和部署配置 6. 代码质量与审查 在团队内部执行代码质量标准并辅助代码审查的 Skills。可以包含确定性的脚本或工具来保证最大的可靠性。你可能希望把这些 Skills 作为钩子的一部分自动运行，或者放在 GitHub Action 中执行。 示例： adversarial-review — 生成一个全新视角的子智能体来挑刺，实施修复，反复迭代直到发现的问题退化为吹毛求疵。子智能体（subagent）是指 Claude Code 在执行任务时启动的另一个独立 Claude 实例。这里的做法是让一个"没见过这段代码"的新实例来做代码审查，避免原实例的思维惯性。 code-style — 强制执行代码风格，特别是那些 Claude 默认做不好的风格 testing-practices — 关于如何写测试以及测试什么的指导 7. CI/CD 与部署 帮你拉取、推送和部署代码的 Skills。这类 Skills 可能会引用其他 Skills 来收集数据。 示例： babysit-pr — 监控一个 PR→重试不稳定的 CI→解决合并冲突→启用自动合并 deploy- — 构建→冒烟测试→渐进式流量切换并对比错误率→指标恶化时自动回滚 cherry-pick-prod — 隔离的工作树（worktree）→cherry-pick→解决冲突→用模板创建 PR 8. 运维手册 接收一个现象（比如一条 Slack 消息、一条告警或者一个错误特征），引导你走完多工具排查流程，最后生成结构化报告的 Skills。 示例： -debugging — 把现象对应到工具→查询模式，覆盖你流量最大的服务 oncall-runner — 拉取告警→检查常见嫌疑→格式化输出排查结论 log-correlator — 给定一个请求 ID，从所有可能经过的系统中拉取匹配的日志 9. 基础设施运维 执行日常维护和运维操作的 Skills——其中一些涉及破坏性操作，需要安全护栏。这些 Skills 让工程师在执行关键操作时更容易遵循最佳实践。 示例： -orphans — 找到孤立的 Pod/Volume→发到 Slack→等待观察→用户确认→级联清理 dependency-management — 你所在组织的依赖审批工作流 cost-investigation — "我们的存储/出口带宽费用为什么突然涨了"，附带具体的存储桶和查询模式 编写技巧 确定了要做什么 Skill 之后，怎么写呢？以下是我们总结的一些最佳实践和技巧。 我们最近还发布了 Skill Creator ，让在 Claude Code 中创建 Skills 变得更加简单。 不要说显而易见的事 Claude Code 对你的代码库已经非常了解，Claude 本身对编程也很在行，包括很多默认的观点。如果你发布的 Skill 主要是提供知识，那就把重点放在能打破 Claude 常规思维模式的信息上。 frontend design 这个 Skill 就是一个很好的例子——它是 Anthropic 的一位工程师通过与用户反复迭代、改进 Claude 的设计品味而构建的，专门避免那些典型的套路，比如 Inter 字体和紫色渐变。 建一个踩坑点章节 任何 Skill 中信息量最大的部分就是踩坑点章节。这些章节应该根据 Claude 在使用你的 Skill 时遇到的常见失败点逐步积累起来。理想情况下，你会持续更新 Skill 来记录这些踩坑点。 利用文件系统与渐进式披露 就像前面说的，Skill 是一个文件夹，不只是一个 markdown 文件。你应该把整个文件系统当作上下文工程（Context Engineering）和渐进式披露（progressive disclosure）的工具。告诉 Claude 你的 Skill 里有哪些文件，它会在合适的时候去读取它们。 上下文工程（Context Engineering）是 2025 年由 Andrej Karpathy 等人提出并广泛传播的概念，指的是精心设计和管理输入给大语言模型的上下文信息，以最大化模型的输出质量。渐进式披露（progressive disclosure）借用了 UI 设计中的概念，意思是不一次性把所有信息塞给模型，而是让它在需要时再去读取，从而节省上下文窗口空间。 最简单的渐进式披露形式是指向其他 markdown 文件让 Claude 使用。例如，你可以把详细的函数签名和用法示例拆分到 references/api.md 里。 另一个例子：如果你的最终输出是一个 markdown 文件，你可以在 assets/ 中放一个模板文件供复制使用。 你可以有参考资料、脚本、示例等文件夹，帮助 Claude 更高效地工作。 不要把 Claude 限制得太死 Claude 通常会努力遵循你的指令，而由于 Skills 的复用性很强，你需要注意不要把指令写得太具体。给 Claude 它需要的信息，但留给它适应具体情况的灵活性。 考虑好初始设置 有些 Skills 可能需要用户提供上下文来完成初始设置。例如，如果你做了一个把站会内容发到 Slack 的 Skill，你可能希望 Claude 先问用户要发到哪个 Slack 频道。 一个好的做法是把这些设置信息存在 Skill 目录下的 config.json 文件里。如果配置还没设置好，智能体就会向用户询问相关信息。 如果你希望智能体向用户展示结构化的多选题，可以让 Claude 使用 AskUserQuestion 工具。 description 字段是给模型看的 当 Claude Code 启动一个会话时，它会构建一份所有可用 Skills 及其描述的清单。Claude 通过扫描这份清单来判断"这个请求有没有对应的 Skill？"所以 description 字段不是摘要——它描述的是 何时该触发这个 Skill 。 这条建议经常被忽略。很多人写 description 时会写"这个 Skill 做什么"，但 Claude 需要的是"什么情况下该用这个 Skill"。好的 description 读起来更像 if-then 条件，而不是功能说明。 记忆与数据存储 有些 Skills 可以通过在内部存储数据来实现某种形式的记忆。你可以用最简单的方式——一个只追加写入的文本日志文件或 JSON 文件，也可以用更复杂的方式——比如 SQLite 数据库。 例如，一个 standup-post Skill 可以保留一份 standups.log ，记录它写过的每一条站会汇报。这样下次运行时，Claude 会读取自己的历史记录，就能知道从昨天到现在发生了什么变化。 存在 Skill 目录下的数据可能会在升级 Skill 时被删除，因此持久数据应保存在 Skill 目录之外、由用户明确选择的稳定位置，并在配置中记录该路径。 存储脚本与生成代码 你能给 Claude 的最强大的工具之一就是代码。给 Claude 提供脚本和库，让它把精力花在组合编排上——决定下一步做什么，而不是重新构造样板代码。 例如，在你的数据科学 Skill 中，你可以放一组从事件源获取数据的函数库。为了让 Claude 做更复杂的分析，你可以提供一组辅助函数，像这样： Claude 就可以即时生成脚本来组合这些功能，完成更高级的分析——比如回答"周二发生了什么？"这样的问题。 按需钩子 Skills 可以包含只在该 Skill 被调用时才激活的钩子（On Demand Hooks），并且在整个会话期间保持生效。这适合那些比较主观、你不想一直运行但有时候极其有用的钩子。 例如： /careful — 通过 PreToolUse 匹配器拦截 Bash 中的 rm -rf 、 DROP TABLE 、force-push、 kubectl delete 。你只在知道自己在操作生产环境时才需要这个——要是一直开着会让你抓狂。PreToolUse 是 Claude Code 的钩子（hook）机制之一，会在 Claude 每次调用工具之前触发。你可以在这个钩子里检查 Claude 即将执行的命令，如果命中危险操作就阻止执行。这里 /careful 是一个按需激活的 Skill，只有用户主动调用时才会注册这个钩子。 /freeze — 阻止对特定目录之外的任何 Edit/Write 操作。在调试时特别有用："我想加日志但老是不小心'修'了不相关的代码" 团队分发 Skills 最大的好处之一就是你可以把它们分享给团队的其他人。 最直接的分享方式是把 Skills 提交到代码仓库的 .agents/skills/ 中，让项目成员和兼容客户端共同使用；跨项目复用时，也可以通过独立 Git 仓库或压缩包分发到用户级 Skills 目录。无论采用哪种方式，都应在正式分发前检查重复内容、来源、权限和实际评测结果。 组合 Skills 你可能希望 Skills 之间互相依赖。例如，你可能有一个文件上传 Skill 用来上传文件，以及一个 CSV 生成 Skill 用来生成 CSV 并上传。Agent Skills 规范目前没有定义 Skill 间的依赖管理；可以在说明中引用其他 Skill，但需要明确前置条件，并为缺少依赖的情况提供替代路径。 衡量 Skills 的效果 为了了解一个 Skill 的表现，我们使用了一个 PreToolUse 钩子来在公司内部记录 Skill 的使用情况（ 示例代码在这里 ）。这样我们就能发现哪些 Skills 很受欢迎，或者哪些触发频率低于预期。 结语 Skills 是 AI 智能体（AI Agent）极其强大且灵活的工具，但这一切还处于早期阶段，我们都在摸索怎样用好它们。 与其把这篇文章当作权威指南，不如把它看作我们实践中验证过有效的一堆实用技巧合集。理解 Skills 最好的方式就是动手开始做、不断试验、看看什么对你管用。我们大多数 Skills 一开始就是几行文字加一个踩坑点，后来因为大家不断补充 Claude 遇到的新边界情况，才慢慢变好的。 希望这篇文章对你有帮助，如果有任何问题欢迎告诉我。 Agent Skill 五种设计模式 说到 SKILL.md ，开发者往往执着于格式问题——把 YAML 写对、组织好目录结构、遵循规范。但随着超过 30 种 Agent 工具（如 Claude Code、Gemini CLI、Cursor）都在向同一套目录结构靠拢，格式问题已基本成为历史。 现在真正的挑战是 内容设计 。规范告诉你如何打包一个 Skill，却对如何组织其中的逻辑毫无指导。举个例子：一个封装 FastAPI 规范的 Skill，和一个四步文档生成流水线，从外部看 SKILL.md 文件几乎一模一样，但它们的运作方式截然不同。 通过研究整个生态系统中 Skill 的构建方式——从 Anthropic 的代码库到 Vercel 和 Google 的内部指南——我们总结出了五种反复出现的设计模式，帮助开发者构建更可靠的 Agent。 本文将结合可运行的 ADK 代码，逐一介绍每种模式： 工具封装（Tool Wrapper） ：让你的 Agent 瞬间成为任意库的专家 生成器（Generator） ：从可复用模板生成结构化文档 审查器（Reviewer） ：按严重程度对照清单评审代码 反转（Inversion） ：Agent 先采访你，再开始行动 流水线（Pipeline） ：强制执行带检查点的严格多步骤工作流 模式一：工具封装（Tool Wrapper） 工具封装让你的 Agent 能够按需获取特定库的上下文。与其把 API 规范硬编码进系统提示，不如将它们打包成一个 Skill。Agent 只在真正需要使用该技术时才加载这些上下文。 这是最简单的实现模式。 SKILL.md 文件监听用户提示中的特定库关键词，从 references/ 目录动态加载内部文档，并将这些规则作为绝对准则应用。这正是你向团队开发者工作流中分发内部编码规范或特定框架最佳实践的机制。 下面是一个工具封装示例，教 Agent 如何编写 FastAPI 代码。注意指令明确告诉 Agent 只在开始审查或编写代码时才加载 conventions.md ： # skills/api-expert/SKILL.md --- name: api-expert description: FastAPI 开发最佳实践与规范。在构建、审查或调试 FastAPI 应用、REST API 或 Pydantic 模型时使用。 metadata: pattern: tool-wrapper domain: fastapi --- 你是 FastAPI 开发专家。将以下规范应用于用户的代码或问题。 ## 核心规范 加载 'references/conventions.md' 获取完整的 FastAPI 最佳实践列表。 ## 审查代码时 1. 加载规范参考文件 2. 对照每条规范检查用户代码 3. 对于每处违规，引用具体规则并给出修复建议 ## 编写代码时 1. 加载规范参考文件 2. 严格遵循每条规范 3. 为所有函数签名添加类型注解 4. 使用 Annotated 风格进行依赖注入 模式二：生成器（Generator） 工具封装负责应用知识，而生成器负责强制输出一致性。如果你苦恼于 Agent 每次生成的文档结构都不一样，生成器通过编排"填空"流程来解决这个问题。 它利用两个可选目录： assets/ 存放输出模板， references/ 存放风格指南。指令充当项目经理的角色，告诉 Agent 加载模板、读取风格指南、向用户询问缺失的变量，然后填充文档。这对于生成可预期的 API 文档、标准化提交信息或搭建项目架构非常实用。 在这个技术报告生成器示例中，Skill 文件本身不包含实际的布局或语法规则，它只是协调这些资源的检索，并强制 Agent 逐步执行： # skills/report-generator/SKILL.md --- name: report-generator description: 生成 Markdown 格式的结构化技术报告。当用户要求撰写、创建或起草报告、摘要或分析文档时使用。 metadata: pattern: generator output-format: markdown --- 你是一个技术报告生成器。严格按照以下步骤执行： 第一步：加载 'references/style-guide.md' 获取语气和格式规则。 第二步：加载 'assets/report-template.md' 获取所需的输出结构。 第三步：向用户询问填充模板所需的缺失信息： - 主题或议题 - 关键发现或数据点 - 目标受众（技术人员、管理层、普通读者） 第四步：按照风格指南规则填充模板。模板中的每个章节都必须出现在输出中。 第五步：以单个 Markdown 文档的形式返回完成的报告。 模式三：审查器（Reviewer） 审查器模式将"检查什么"与"如何检查"分离开来。与其在系统提示中罗列每一种代码坏味道，不如将模块化的评审标准存储在 references/review-checklist.md 文件中。 当用户提交代码时，Agent 加载这份清单并系统地对提交内容评分，按严重程度分组整理发现的问题。如果你把 Python 风格清单换成 OWASP 安全清单，使用完全相同的 Skill 基础设施，就能得到一个完全不同的专项审计工具。这是自动化 PR 审查或在人工审查前捕获漏洞的高效方式。 下面的代码审查器 Skill 展示了这种分离。指令保持静态，但 Agent 从外部清单动态加载具体的审查标准，并强制输出结构化的、按严重程度分级的结果： # skills/code-reviewer/SKILL.md --- name: code-reviewer description: 审查 Python 代码的质量、风格和常见 Bug。当用户提交代码请求审查、寻求代码反馈或需要代码审计时使用。 metadata: pattern: reviewer severity-levels: error,warning,info --- 你是一名 Python 代码审查员。严格遵循以下审查流程： 第一步：加载 'references/review-checklist.md' 获取完整的审查标准。 第二步：仔细阅读用户的代码。在批评之前先理解其目的。 第三步：将清单中的每条规则应用于代码。对于发现的每处违规： - 记录行号（或大致位置） - 分类严重程度：error（必须修复）、warning（应该修复）、info（建议考虑） - 解释为什么这是问题，而不仅仅是说明是什么问题 - 给出包含修正代码的具体修复建议 第四步：生成包含以下章节的结构化审查报告： - **摘要**：代码的功能描述，整体质量评估 - **发现**：按严重程度分组（先列 error，再列 warning，最后列 info） - **评分**：1-10 分，附简短说明 - **三大建议**：最具影响力的改进措施 模式四：反转（Inversion） Agent 天生倾向于立即猜测并生成内容。反转模式颠覆了这一动态。不再是用户驱动提示、Agent 执行，而是让 Agent 扮演采访者的角色。 反转依赖明确的、不可绕过的门控指令（如"在所有阶段完成之前不得开始构建"），强制 Agent 先收集上下文。它按顺序提出结构化问题，等待你的回答后再进入下一阶段。在获得完整的需求和部署约束全貌之前，Agent 拒绝综合最终输出。 来看这个项目规划器 Skill。关键要素是严格的阶段划分，以及明确阻止 Agent 在收集完所有用户回答之前综合最终计划的门控提示： # skills/project-planner/SKILL.md --- name: project-planner description: 通过结构化提问收集需求，然后生成计划，从而规划新软件项目。当用户说"我想构建"、"帮我规划"、"设计一个系统"或"启动新项目"时使用。 metadata: pattern: inversion interaction: multi-turn --- 你正在进行一次结构化需求访谈。在所有阶段完成之前，不得开始构建或设计。 ## 第一阶段——问题发现（每次只问一个问题，等待每个回答） 按顺序提问，不得跳过任何问题。 - Q1："这个项目为用户解决什么问题？" - Q2："主要用户是谁？他们的技术水平如何？" - Q3："预期规模是多少？（每日用户数、数据量、请求频率）" ## 第二阶段——技术约束（仅在第一阶段完全回答后进行） - Q4："你将使用什么部署环境？" - Q5："你有技术栈要求或偏好吗？" - Q6："有哪些不可妥协的要求？（延迟、可用性、合规性、预算）" ## 第三阶段——综合（仅在所有问题都回答后进行） 1. 加载 'assets/plan-template.md' 获取输出格式 2. 使用收集到的需求填充模板的每个章节 3. 向用户呈现完成的计划 4. 询问："这份计划是否准确反映了你的需求？你想修改什么？" 5. 根据反馈迭代，直到用户确认 模式五：流水线（Pipeline） 对于复杂任务，你无法承受步骤被跳过或指令被忽视的代价。流水线模式强制执行带有硬性检查点的严格顺序工作流。 指令本身就是工作流定义。通过实现明确的菱形门控条件（例如要求用户在从文档字符串生成阶段进入最终组装阶段之前给予确认），流水线确保 Agent 不能绕过复杂任务直接呈现未经验证的最终结果。 这种模式充分利用所有可选目录，只在特定步骤需要时才引入不同的参考文件和模板，保持上下文窗口的整洁。 在这个文档生成流水线示例中，注意明确的门控条件——Agent 被明确禁止在用户确认上一步生成的文档字符串之前进入组装阶段： # skills/doc-pipeline/SKILL.md --- name: doc-pipeline description: 通过多步骤流水线从 Python 源代码生成 API 文档。当用户要求为模块编写文档、生成 API 文档或从代码创建文档时使用。 metadata: pattern: pipeline steps: "4" --- 你正在运行一个文档生成流水线。按顺序执行每个步骤。不得跳过步骤，步骤失败时不得继续。 ## 第一步——解析与清点 分析用户的 Python 代码，提取所有公开的类、函数和常量。以清单形式呈现清点结果。询问："这是你想要文档化的完整公开 API 吗？" ## 第二步——生成文档字符串 对于每个缺少文档字符串的函数： - 加载 'references/docstring-style.md' 获取所需格式 - 严格按照风格指南生成文档字符串 - 逐一呈现生成的文档字符串供用户确认 在用户确认之前，不得进入第三步。 ## 第三步——组装文档 加载 'assets/api-doc-template.md' 获取输出结构。将所有类、函数和文档字符串编译成单一的 API 参考文档。 ## 第四步——质量检查 对照 'references/quality-checklist.md' 进行审查： - 每个公开符号都已文档化 - 每个参数都有类型和描述 - 每个函数至少有一个使用示例 报告结果。在呈现最终文档之前修复所有问题。 如何选择合适的模式 每种模式回答的是不同的问题。用这棵决策树找到适合你场景的模式： 你的问题 推荐模式 如何让 Agent 掌握特定库或框架的知识？ 工具封装 如何确保每次输出的文档结构一致？ 生成器 如何自动化代码审查或安全审计？ 审查器 如何防止 Agent 在需求不明确时乱猜？ 反转 如何确保复杂任务的每个步骤都被执行？ 流水线 模式可以组合使用 这五种模式并不互斥，它们可以组合。 流水线 Skill 可以在末尾加入一个审查器步骤来自我检验。生成器可以在开头借助反转模式收集必要的变量，再填充模板。得益于 ADK 的 SkillToolset 和递进式披露机制，你的 Agent 在运行时只会为真正需要的模式消耗上下文 token。 不要再试图把复杂而脆弱的指令塞进单个系统提示。拆解你的工作流，应用正确的结构模式，构建更可靠的 Agent。 立即开始 Agent Skills 规范是开源的，并在 ADK 中原生支持。你已经知道如何打包格式，现在你也知道如何设计内容了。用 Google Agent Development Kit 构建更智能的 Agent 吧。 Claude Skill：Skill Creator --- name: skill-creator description: Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. --- Skill Creator A skill for creating new skills and iteratively improving them. At a high level, the process of creating a skill goes like this: Decide what you want the skill to do and roughly how it should do it Write a draft of the skill Create a few test prompts and run claude-with-access-to-the-skill on them Help the user evaluate the results both qualitatively and quantitatively While the runs happen in the background, draft some quantitative evals if there aren't any (if there are some, you can either use as is or modify if you feel something needs to change about them). Then explain them to the user (or if they already existed, explain the ones that already exist) Use the eval-viewer/generate_review.py script to show the user the results for them to look at, and also let them look at the quantitative metrics Rewrite the skill based on feedback from the user's evaluation of the results (and also if there are any glaring flaws that become apparent from the quantitative benchmarks) Repeat until you're satisfied Expand the test set and try again at larger scale Your job when using this skill is to figure out where the user is in this process and then jump in and help them progress through these stages. So for instance, maybe they're like "I want to make a skill for X". You can help narrow down what they mean, write a draft, write the test cases, figure out how they want to evaluate, run all the prompts, and repeat. On the other hand, maybe they already have a draft of the skill. In this case you can go straight to the eval/iterate part of the loop. Of course, you should always be flexible and if the user is like "I don't need to run a bunch of evaluations, just vibe with me", you can do that instead. Then after the skill is done (but again, the order is flexible), you can also run the skill description improver, which we have a whole separate script for, to optimize the triggering of the skill. Cool? Cool. Communicating with the user The skill creator is liable to be used by people across a wide range of familiarity with coding jargon. If you haven't heard (and how could you, it's only very recently that it started), there's a trend now where the power of Claude is inspiring plumbers to open up their terminals, parents and grandparents to google "how to install npm". On the other hand, the bulk of users are probably fairly computer-literate. So please pay attention to context cues to understand how to phrase your communication! In the default case, just to give you some idea: "evaluation" and "benchmark" are borderline, but OK for "JSON" and "assertion" you want to see serious cues from the user that they know what those things are before using them without explaining them It's OK to briefly explain terms if you're in doubt, and feel free to clarify terms with a short definition if you're unsure if the user will get it. Creating a skill Capture Intent Start by understanding the user's intent. The current conversation might already contain a workflow the user wants to capture (e.g., they say "turn this into a skill"). If so, extract answers from the conversation history first — the tools used, the sequence of steps, corrections the user made, input/output formats observed. The user may need to fill the gaps, and should confirm before proceeding to the next step. What should this skill enable Claude to do? When should this skill trigger? (what user phrases/contexts) What's the expected output format? Should we set up test cases to verify the skill works? Skills with objectively verifiable outputs (file transforms, data extraction, code generation, fixed workflow steps) benefit from test cases. Skills with subjective outputs (writing style, art) often don't need them. Suggest the appropriate default based on the skill type, but let the user decide. Interview and Research Proactively ask questions about edge cases, input/output formats, example files, success criteria, and dependencies. Wait to write test prompts until you've got this part ironed out. Check available MCPs - if useful for research (searching docs, finding similar skills, looking up best practices), research in parallel via subagents if available, otherwise inline. Come prepared with context to reduce burden on the user. Write the SKILL.md Based on the user interview, fill in these components: name : Skill identifier description : When to trigger, what it does. This is the primary triggering mechanism - include both what the skill does AND specific contexts for when to use it. All "when to use" info goes here, not in the body. Note: currently Claude has a tendency to "undertrigger" skills -- to not use them when they'd be useful. To combat this, please make the skill descriptions a little bit "pushy". So for instance, instead of "How to build a simple fast dashboard to display internal Anthropic data.", you might write "How to build a simple fast dashboard to display internal Anthropic data. Make sure to use this skill whenever the user mentions dashboards, data visualization, internal metrics, or wants to display any kind of company data, even if they don't explicitly ask for a 'dashboard.'" compatibility : Required tools, dependencies (optional, rarely needed) the rest of the skill :) Skill Writing Guide Anatomy of a Skill skill-name/ ├── SKILL.md (required) │ ├── YAML frontmatter (name, description required) │ └── Markdown instructions └── Bundled Resources (optional) ├── scripts/ - Executable code for deterministic/repetitive tasks ├── references/ - Docs loaded into context as needed └── assets/ - Files used in output (templates, icons, fonts) Progressive Disclosure Skills use a three-level loading system: Metadata (name + description) - Always in context (~100 words) SKILL.md body - In context whenever skill triggers (<500 lines ideal) Bundled resources - As needed (unlimited, scripts can execute without loading) These word counts are approximate and you can feel free to go longer if needed. Key patterns: Keep SKILL.md under 500 lines; if you're approaching this limit, add an additional layer of hierarchy along with clear pointers about where the model using the skill should go next to follow up. Reference files clearly from SKILL.md with guidance on when to read them For large reference files (>300 lines), include a table of contents Domain organization : When a skill supports multiple domains/frameworks, organize by variant: cloud-deploy/ ├── SKILL.md (workflow + selection) └── references/ ├── aws.md ├── gcp.md └── azure.md Claude reads only the relevant reference file. Principle of Lack of Surprise This goes without saying, but skills must not contain malware, exploit code, or any content that could compromise system security. A skill's contents should not surprise the user in their intent if described. Don't go along with requests to create misleading skills or skills designed to facilitate unauthorized access, data exfiltration, or other malicious activities. Things like a "roleplay as an XYZ" are OK though. Writing Patterns Prefer using the imperative form in instructions. Defining output formats - You can do it like this: ## Report structure ALWAYS use this exact template: # [Title] ## Executive summary ## Key findings ## Recommendations Examples pattern - It's useful to include examples. You can format them like this (but if "Input" and "Output" are in the examples you might want to deviate a little): ## Commit message format **Example 1:** Input: Added user authentication with JWT tokens Output: feat(auth): implement JWT-based authentication Writing Style Try to explain to the model why things are important in lieu of heavy-handed musty MUSTs. Use theory of mind and try to make the skill general and not super-narrow to specific examples. Start by writing a draft and then look at it with fresh eyes and improve it. Test Cases After writing the skill draft, come up with 2-3 realistic test prompts — the kind of thing a real user would actually say. Share them with the user: [you don't have to use this exact language] "Here are a few test cases I'd like to try. Do these look right, or do you want to add more?" Then run them. Save test cases to evals/evals.json . Don't write assertions yet — just the prompts. You'll draft assertions in the next step while the runs are in progress. { "skill_name": "example-skill", "evals": [ { "id": 1, "prompt": "User's task prompt", "expected_output": "Description of expected result", "files": [] } ] } See references/schemas.md for the full schema (including the assertions field, which you'll add later). Running and evaluating test cases This section is one continuous sequence — don't stop partway through. Do NOT use /skill-test or any other testing skill. Put results in -workspace/ as a sibling to the skill directory. Within the workspace, organize results by iteration ( iteration-1/ , iteration-2/ , etc.) and within that, each test case gets a directory ( eval-0/ , eval-1/ , etc.). Don't create all of this upfront — just create directories as you go. Step 1: Spawn all runs (with-skill AND baseline) in the same turn For each test case, spawn two subagents in the same turn — one with the skill, one without. This is important: don't spawn the with-skill runs first and then come back for baselines later. Launch everything at once so it all finishes around the same time. With-skill run: Execute this task: - Skill path: - Task: - Input files: - Save outputs to: /iteration-/eval-/with_skill/outputs/ - Outputs to save: Baseline run (same prompt, but the baseline depends on context): Creating a new skill : no skill at all. Same prompt, no skill path, save to without_skill/outputs/ . Improving an existing skill : the old version. Before editing, snapshot the skill ( cp -r /skill-snapshot/ ), then point the baseline subagent at the snapshot. Save to old_skill/outputs/ . Write an eval_metadata.json for each test case (assertions can be empty for now). Give each eval a descriptive name based on what it's testing — not just "eval-0". Use this name for the directory too. If this iteration uses new or modified eval prompts, create these files for each new eval directory — don't assume they carry over from previous iterations. { "eval_id": 0, "eval_name": "descriptive-name-here", "prompt": "The user's task prompt", "assertions": [] } Step 2: While runs are in progress, draft assertions Don't just wait for the runs to finish — you can use this time productively. Draft quantitative assertions for each test case and explain them to the user. If assertions already exist in evals/evals.json , review them and explain what they check. Good assertions are objectively verifiable and have descriptive names — they should read clearly in the benchmark viewer so someone glancing at the results immediately understands what each one checks. Subjective skills (writing style, design quality) are better evaluated qualitatively — don't force assertions onto things that need human judgment. Update the eval_metadata.json files and evals/evals.json with the assertions once drafted. Also explain to the user what they'll see in the viewer — both the qualitative outputs and the quantitative benchmark. Step 3: As runs complete, capture timing data When each subagent task completes, you receive a notification containing total_tokens and duration_ms . Save this data immediately to timing.json in the run directory: { "total_tokens": 84852, "duration_ms": 23332, "total_duration_seconds": 23.3 } This is the only opportunity to capture this data — it comes through the task notification and isn't persisted elsewhere. Process each notification as it arrives rather than trying to batch them. Step 4: Grade, aggregate, and launch the viewer Once all runs are done: Grade each run — spawn a grader subagent (or grade inline) that reads agents/grader.md and evaluates each assertion against the outputs. Save results to grading.json in each run directory. The grading.json expectations array must use the fields text , passed , and evidence (not name / met / details or other variants) — the viewer depends on these exact field names. For assertions that can be checked programmatically, write and run a script rather than eyeballing it — scripts are faster, more reliable, and can be reused across iterations. Aggregate into benchmark — run the aggregation script from the skill-creator directory: python -m scripts.aggregate_benchmark /iteration-N --skill-name This produces benchmark.json and benchmark.md with pass_rate, time, and tokens for each configuration, with mean ± stddev and the delta. If generating benchmark.json manually, see references/schemas.md for the exact schema the viewer expects. Put each with_skill version before its baseline counterpart. Do an analyst pass — read the benchmark data and surface patterns the aggregate stats might hide. See agents/analyzer.md (the "Analyzing Benchmark Results" section) for what to look for — things like assertions that always pass regardless of skill (non-discriminating), high-variance evals (possibly flaky), and time/token tradeoffs. Launch the viewer with both qualitative outputs and quantitative data: nohup python /eval-viewer/generate_review.py \ /iteration-N \ --skill-name "my-skill" \ --benchmark /iteration-N/benchmark.json \ > /dev/null 2>&1 & VIEWER_PID=$! For iteration 2+, also pass --previous-workspace /iteration- . Cowork / headless environments: If webbrowser.open() is not available or the environment has no display, use --static to write a standalone HTML file instead of starting a server. Feedback will be downloaded as a feedback.json file when the user clicks "Submit All Reviews". After download, copy feedback.json into the workspace directory for the next iteration to pick up. Note: please use generate_review.py to create the viewer; there's no need to write custom HTML. Tell the user something like: "I've opened the results in your browser. There are two tabs — 'Outputs' lets you click through each test case and leave feedback, 'Benchmark' shows the quantitative comparison. When you're done, come back here and let me know." What the user sees in the viewer The "Outputs" tab shows one test case at a time: Prompt : the task that was given Output : the files the skill produced, rendered inline where possible Previous Output (iteration 2+): collapsed section showing last iteration's output Formal Grades (if grading was run): collapsed section showing assertion pass/fail Feedback : a textbox that auto-saves as they type Previous Feedback (iteration 2+): their comments from last time, shown below the textbox The "Benchmark" tab shows the stats summary: pass rates, timing, and token usage for each configuration, with per-eval breakdowns and analyst observations. Navigation is via prev/next buttons or arrow keys. When done, they click "Submit All Reviews" which saves all feedback to feedback.json . Step 5: Read the feedback When the user tells you they're done, read feedback.json : { "reviews": [ {"run_id": "eval-0-with_skill", "feedback": "the chart is missing axis labels", "timestamp": "..."}, {"run_id": "eval-1-with_skill", "feedback": "", "timestamp": "..."}, {"run_id": "eval-2-with_skill", "feedback": "perfect, love this", "timestamp": "..."} ], "status": "complete" } Empty feedback means the user thought it was fine. Focus your improvements on the test cases where the user had specific complaints. Kill the viewer server when you're done with it: kill $VIEWER_PID 2>/dev/null Improving the skill This is the heart of the loop. You've run the test cases, the user has reviewed the results, and now you need to make the skill better based on their feedback. How to think about improvements Generalize from the feedback. The big picture thing that's happening here is that we're trying to create skills that can be used a million times (maybe literally, maybe even more who knows) across many different prompts. Here you and the user are iterating on only a few examples over and over again because it helps move faster. The user knows these examples in and out and it's quick for them to assess new outputs. But if the skill you and the user are codeveloping works only for those examples, it's useless. Rather than put in fiddly overfitty changes, or oppressively constrictive MUSTs, if there's some stubborn issue, you might try branching out and using different metaphors, or recommending different patterns of working. It's relatively cheap to try and maybe you'll land on something great. Keep the prompt lean. Remove things that aren't pulling their weight. Make sure to read the transcripts, not just the final outputs — if it looks like the skill is making the model waste a bunch of time doing things that are unproductive, you can try getting rid of the parts of the skill that are making it do that and seeing what happens. Explain the why. Try hard to explain the why behind everything you're asking the model to do. Today's LLMs are smart . They have good theory of mind and when given a good harness can go beyond rote instructions and really make things happen. Even if the feedback from the user is terse or frustrated, try to actually understand the task and why the user is writing what they wrote, and what they actually wrote, and then transmit this understanding into the instructions. If you find yourself writing ALWAYS or NEVER in all caps, or using super rigid structures, that's a yellow flag — if possible, reframe and explain the reasoning so that the model understands why the thing you're asking for is important. That's a more humane, powerful, and effective approach. Look for repeated work across test cases. Read the transcripts from the test runs and notice if the subagents all independently wrote similar helper scripts or took the same multi-step approach to something. If all 3 test cases resulted in the subagent writing a create_docx.py or a build_chart.py , that's a strong signal the skill should bundle that script. Write it once, put it in scripts/ , and tell the skill to use it. This saves every future invocation from reinventing the wheel. This task is pretty important (we are trying to create billions a year in economic value here!) and your thinking time is not the blocker; take your time and really mull things over. I'd suggest writing a draft revision and then looking at it anew and making improvements. Really do your best to get into the head of the user and understand what they want and need. The iteration loop After improving the skill: Apply your improvements to the skill Rerun all test cases into a new iteration-/ directory, including baseline runs. If you're creating a new skill, the baseline is always without_skill (no skill) — that stays the same across iterations. If you're improving an existing skill, use your judgment on what makes sense as the baseline: the original version the user came in with, or the previous iteration. Launch the reviewer with --previous-workspace pointing at the previous iteration Wait for the user to review and tell you they're done Read the new feedback, improve again, repeat Keep going until: The user says they're happy The feedback is all empty (everything looks good) You're not making meaningful progress Advanced: Blind comparison For situations where you want a more rigorous comparison between two versions of a skill (e.g., the user asks "is the new version actually better?"), there's a blind comparison system. Read agents/comparator.md and agents/analyzer.md for the details. The basic idea is: give two outputs to an independent agent without telling it which is which, and let it judge quality. Then analyze why the winner won. This is optional, requires subagents, and most users won't need it. The human review loop is usually sufficient. Description Optimization The description field in SKILL.md frontmatter is the primary mechanism that determines whether Claude invokes a skill. After creating or improving a skill, offer to optimize the description for better triggering accuracy. Step 1: Generate trigger eval queries Create 20 eval queries — a mix of should-trigger and should-not-trigger. Save as JSON: [ {"query": "the user prompt", "should_trigger": true}, {"query": "another prompt", "should_trigger": false} ] The queries must be realistic and something a Claude Code or Claude.ai user would actually type. Not abstract requests, but requests that are concrete and specific and have a good amount of detail. For instance, file paths, personal context about the user's job or situation, column names and values, company names, URLs. A little bit of backstory. Some might be in lowercase or contain abbreviations or typos or casual speech. Use a mix of different lengths, and focus on edge cases rather than making them clear-cut (the user will get a chance to sign off on them). Bad: "Format this data" , "Extract text from PDF" , "Create a chart" Good: "ok so my boss just sent me this xlsx file (its in my downloads, called something like 'Q4 sales final FINAL v2.xlsx') and she wants me to add a column that shows the profit margin as a percentage. The revenue is in column C and costs are in column D i think" For the should-trigger queries (8-10), think about coverage. You want different phrasings of the same intent — some formal, some casual. Include cases where the user doesn't explicitly name the skill or file type but clearly needs it. Throw in some uncommon use cases and cases where this skill competes with another but should win. For the should-not-trigger queries (8-10), the most valuable ones are the near-misses — queries that share keywords or concepts with the skill but actually need something different. Think adjacent domains, ambiguous phrasing where a naive keyword match would trigger but shouldn't, and cases where the query touches on something the skill does but in a context where another tool is more appropriate. The key thing to avoid: don't make should-not-trigger queries obviously irrelevant. "Write a fibonacci function" as a negative test for a PDF skill is too easy — it doesn't test anything. The negative cases should be genuinely tricky. Step 2: Review with user Present the eval set to the user for review using the HTML template: Read the template from assets/eval_review.html Replace the placeholders: __EVAL_DATA_PLACEHOLDER__ → the JSON array of eval items (no quotes around it — it's a JS variable assignment) __SKILL_NAME_PLACEHOLDER__ → the skill's name __SKILL_DESCRIPTION_PLACEHOLDER__ → the skill's current description Write to a temp file (e.g., /tmp/eval_review_.html ) and open it: open /tmp/eval_review_.html The user can edit queries, toggle should-trigger, add/remove entries, then click "Export Eval Set" The file downloads to ~/Downloads/eval_set.json — check the Downloads folder for the most recent version in case there are multiple (e.g., eval_set (1).json ) This step matters — bad eval queries lead to bad descriptions. Step 3: Run the optimization loop Tell the user: "This will take some time — I'll run the optimization loop in the background and check on it periodically." Save the eval set to the workspace, then run in the background: python -m scripts.run_loop \ --eval-set \ --skill-path \ --model \ --max-iterations 5 \ --verbose Use the model ID from your system prompt (the one powering the current session) so the triggering test matches what the user actually experiences. While it runs, periodically tail the output to give the user updates on which iteration it's on and what the scores look like. This handles the full optimization loop automatically. It splits the eval set into 60% train and 40% held-out test, evaluates the current description (running each query 3 times to get a reliable trigger rate), then calls Claude to propose improvements based on what failed. It re-evaluates each new description on both train and test, iterating up to 5 times. When it's done, it opens an HTML report in the browser showing the results per iteration and returns JSON with best_description — selected by test score rather than train score to avoid overfitting. How skill triggering works Understanding the triggering mechanism helps design better eval queries. Skills appear in Claude's available_skills list with their name + description, and Claude decides whether to consult a skill based on that description. The important thing to know is that Claude only consults skills for tasks it can't easily handle on its own — simple, one-step queries like "read this PDF" may not trigger a skill even if the description matches perfectly, because Claude can handle them directly with basic tools. Complex, multi-step, or specialized queries reliably trigger skills when the description matches. This means your eval queries should be substantive enough that Claude would actually benefit from consulting a skill. Simple queries like "read file X" are poor test cases — they won't trigger skills regardless of description quality. Step 4: Apply the result Take best_description from the JSON output and update the skill's SKILL.md frontmatter. Show the user before/after and report the scores. Package and Present (only if present_files tool is available) Check whether you have access to the present_files tool. If you don't, skip this step. If you do, package the skill and present the .skill file to the user: python -m scripts.package_skill After packaging, direct the user to the resulting .skill file path so they can install it. Claude.ai-specific instructions In Claude.ai, the core workflow is the same (draft → test → review → improve → repeat), but because Claude.ai doesn't have subagents, some mechanics change. Here's what to adapt: Running test cases : No subagents means no parallel execution. For each test case, read the skill's SKILL.md, then follow its instructions to accomplish the test prompt yourself. Do them one at a time. This is less rigorous than independent subagents (you wrote the skill and you're also running it, so you have full context), but it's a useful sanity check — and the human review step compensates. Skip the baseline runs — just use the skill to complete the task as requested. Reviewing results : If you can't open a browser (e.g., Claude.ai's VM has no display, or you're on a remote server), skip the browser reviewer entirely. Instead, present results directly in the conversation. For each test case, show the prompt and the output. If the output is a file the user needs to see (like a .docx or .xlsx), save it to the filesystem and tell them where it is so they can download and inspect it. Ask for feedback inline: "How does this look? Anything you'd change?" Benchmarking : Skip the quantitative benchmarking — it relies on baseline comparisons which aren't meaningful without subagents. Focus on qualitative feedback from the user. The iteration loop : Same as before — improve the skill, rerun the test cases, ask for feedback — just without the browser reviewer in the middle. You can still organize results into iteration directories on the filesystem if you have one. Description optimization : This section requires the claude CLI tool (specifically claude -p ) which is only available in Claude Code. Skip it if you're on Claude.ai. Blind comparison : Requires subagents. Skip it. Packaging : The package_skill.py script works anywhere with Python and a filesystem. On Claude.ai, you can run it and the user can download the resulting .skill file. Updating an existing skill : The user might be asking you to update an existing skill, not create a new one. In this case: Preserve the original name. Note the skill's directory name and name frontmatter field -- use them unchanged. E.g., if the installed skill is research-helper , output research-helper.skill (not research-helper-v2 ). Copy to a writeable location before editing. The installed skill path may be read-only. Copy to /tmp/skill-name/ , edit there, and package from the copy. If packaging manually, stage in /tmp/ first , then copy to the output directory -- direct writes may fail due to permissions. Cowork-Specific Instructions If you're in Cowork, the main things to know are: You have subagents, so the main workflow (spawn test cases in parallel, run baselines, grade, etc.) all works. (However, if you run into severe problems with timeouts, it's OK to run the test prompts in series rather than parallel.) You don't have a browser or display, so when generating the eval viewer, use --static to write a standalone HTML file instead of starting a server. Then proffer a link that the user can click to open the HTML in their browser. For whatever reason, the Cowork setup seems to disincline Claude from generating the eval viewer after running the tests, so just to reiterate: whether you're in Cowork or in Claude Code, after running tests, you should always generate the eval viewer for the human to look at examples before revising the skill yourself and trying to make corrections, using generate_review.py (not writing your own boutique html code). Sorry in advance but I'm gonna go all caps here: GENERATE THE EVAL VIEWER BEFORE evaluating inputs yourself. You want to get them in front of the human ASAP! Feedback works differently: since there's no running server, the viewer's "Submit All Reviews" button will download feedback.json as a file. You can then read it from there (you may have to request access first). Packaging works — package_skill.py just needs Python and a filesystem. Description optimization ( run_loop.py / run_eval.py ) should work in Cowork just fine since it uses claude -p via subprocess, not a browser, but please save it until you've fully finished making the skill and the user agrees it's in good shape. Updating an existing skill : The user might be asking you to update an existing skill, not create a new one. Follow the update guidance in the claude.ai section above. Reference files The agents/ directory contains instructions for specialized subagents. Read them when you need to spawn the relevant subagent. agents/grader.md — How to evaluate assertions against outputs agents/comparator.md — How to do blind A/B comparison between two outputs agents/analyzer.md — How to analyze why one version beat another The references/ directory has additional documentation: references/schemas.md — JSON structures for evals.json, grading.json, etc. Repeating one more time the core loop here for emphasis: Figure out what the skill is about Draft or edit the skill Run claude-with-access-to-the-skill on test prompts With the user, evaluate the outputs: Create benchmark.json and run eval-viewer/generate_review.py to help the user review them Run quantitative evals Repeat until you and the user are satisfied Package the final skill and return it to the user. Please add steps to your TodoList, if you have such a thing, to make sure you don't forget. If you're in Cowork, please specifically put "Create evals JSON and run eval-viewer/generate_review.py so human can review test cases" in your TodoList to make sure it happens. Good luck!