skill-creator

技能创建器

此技能提供创建高效技能的指南。

关于技能

技能是模块化、独立的套件，通过提供专业知识、工作流和工具来扩展 Claude 的能力。可以将它们视为特定领域或任务的“入门指南”——它们能把 Claude 从通用型 Agent 转变为具备流程性知识的专业 Agent，而这些知识并非任何模型都能完全掌握。

技能类别

技能最适用于可重复的工作流。常见类别有三种：

1. 文档与素材创建 — 生成风格统一的文档、演示文稿、应用和设计，并内嵌风格指南、模板和质量检查清单（例如，frontend-design、docx-creator）
2. 工作流自动化 — 采用统一方法的多步骤流程，包括跨多个 MCP 服务进行协调（例如，skill-creator、sprint-planner）
3. MCP 增强 — 在现有 MCP 工具访问能力之上叠加工作流指南，教 Claude 如何有效使用服务，而不只是了解服务能做什么（例如，sentry-code-review）

核心设计原则

渐进式披露

技能采用三级加载系统，高效管理上下文：

1. 元数据（名称 + 描述） — 始终保留在上下文中（约 100 个词）
2. SKILL.md 正文 — 技能触发时加载（少于 5k 个词）
3. 捆绑资源 — Claude 按需加载（不限量*）

*不限量是因为脚本无需读入上下文窗口即可执行。

可组合性

Claude 可以同时加载多个技能。技能应能与其他技能协同工作，不要假设该技能是唯一可用的能力。

可移植性

技能在 Claude.ai、Claude Code 和 API 中的运行方式完全相同。创建一次技能，即可在所有平台上使用，无需修改。

技能 + MCP

对于 MCP 集成，技能会在工具访问能力之上添加一层知识：

	MCP（连接能力）	技能（知识）
提供内容	工具访问能力和实时数据	工作流和最佳实践
回答问题	Claude 能做什么	Claude 应如何操作

如果没有技能，连接 MCP 服务的用户就必须自行摸索工作流，导致结果不一致，并增加支持负担。技能内嵌最佳实践，使其能够自动启用。

请参阅 references/workflow-patterns.md，了解五种经过验证的模式（顺序编排、多 MCP 协调、迭代优化、上下文感知的工具选择、领域专属智能）。

技能结构

每个技能都包含一个必需的 SKILL.md 文件，以及可选的捆绑资源：

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter metadata (required)
│   │   ├── name: (required)
│   │   └── description: (required)
│   └── Markdown instructions (required)
└── Bundled Resources (optional)
    ├── scripts/          - Executable code (Python/Bash/etc.)
    ├── references/       - Documentation loaded into context as needed
    └── assets/           - Files used in output (templates, icons, fonts, etc.)

重要：请勿在技能文件夹内包含 README.md。 所有文档都应放在 SKILL.md 或 references/ 中。托管该技能的 GitHub 仓库可以在仓库根目录放置 README，供访客阅读，但不得将其放入技能文件夹。

SKILL.md

元数据质量： YAML frontmatter 中的 name 和 description 决定 Claude 何时使用该技能。请具体说明技能的功能和使用时机。使用第三人称表述（例如，“应在……时使用此技能”，而不是“在……时使用此技能”）。

YAML Frontmatter 字段：

---
name: skill-name-in-kebab-case          # required; lowercase, hyphens only, max 64 chars
description: What it does and when.     # required; WHAT + WHEN, max 1024 chars
license: MIT                            # optional; for open-source skills
allowed-tools: "Bash(python:*) WebFetch" # optional; restrict available tools
compatibility: Requires internet access  # optional; environment requirements, 1-500 chars
metadata:                               # optional; custom key-value pairs
  author: Your Name
  version: 1.0.0
  mcp-server: your-service-name
  tags: [automation, productivity]
---

安全限制：

• frontmatter 中任何位置都不得包含 XML 尖括号（< >）（它会出现在系统提示词中）
• 以 "claude" 或 "anthropic" 为前缀的名称已被保留

编写有效的描述 — 结构：[功能] + [使用时机] + [关键能力]

# Good — specific trigger phrases
description: Manages Linear project workflows including sprint planning and task
  creation. Use when user mentions "sprint", "Linear tasks", "project planning",
  or asks to "create tickets".

# Good — file types + trigger phrases
description: Analyzes Figma design files and generates developer handoff docs.
  Use when user uploads .fig files or asks for "design specs" or
  "design-to-code handoff".

# Bad — too vague, no triggers
description: Helps with projects.

为避免过度触发，请明确列出排除情况：

description: Advanced CSV statistical analysis for regression, clustering, and
  modeling. Do NOT use for simple data exploration (use data-viz skill instead).

捆绑资源（可选）

脚本（scripts/）

用于需要确定性可靠性或会被反复重写的任务的可执行代码（Python/Bash 等）。

• 何时纳入：相同代码会被反复重写，或确定性正确至关重要时
• 示例：用于 PDF 旋转任务的 scripts/rotate_pdf.py
• 优势：节省 token、结果确定，无需加载到上下文中即可执行
• 注意：修补脚本或针对特定环境进行调整时，仍可能需要读取脚本

参考资料（references/）

按需加载到上下文中，为 Claude 的工作流程和思考提供参考的文档和资料。

• 何时纳入：Claude 工作时需要查阅的文档
• 示例：数据库架构 references/schema.md、API 规范 references/api_docs.md、公司政策 references/policies.md
• 最佳实践：如果文件较大（>10k 个词），请在 SKILL.md 中加入 grep 搜索模式
• 避免重复：信息应放在 SKILL.md 或参考资料文件中，而不是两者兼有。保持 SKILL.md 精简——将详细的参考资料、架构和示例移至参考资料文件。

资源文件（assets/）

用于 Claude 生成的输出、不会加载到上下文中的文件。

• 何时纳入：技能需要在最终输出中使用文件时
• 示例：品牌资源 assets/logo.png、PowerPoint 模板 assets/slides.pptx、HTML/React 样板代码 assets/frontend-template/
• 优势：将输出资源与文档分开，Claude 无需将文件加载到上下文中即可使用

技能创建流程

创建技能时，请按顺序遵循以下步骤，只有在理由充分时才跳过。

步骤 1：通过具体示例了解技能

只有在已经明确了解使用模式时才跳过。

通过有针对性地提问收集 2–3 个具体用例——避免一次向用户提出过多问题：

• “此技能应支持哪些功能？”
• “能否举例说明如何使用此技能？”
• “用户会说什么来触发此技能？”

构建前还要定义成功标准：

量化目标（粗略基准）：

• 在约 90% 的相关查询中触发技能（使用 10–20 个有代表性的提示进行测试）
• 每个工作流的工具调用次数保持一致（比较启用和未启用技能时的情况）
• 每个工作流的 API 调用失败次数为 0（如果依赖 MCP）

定性目标：

• 用户无需在工作流中途引导 Claude 改变方向
• 不同会话中的结果保持一致
• 新用户只需少量指导，首次尝试就能完成任务

当功能和成功标准都已明确时，即可结束。

步骤 2：规划可复用的技能内容

要将具体示例转化为有效技能，请按以下方式分析每个示例：

1. 考虑如何从头执行
2. 确定反复执行时哪些脚本、参考资料和资源文件会有所帮助

用例	分析	资源
“旋转此 PDF”	每次都要重写相同代码	scripts/rotate_pdf.py
“帮我构建一个待办事项应用”	每次都要使用相同的 HTML/React 样板代码	assets/hello-world/ 模板
“有多少用户登录了？”	每次都要重新查找表架构	references/schema.md
“通过 Sentry 审查此 PR”	复杂的多 MCP 工作流	SKILL.md 中的结构化步骤

生成一份要纳入的可复用资源清单。

步骤 3：初始化技能

如果技能已经存在且只需迭代，则跳过。

从头创建新技能时，始终运行 init_skill.py 脚本：

scripts/init_skill.py <skill-name> --path <output-directory>

该脚本会：

• 创建结构规范的技能目录
• 生成包含 frontmatter 和 TODO 占位符的 SKILL.md 模板
• 创建示例资源目录：scripts/、references/ 和 assets/
• 在每个目录中添加可自定义或删除的示例文件

初始化后，根据需要自定义或删除生成的 SKILL.md 和示例文件。

步骤 4：编辑技能

该技能是为另一个 Claude 实例创建的。重点关注流程知识、特定领域的细节和不易察觉的可复用资源。

从可复用的技能内容开始

先实现步骤 2 中确定的资源：scripts/、references/ 和 assets/ 文件。特定领域的内容可能需要用户输入（例如品牌资源、公司政策、API 文档）。

删除技能不需要的示例文件——初始化脚本会创建占位文件来展示结构，但大多数技能并不需要全部示例文件。

更新 SKILL.md

写作风格： 使用祈使式／不定式形式（动词开头），不要使用第二人称。写“要完成 X，请执行 Y”，而不是“你应该执行 Y”。这样能保持内容一致清晰，便于 AI 理解。

完成 SKILL.md 时，请回答以下问题：

1. 技能的用途是什么？
2. 何时应使用该技能？
3. Claude 应如何使用随附的各项资源？

关键指令指南：

• 将关键指令放在靠前的位置；使用 ## Critical 或 ## Important 标题
• 对于必须遵循的验证，优先使用确定性脚本，而不是自然语言指令——代码可靠，而自然语言解释并非如此：

  CRITICAL: Before calling create_project, run scripts/validate_input.py
  

• 将详细文档移至 references/ 并链接到这些文档；将 SKILL.md 控制在 5,000 个单词以内
• 对于顺序重要的步骤，明确编号并记录各步骤之间的依赖关系

对于增强 MCP 能力的技能，还需包含：

• MCP 服务中的准确工具名称（区分大小写）
• 每个工作流阶段的验证
• 常见 MCP 故障的错误处理方法（身份验证、速率限制、超时）

步骤 5：测试技能

运行以下三类测试：

1. 触发测试——技能是否会在恰当的时机加载？

• 测试应触发技能的明显查询
• 测试这些查询的改述版本
• 验证技能不会因无关主题而触发
• 调试提示：询问 Claude“你会在什么时候使用 [技能名称] 技能？”——Claude 会复述技能描述，从而暴露其中的不足

2. 功能测试——技能能否生成正确的输出？

• 验证是否生成有效输出
• 确认 API/MCP 调用成功（如适用）
• 测试错误处理路径
• 覆盖边界情况

3. 性能对比——技能能否改善结果？

• 使用和不使用技能运行相同任务
• 对比：往返消息数量、失败的 API 调用次数、消耗的 token 数

有效的迭代策略： 专注于一个有挑战性的任务，直到 Claude 成功，然后将有效的方法提炼到技能中。打下可行的基础后，再扩展多个测试用例以提高覆盖率。

步骤 6：打包技能

scripts/package_skill.py <path/to/skill-folder>

可选输出目录：

scripts/package_skill.py <path/to/skill-folder> ./dist

打包脚本会：

1. 验证技能，检查以下内容：

   • YAML frontmatter 格式和必需字段
   • 命名规范和目录结构
   • 描述的完整性和质量
   • 技能文件夹内没有 README.md

2. 如果验证通过，则打包为可分发的 zip 文件

如果验证失败，请修复所有验证错误并重新运行。

步骤 7：分发

面向个人 / 开源项目：

1. 托管在 GitHub 上，并提供清晰的仓库级 README（面向访客，而非放在技能文件夹内）
2. 对于增强 MCP 的技能，在 MCP 文档中链接到该技能，并说明两者结合使用的价值
3. 提供安装指南，引导用户前往 Settings > Capabilities > Skills > Upload

面向组织（2026 年 1 月及以后）：

• 管理员可以通过 Claude Console 在整个工作区部署技能
• 支持自动更新和集中管理

面向程序化 / API 使用：

• 使用 /v1/skills 端点列出和管理技能
• 通过 container.skills 参数将技能添加到 Messages API 请求中
• 需要启用 Code Execution Tool 测试版

步骤 8：迭代

测试后，根据观察到的信号进行改进：

触发不足（相关查询未加载技能，用户需要手动调用）：

• 在描述中添加更具体的触发短语
• 纳入技术术语和用户实际使用的确切说法
• 询问 Claude“你会在什么时候使用 [skill name]？”，以发现盲点

触发过度（无关查询也加载技能，用户将其禁用）：

• 添加排除触发条件（“不要用于……”）
• 使用更具体的措辞缩小描述范围

执行问题（结果不一致、用户需要修正输出、MCP 调用失败）：

• 将关键指令移至 SKILL.md 的顶部
• 用确定性的验证脚本替换含糊的措辞
• 明确步骤顺序和错误处理方式

故障排除

技能无法上传

错误	原因	修复方法
"Invalid frontmatter"	缺少 --- 分隔符或引号未闭合	添加分隔符，修正 YAML 语法
"Invalid skill name"	名称中包含空格、大写字母或下划线	重命名为 kebab-case
"Could not find SKILL.md"	文件名不是准确的 SKILL.md	重命名（区分大小写）

未遵循指令

• 将关键指令移至顶部；使用 ## Critical / ## Important 标题
• 用可执行脚本替换基于语言的验证（代码具有确定性）
• 保持指令简洁明了——将详细内容移至 references/
• 如果 Claude 跳过步骤：添加“请慢慢来，质量优先于速度。不要跳过验证步骤。”（将其放在用户提示词中，而不是 SKILL.md 中，效果最好）

技能上下文过大 / 响应缓慢

• 将 SKILL.md 控制在 5,000 个词以内
• 将详细文档移至 references/，并在 SKILL.md 中链接到这些文档
• 同时启用的技能数量限制在 20–50 个

资源

• Anthropic 技能文档
• 技能示例仓库 — anthropics/skills
• 技能最佳实践指南
• Claude 开发者 Discord — 社区支持
• references/workflow-patterns.md — MCP 和自动化工作流的五种成熟模式