关联主题:: Claude Skills说明(2026.01.13)
同级:: Planning with Files
下一级::
Skill-creator：Claude Code 技能创建指南
什么是 Skill-creator？
skill-creator 是 Claude Code 官方提供的技能创建指导工具，用于帮助用户创建或更新自定义技能（Skills）。通过这个技能，你可以将 Claude 从通用助手转变为具备专业领域知识和工作流程的专家助手。
核心概念
什么是 Skills？
Skills 是模块化的、自包含的扩展包，通过提供专业化的知识、工作流程和工具来扩展 Claude 的能力。可以把它们看作是特定领域或任务的”培训手册”——它们让 Claude 具备了模型本身无法完全掌握的程序性知识。
Skills 提供什么？
- 专业化工作流程 - 特定领域的多步骤流程
- 工具集成 - 处理特定文件格式或 API 的指令
- 领域专业知识 - 公司特定知识、数据结构、业务逻辑
- 打包资源 - 用于复杂和重复任务的脚本、参考文档和资源文件
核心设计原则
1. 简洁至上
上下文窗口是公共资源，需要被 Claude 的系统提示、对话历史、其他技能的元数据以及实际的用户请求共享。
默认假设：Claude 已经非常聪明。 只添加 Claude 不知道的上下文。对每一部分信息都要质疑：“Claude 真的需要这个解释吗？” 和 “这一段值得它的 token 成本吗？”
优先使用简洁的示例，而不是冗长的解释。
2. 设定适当的自由度
根据任务的脆弱性和可变性匹配具体程度：
- 高自由度（文本指令）：当多种方法都有效、决策依赖上下文或启发式指导方法时使用
- 中等自由度（伪代码或带参数的脚本）：当存在首选模式、可接受一些变化或配置影响行为时使用
- 低自由度（特定脚本，少量参数）：当操作容易出错、一致性至关重要或必须遵循特定序列时使用
3. 渐进式信息披露
Skills 使用三级加载系统来有效管理上下文：
- 元数据（name + description） - 始终在上下文中（约100词）
- SKILL.md 主体 - 当技能触发时加载（<5k词）
- 打包资源 - Claude 根据需要加载（无限制，因为脚本可以在不读入上下文的情况下执行）
Skill 的结构
每个 Skill 由必需的 SKILL.md 文件和可选的打包资源组成：
skill-name/
├── SKILL.md (必需)
│ ├── YAML frontmatter 元数据 (必需)
│ │ ├── name: (必需)
│ │ └── description: (必需)
│ └── Markdown 指令 (必需)
└── 打包资源 (可选)
├── scripts/ - 可执行代码（Python/Bash等）
├── references/ - 需要时加载到上下文的文档
└── assets/ - 输出中使用的文件（模板、图标、字体等）
SKILL.md（必需）
- Frontmatter（YAML）：包含
name和description字段。这些是 Claude 用来判断何时使用技能的唯一字段，因此清晰全面地描述技能是什么以及何时应该使用它非常重要。 - Body（Markdown）：使用技能的指令和指导。仅在技能触发后加载。
打包资源（可选）
Scripts（scripts/）
可执行代码，用于需要确定性可靠性或重复编写的任务。
- 何时包含：当同样的代码被重复编写或需要确定性可靠性时
- 示例：
scripts/rotate_pdf.py用于 PDF 旋转任务 - 优势：Token 高效、确定性、可能在不加载到上下文的情况下执行
References（references/）
文档和参考材料，旨在根据需要加载到上下文中，以指导 Claude 的过程和思考。
- 何时包含：用于 Claude 在工作时应参考的文档
- 示例：
references/finance.md用于财务模式、references/api_docs.md用于 API 规范 - 用途：数据库结构、API 文档、领域知识、公司政策、详细的工作流程指南
- 最佳实践：如果文件很大（>10k 词），在 SKILL.md 中包含 grep 搜索模式
Assets（assets/）
不打算加载到上下文中，而是在 Claude 产生的输出中使用的文件。
- 何时包含：当技能需要在最终输出中使用的文件时
- 示例：
assets/logo.png用于品牌资产、assets/slides.pptx用于 PowerPoint 模板 - 用途：模板、图像、图标、样板代码、字体、会被复制或修改的示例文档
Skill 创建流程
第 1 步：通过具体示例理解技能
通过直接的用户示例或经过用户反馈验证的生成示例，清楚地了解技能的使用方式。
相关问题包括：
- “这个技能应该支持什么功能？”
- “你能给一些如何使用这个技能的例子吗？”
- “什么情况下用户会说触发这个技能？“
第 2 步：规划可重用的技能内容
通过分析每个示例：
- 考虑如何从头执行示例
- 确定在重复执行这些工作流程时哪些脚本、参考文档和资源会有帮助
第 3 步：初始化技能
运行 init_skill.py 脚本创建技能模板：
scripts/init_skill.py <skill-name> --path <output-directory>脚本会：
- 在指定路径创建技能目录
- 生成带有适当 frontmatter 和 TODO 占位符的 SKILL.md 模板
- 创建示例资源目录：
scripts/、references/和assets/
第 4 步：编辑技能
学习经过验证的设计模式
根据技能需求查阅有用的指南：
- 多步骤流程：参见
references/workflows.md了解顺序工作流程和条件逻辑 - 特定输出格式或质量标准：参见
references/output-patterns.md了解模板和示例模式
实现可重用内容
从确定的可重用资源开始：scripts/、references/ 和 assets/ 文件。
添加的脚本必须通过实际运行来测试，以确保没有错误并且输出符合预期。
更新 SKILL.md
编写指南：始终使用祈使句/不定式形式。
Frontmatter
编写包含 name 和 description 的 YAML frontmatter：
name：技能名称description：这是技能的主要触发机制，帮助 Claude 理解何时使用技能- 包含技能的功能和使用的具体触发器/上下文
- 在这里包含所有”何时使用”信息 - 不在正文中
- 示例：
docx技能的描述：“Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. Use when Claude needs to work with professional documents (.docx files) for: (1) Creating new documents, (2) Modifying or editing content, (3) Working with tracked changes, (4) Adding comments, or any other document tasks”
Body
编写使用技能及其打包资源的指令。
第 5 步：打包技能
完成开发后，将技能打包为可分发的 .skill 文件：
scripts/package_skill.py <path/to/skill-folder>可选指定输出目录：
scripts/package_skill.py <path/to/skill-folder> ./dist打包脚本将：
-
验证技能，检查：
- YAML frontmatter 格式和必填字段
- 技能命名约定和目录结构
- 描述的完整性和质量
- 文件组织和资源引用
-
打包技能（如果验证通过），创建一个以技能命名的 .skill 文件
第 6 步：迭代
在测试技能后，用户可能会要求改进。迭代工作流程：
- 在实际任务中使用技能
- 注意困难或低效之处
- 确定应如何更新 SKILL.md 或打包资源
- 实施更改并再次测试
渐进式披露设计模式
模式 1：高级指南与引用
# PDF 处理
## 快速开始
使用 pdfplumber 提取文本：
[代码示例]
## 高级功能
- **表单填写**：参见 [FORMS.md](FORMS.md) 获取完整指南
- **API 参考**：参见 [REFERENCE.md](REFERENCE.md) 获取所有方法
- **示例**：参见 [EXAMPLES.md](EXAMPLES.md) 获取常见模式Claude 仅在需要时加载 FORMS.md、REFERENCE.md 或 EXAMPLES.md。
模式 2：特定领域组织
对于具有多个领域的技能，按领域组织内容以避免加载无关上下文：
bigquery-skill/
├── SKILL.md（概述和导航）
└── reference/
├── finance.md（收入、计费指标）
├── sales.md（机会、管道）
├── product.md（API 使用、功能）
└── marketing.md（活动、归因）
当用户询问销售指标时，Claude 仅读取 sales.md。
模式 3：条件详情
显示基本内容，链接到高级内容：
# DOCX 处理
## 创建文档
使用 docx-js 创建新文档。参见 [DOCX-JS.md](DOCX-JS.md)。
## 编辑文档
对于简单编辑，直接修改 XML。
**对于跟踪更改**：参见 [REDLINING.md](REDLINING.md)
**对于 OOXML 详情**：参见 [OOXML.md](OOXML.md)Claude 仅在用户需要这些功能时读取 REDLINING.md 或 OOXML.md。
输出模式
模板模式
为输出格式提供模板。根据需求匹配严格程度。
对于严格要求（如 API 响应或数据格式）：
## 报告结构
始终使用这个确切的模板结构：
# [分析标题]
## 执行摘要
[关键发现的一段概述]
## 主要发现
- 发现 1 及支持数据
- 发现 2 及支持数据
- 发现 3 及支持数据
## 建议
1. 具体可操作的建议
2. 具体可操作的建议对于灵活指导（当适应有用时）：
## 报告结构
这是一个合理的默认格式，但请根据最佳判断调整：
# [分析标题]
## 执行摘要
[概述]
## 主要发现
[根据发现调整部分]
## 建议
[根据具体情况定制]
根据特定分析类型调整部分。示例模式
对于输出质量取决于看到示例的技能，提供输入/输出对：
## 提交消息格式
按照以下示例生成提交消息：
**示例 1：**
输入：添加了使用 JWT 令牌的用户身份验证
输出：feat(auth): implement JWT-based authentication
Add login endpoint and token validation middleware
**示例 2：**
输入：修复了报告中日期显示不正确的错误
输出：
fix(reports): correct date formatting in timezone conversion
Use UTC timestamps consistently across report generation
遵循此风格：type(scope): 简短描述，然后详细解释。
使用场景
何时使用 skill-creator？
当你想要：
- 创建新技能：为特定工作流程或领域创建自定义技能
- 更新现有技能：改进或扩展现有技能的功能
- 学习技能设计：了解如何有效地构建 Claude Code 技能
典型应用
-
PDF 编辑器技能：处理”帮我旋转这个 PDF”等查询
- 创建
scripts/rotate_pdf.py脚本
- 创建
-
前端 Web 应用构建器：处理”构建一个待办事项应用”等查询
- 创建
assets/hello-world/模板，包含样板 HTML/React 项目文件
- 创建
-
BigQuery 技能：处理”今天有多少用户登录？“等查询
- 创建
references/schema.md文件，记录表结构
- 创建
最佳实践
- 保持 SKILL.md 简洁：将主体保持在 500 行以下以最小化上下文膨胀
- 测试脚本：添加的脚本必须通过实际运行来测试
- 避免重复：信息应存在于 SKILL.md 或参考文件中，而不是两者都有
- 使用祈使句：始终使用祈使/不定式形式编写
- 避免嵌套引用：保持引用从 SKILL.md 一级深度
- 为长参考文件添加目录：对于超过 100 行的文件，在顶部包含目录
不应包含的内容
技能应仅包含直接支持其功能的必要文件。不要创建多余的文档或辅助文件，包括：
- README.md
- INSTALLATION_GUIDE.md
- QUICK_REFERENCE.md
- CHANGELOG.md
- 等等
技能应仅包含 AI 代理完成手头工作所需的信息。
总结
skill-creator 是一个强大的工具，让你能够将 Claude Code 定制为满足特定需求的专业助手。通过遵循渐进式披露原则、保持简洁并提供适当的结构，你可以创建高效、易用且功能强大的自定义技能。
记住：好的技能不是关于提供所有可能的信息，而是关于在正确的时间提供正确的信息。
相关资源
- Claude Code 官方文档
- Skill 示例库
- 技能开发社区讨论