create-skill

Skill Creator

此 Skill 提供创建有效 Skill 的指导。

关于 Skills

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

Skills 提供什么

1. 专业工作流——针对特定领域的多步骤流程
2. 工具集成——使用特定文件格式或 API 的说明
3. 领域专业知识——公司专属知识、架构、业务逻辑
4. 配套资源——用于复杂且重复性任务的脚本、参考资料和资源

核心原则

简洁为要

上下文窗口是一种公共资源。Skills 会与其他所有所需内容共享上下文窗口：系统提示词、对话历史、其他 Skills 的元数据，以及实际的用户请求。

默认假设：你已经具备相当丰富的能力。 只添加你尚不具备的上下文。逐条审视信息：“真的需要这段说明吗？”以及“这段文字值得占用这些 token 吗？”

与其提供冗长的说明，不如优先提供简洁的示例。

设定适当的自由度

根据任务的脆弱性和可变性，调整具体程度：

高自由度（基于文本的说明）：适用于存在多种有效方法、决策取决于上下文或需要根据启发式方法判断的情况。

中等自由度（带参数的伪代码或脚本）：适用于存在首选模式、允许一定变化或配置会影响行为的情况。

低自由度（参数较少的特定脚本）：适用于操作脆弱且容易出错、需要保持一致性或必须遵循特定步骤的情况。

把自己想象成正在探索一条路径：狭窄且两侧是悬崖的桥需要明确的护栏（低自由度），而开阔的原野则允许你选择多种路线（高自由度）。

Skill 的结构

每个 Skill 都包含一个必需的 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 intended to be loaded into context as needed
    └── assets/           - Files used in output (templates, icons, fonts, etc.)

SKILL.md（必需）

每个 SKILL.md 都包含：

• Frontmatter（YAML）：包含 name 和 description 字段。这是你用来判断何时使用 Skill 的唯一字段，因此清楚、全面地说明 Skill 的用途及其适用场景非常重要。
• 正文（Markdown）：使用 Skill 的说明和指导。只有在 Skill 被触发后才会加载（如果会加载的话）。

配套资源（可选）

脚本（scripts/）

用于需要确定性可靠性或经常需要重写的任务的可执行代码。

• 适用场景：需要反复重写相同代码，或需要确定性可靠性
• 示例：用于 PDF 旋转任务的 scripts/rotate_pdf.sh
• 优点：节省 token、结果确定，可在不加载到上下文中的情况下执行
• 注意：你可能仍需阅读脚本，以便进行修补或针对环境进行调整

参考资料（references/）

文档和参考材料，旨在按需加载到上下文中，为你的流程和思考提供参考。

• 包含时机：需要在工作过程中查阅的文档
• 示例：用于财务架构的 references/finance.md、公司 NDA 模板 references/mnda.md、公司政策 references/policies.md、API 规范 references/api_docs.md
• 使用场景：数据库架构、API 文档、领域知识、公司政策、详细的工作流指南
• 优势：让 SKILL.md 保持精简，仅在你判断需要时加载
• 最佳实践：如果文件较大（超过 10k 字），请在 SKILL.md 中加入 grep 搜索模式
• 避免重复：信息应仅存放在 SKILL.md 或参考文件中，不要两处重复。除非相关内容确实是技能的核心，否则详细信息优先放在参考文件中；这样既能让 SKILL.md 保持精简，也能让信息易于查找，而不会占用过多上下文窗口。SKILL.md 中只保留必要的流程指令和工作流指南；将详细的参考材料、架构和示例移至参考文件。

资源文件（assets/）

不用于加载到上下文中，而是在生成输出时使用的文件。

• 包含时机：技能需要在最终输出中使用文件时
• 示例：品牌资源 assets/logo.png、PowerPoint 模板 assets/slides.pptx、HTML/React 样板代码 assets/frontend-template/、排版字体 assets/font.ttf
• 使用场景：模板、图片、图标、样板代码、字体、会复制或修改的示例文档
• 优势：将输出资源与文档分开，无需加载到上下文中也能使用这些文件

技能中不应包含的内容

技能只应包含直接支持其功能所必需的文件。请勿创建多余的文档或辅助文件，包括：

• README.md
• INSTALLATION_GUIDE.md
• QUICK_REFERENCE.md
• CHANGELOG.md
• 等等

技能只应包含 AI Agent 完成当前任务所需的信息。不应包含有关创建技能的过程、设置和测试流程、面向用户的文档等额外背景信息。创建额外的文档文件只会增加杂乱和困惑。

渐进式披露设计原则

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

1. 元数据（名称 + 描述）——始终位于上下文中（约 100 个词）
2. SKILL.md 正文——技能触发时加载（少于 5k 个词）
3. 捆绑资源——Claude 按需加载（无限制，因为脚本无需读入上下文窗口即可执行）

渐进式披露模式

将 SKILL.md 正文控制在必要内容范围内，并保持在 500 行以内，以尽量减少上下文膨胀。接近此限制时，将内容拆分到单独的文件中。将内容拆分到其他文件时，务必在 SKILL.md 中引用这些文件，并清楚说明何时阅读，确保技能的读者知道这些文件的存在及其使用时机。

核心原则： 当一项技能支持多种变体、框架或选项时，只在 SKILL.md 中保留核心工作流和选择指南。将特定变体的详细信息（模式、示例、配置）移到单独的参考文件中。

模式 1：带有参考文件的高级指南

# PDF Processing

## Quick start

Extract text with pdfplumber:
[code example]

## Advanced features

- **Form filling**: See [FORMS.md](FORMS.md) for complete guide
- **API reference**: See [REFERENCE.md](REFERENCE.md) for all methods
- **Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns

仅在需要时加载 FORMS.md、REFERENCE.md 或 EXAMPLES.md。

模式 2：按领域组织

对于涵盖多个领域的技能，按领域组织内容，避免加载无关上下文：

bigquery-skill/
├── SKILL.md (overview and navigation)
└── reference/
    ├── finance.md (revenue, billing metrics)
    ├── sales.md (opportunities, pipeline)
    ├── product.md (API usage, features)
    └── marketing.md (campaigns, attribution)

当用户询问销售指标时，只需阅读 sales.md。

同样，对于支持多个框架或变体的技能，也应按变体组织：

cloud-deploy/
├── SKILL.md (workflow + provider selection)
└── references/
    ├── aws.md (AWS deployment patterns)
    ├── gcp.md (GCP deployment patterns)
    └── azure.md (Azure deployment patterns)

当用户选择 AWS 时，只需阅读 aws.md。

模式 3：条件式详细内容

展示基本内容，并链接到高级内容：

# DOCX Processing

## Creating documents

Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).

## Editing documents

For simple edits, modify the XML directly.

**For tracked changes**: See [REDLINING.md](REDLINING.md)
**For OOXML details**: See [OOXML.md](OOXML.md)

只有在用户需要这些功能时，才阅读 REDLINING.md 或 OOXML.md。

重要指南：

• 避免多层嵌套引用——引用文件应距 SKILL.md 仅一层。所有参考文件都应由 SKILL.md 直接链接。
• 为较长的参考文件设置结构——对于超过 100 行的文件，在顶部添加目录，以便预览时了解其完整范围。

技能创建流程

创建技能包括以下步骤：

1. 通过具体示例了解技能
2. 规划可复用的技能内容（脚本、参考资料、资源）
3. 初始化技能
4. 编辑技能（实现资源并编写 SKILL.md）
5. 根据实际使用情况迭代

按顺序执行这些步骤，仅在有明确理由表明不适用时才跳过。

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

只有在已经明确了解该技能的使用模式时，才跳过此步骤。即使是在处理现有技能时，此步骤仍然很有价值。

要创建有效的技能，必须清楚了解该技能的具体使用方式。这种了解可以来自用户直接提供的示例，也可以来自经用户反馈验证的生成示例。

例如，在构建图像编辑技能时，相关问题包括：

• “图像编辑技能应该支持哪些功能？编辑、旋转，还有其他功能吗？”
• “能否提供一些这项技能的使用示例？”
• “我能想到用户可能会提出诸如‘去除这张图片中的红眼’或‘旋转这张图片’之类的请求。你觉得这项技能还会有哪些其他用法？”
• “用户说什么时应该触发这项技能？”

为避免让用户应接不暇，不要在一条消息中提出太多问题。先问最重要的问题，再根据需要继续追问，以提高效果。

当你清楚了解这项技能应支持的功能后，结束此步骤。

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

要将具体示例转化为有效的技能，请逐一分析每个示例：

1. 考虑如何从头开始执行该示例
2. 确定反复执行这些工作流时，哪些脚本、参考资料和资源会有所帮助

示例：构建 edit-pdf 技能来处理“帮我旋转这个 PDF”之类的请求时，分析表明：

1. 每次旋转 PDF 都需要重新编写相同的代码
2. 将 scripts/rotate_pdf.sh 脚本存放在技能中会很有帮助

示例：设计 build-frontend-webapp 技能来处理“帮我构建一个待办事项应用”或“帮我构建一个跟踪步数的仪表板”之类的请求时，分析表明：

1. 每次编写前端 Web 应用都需要相同的 HTML/React 样板代码
2. 将包含样板 HTML/React 项目文件的 assets/hello-world/ 模板存放在技能中会很有帮助

示例：构建 query-bigquery 技能来处理“今天有多少用户登录？”之类的请求时，分析表明：

1. 每次查询 BigQuery 都需要重新查找表的架构和关系
2. 将记录表架构的 references/schema.md 文件存放在技能中会很有帮助

要确定技能的内容，请分析每个具体示例，并列出要包含的可复用资源：脚本、参考资料和资源文件。

第 3 步：初始化技能

现在可以开始实际创建技能了。

仅当要开发的技能已存在，且需要迭代或打包时，才跳过此步骤。在这种情况下，请继续下一步。

技能命名规范

技能名称始终使用动词，以清楚说明技能执行的操作：

• ✅ 好：execute-plan、create-report、analyze-logs、deploy-app
• ❌ 不好：plan-executor、report-creator、log-analyzer、app-deployer

动词开头的命名能让人立即明白技能的用途，也符合技能说明中通用的祈使式/不定式形式。

技能位置

默认情况下，创建项目本地技能，除非用户明确要求创建全局技能。

从头创建新技能时，请将其放在项目本地技能目录中：

• 项目本地（默认）：{{local_skills_path}}/<skill-name>/——技能仅适用于当前项目，不会影响其他项目。这是大多数技能的安全默认选项。
• 全局（仅在明确要求时）：{{global_skills_path}}/<skill-name>/——技能可在所有项目中使用。仅当用户明确要求创建全局技能，或技能确实适用于所有项目时，才使用此位置。

目录结构应包含：

• 带有 YAML frontmatter（name、description）和 Markdown 正文的 SKILL.md
• 用于存放可执行代码（例如 process.sh、validate.sh）的 scripts/ 目录
• 用于存放按需加载的文档的 references/ 目录
• 用于存放输出文件的 assets/ 目录

初始化示例（默认项目本地）：

mkdir -p {{local_skills_path}}/edit-pdf/{scripts,references,assets}
cat > {{local_skills_path}}/edit-pdf/SKILL.md << 'EOF'
---
name: edit-pdf
description: TODO - Describe what this skill does and when to use it
---

# Edit PDF

TODO - Add skill instructions here
EOF

cat > {{local_skills_path}}/edit-pdf/scripts/rotate.sh << 'EOF'
#!/bin/bash
# Rotate PDF using pdftk
pdftk "$1" cat 1-endright output "$2"
EOF

chmod +x {{local_skills_path}}/edit-pdf/scripts/rotate.sh

如果用户明确要求创建全局技能，请改用以下方式：

mkdir -p {{global_skills_path}}/edit-pdf/{scripts,references,assets}
cat > {{global_skills_path}}/edit-pdf/SKILL.md << 'EOF'
---
name: edit-pdf
description: TODO - Describe what this skill does and when to use it
---

# Edit PDF

TODO - Add skill instructions here
EOF

cat > {{global_skills_path}}/edit-pdf/scripts/rotate.sh << 'EOF'
#!/bin/bash
# Rotate PDF using pdftk
pdftk "$1" cat 1-endright output "$2"
EOF

chmod +x {{global_skills_path}}/edit-pdf/scripts/rotate.sh

初始化后，根据需要自定义生成的文件。

第 4 步：编辑技能

编辑（新生成或现有的）技能时，请记住，创建该技能是为了让另一个 AI Agent 实例使用。请纳入有益且不显而易见的信息。考虑哪些程序性知识、领域特定细节或可复用资源能帮助另一个 Agent 实例更有效地执行这些任务。

学习经实践验证的设计模式

根据技能需求，参考以下实用指南：

• 多步骤流程：参阅 references/workflows.md，了解顺序工作流和条件逻辑
• 特定输出格式或质量标准：参阅 references/output-patterns.md，了解模板和示例模式

这些文件包含经过验证的最佳实践，可帮助有效设计技能。

从可复用的技能内容着手

开始实现时，先使用上文确定的可复用资源：scripts/、references/ 和 assets/ 文件。请注意，此步骤可能需要用户提供输入。例如，实现 brand-guidelines 技能时，用户可能需要提供品牌素材或模板，以存放在 assets/ 中；也可能需要提供文档，以存放在 references/ 中。

添加的脚本必须通过实际运行进行测试，以确保没有错误，且输出符合预期。如果有许多相似脚本，只需测试其中具有代表性的样本，以确认它们都能正常工作，同时兼顾完成所需的时间。

删除技能不需要的所有示例文件和目录。

更新 SKILL.md

写作指南： 始终使用祈使式或不定式。

Frontmatter

编写包含 name 和 description 的 YAML frontmatter：

• name：技能名称
• description：这是技能的主要触发机制，有助于判断何时使用该技能。
  • 同时说明 Skill 的功能，以及适用的具体触发条件或场景。
  • 将所有“何时使用”的信息放在这里，而不是正文中。正文只会在触发后加载，因此在正文中添加“何时使用此技能”章节并无帮助。
  • docx 技能的描述示例：“全面的文档创建、编辑和分析，支持修订、批注、格式保留和文本提取。需要处理专业文档（.docx 文件）时使用，例如：(1) 创建新文档，(2) 修改或编辑内容，(3) 处理修订，(4) 添加批注，或执行其他文档任务”

不要在 YAML frontmatter 中添加其他字段。

正文

编写使用该技能及其捆绑资源的说明。

加载新技能

技能完成后，建议用户开始新会话，以加载新创建的技能。技能会在每个会话开始时加载，因此新技能在当前会话中不可用。开始新会话可确保技能正确注册并可供使用。

第 5 步：迭代

测试技能后，用户可能会要求改进。通常，这会在刚使用完技能、上下文仍然清晰时发生。

迭代工作流：

1. 在实际任务中使用技能
2. 留意遇到的困难或效率低下之处
3. 确定应如何更新 SKILL.md 或捆绑资源
4. 实施更改并再次测试