skill-creator

Skill Creator

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

关于技能

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

技能提供的内容

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

核心原则

简洁是关键

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

默认假设：Claude 已经非常聪明。 只添加 Claude 尚不具备的上下文。审视每条信息：“Claude 真的需要这个解释吗？”以及“这一段值得占用这些 token 吗？”

优先采用简洁的示例，而非冗长的解释。

设置恰当的自由度

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

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

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

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

可以把 Claude 想象成在探索一条路径：狭窄且两侧有悬崖的桥需要明确的护栏（低自由度），而开阔的场地则允许有许多路线（高自由度）。

技能的构成

每项技能都包含必需的 SKILL.md 文件和可选的捆绑资源：

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter metadata (required)
│   │   ├── name: (required)
│   │   ├── description: (required)
│   │   └── compatibility: (optional, rarely needed)
│   └── 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 字段，以及 license、metadata 和 compatibility 等可选字段。Claude 只会读取 name 和 description 来判断何时触发技能，因此应清晰、全面地说明技能的用途及其适用场景。compatibility 字段用于注明环境要求（目标产品、系统软件包等），但大多数技能不需要此字段。
• 正文（Markdown）：使用技能的说明和指南。仅在技能触发后（如果触发）才会加载。

捆绑资源（可选）

脚本（scripts/）

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

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

参考资料（references/）

文档和参考材料，可按需加载到上下文中，为 Claude 的处理和思考提供参考。

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

资源文件（assets/）

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

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

技能中不应包含的内容

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

• 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

Claude 只会在需要时加载 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)

当用户询问销售指标时，Claude 只会读取 sales.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)

只有当用户需要这些功能时，Claude 才会读取 REDLINING.md 或 OOXML.md。

重要指南：

• 避免引用层级过深——引用文件应与 SKILL.md 保持一层关系。所有参考文件都应由 SKILL.md 直接链接。
• 为较长的参考文件添加结构——对于超过 100 行的文件，请在顶部添加目录，以便 Claude 在预览时了解文件的完整范围。

技能创建流程

技能创建包括以下步骤：

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

请按顺序执行这些步骤；只有在有明确理由表明某个步骤不适用时，才跳过该步骤。

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

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

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

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

• “图像编辑器技能应支持哪些功能？编辑、旋转，还需要其他功能吗？”
• “你能举几个使用此技能的例子吗？”
• “我能想到用户可能会提出‘移除这张图片中的红眼’或‘旋转这张图片’之类的要求。你还能想到其他使用方式吗？”
• “用户会说什么话来触发此技能？”

为避免让用户不知所措，不要在一条消息中提出太多问题。先从最重要的问题开始，再根据需要继续询问，以提高效果。

当你清楚了解此技能应支持哪些功能时，即可结束此步骤。

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

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

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

示例：创建 pdf-editor 技能以处理“帮我旋转这个 PDF”之类的请求时，分析发现：

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

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

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

示例：创建 big-query 技能以处理“今天有多少用户登录了？”之类的请求时，分析发现：

1. 每次查询 BigQuery 都需要重新查找表结构及其关联关系
2. 将记录表结构的 references/schema.md 文件存入技能会很有帮助

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

步骤 3：初始化技能

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

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

从头创建新技能时，务必运行 init_skill.py 脚本。该脚本可以方便地生成新的技能模板目录，其中会自动包含技能所需的一切，从而让技能创建过程更加高效、可靠。

用法：

python3 plugins/dev-tools/skills/skill-creator/scripts/init_skill.py <skill-name> --path plugins/<category>/skills/

该脚本会：

• 在指定路径创建技能目录
• 生成带有正确 frontmatter 和 TODO 占位符的 SKILL.md 模板
• 创建示例资源目录：scripts/、references/ 和 assets/
• 在每个目录中添加可自定义或删除的示例文件

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

步骤 4：编辑技能

编辑（新生成或现有的）技能时，请记住，该技能是为另一个 Claude 实例而创建的。请包含对 Claude 有益且不显而易见的信息。思考哪些程序性知识、领域专属细节或可复用资源，能帮助另一个 Claude 实例更高效地完成这些任务。

技能必须自包含

安装技能的其他用户不会拥有你的 ~/.claude/rules/、你的 CLAUDE.md、你的 MCP 服务或你的 Vault。技能所需的一切都必须包含在技能自身中：

不要依赖……	而应……
你的 ~/.claude/rules/*.md	将指导内容放入 SKILL.md 或 references/
你的项目级/全局 CLAUDE.md	将相关背景信息直接写入技能
特定的 MCP 服务（Brain、Vault 等）	让 MCP 的使用成为可选项，或说明所需内容
你的 settings.local.json 权限	说明技能需要哪些权限，以便用户添加
特定环境中的路径或工具	使用检测逻辑或说明前置条件

测试：刚安装 Claude Code 的用户能否使用此技能？如果没有你的个人配置就无法正常工作，那么它就不是自包含的。

学习经过验证的设计模式

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

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

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

优先使用脚本，而非 Bash 命令链

如果某个技能步骤涉及从多个来源收集数据、扫描文件或批量操作，请指示 Claude 编写并运行脚本，而不是逐条列出 Bash 命令。每条 Bash 命令都需要单独获得用户批准——一个需要运行 10 条命令的步骤会产生 10 个批准提示。

不要这样做……	应这样指示……
“运行 git log，然后运行 grep，再运行 jq……”	“编写一个 Python 脚本，收集 Git 历史记录、提取模式并输出摘要。然后从 /tmp 运行该脚本。”
“对每个文件运行 cat 并检查……”	“编写一个脚本，扫描所有匹配的文件并返回结构化报告。”
“运行这 5 条 curl 命令……”	“编写一个脚本来发起 API 调用并汇总结果。”

经验法则：如果一个逻辑操作需要 3 条或更多 Bash 命令，就应该编写脚本。一次 Write 加一次 Bash 运行 = 2 次批准，而非多次。

保存位置：将脚本写入项目中的 .claude/scripts/，而不是 /tmp。项目脚本是项目演进的一部分，未来的会话也可以使用。仅在处理真正一次性、可丢弃的操作时使用 /tmp。

从可复用的技能内容开始

开始实施时，先使用上面确定的可复用资源：scripts/、references/ 和 assets/ 文件。请注意，这一步可能需要用户提供信息。例如，实施 brand-guidelines 技能时，用户可能需要提供品牌素材或模板，以便存入 assets/，也可能需要提供文档，以便存入 references/。

必须实际运行新增脚本进行测试，以确保没有错误，并且输出符合预期。如果有许多相似脚本，只需测试有代表性的一部分，即可在确保它们都能正常运行的同时兼顾完成时间。

删除技能不需要的示例文件和目录。初始化脚本会在 scripts/、references/ 和 assets/ 中创建示例文件以展示结构，但大多数技能并不需要这些文件。

更新 SKILL.md

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

Frontmatter

编写包含 name 和 description 的 YAML frontmatter：

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

不要在 YAML frontmatter 中包含其他字段。

正文

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

步骤 5：打包技能

技能开发完成后，可以将其打包以供分发：

用于 claude.ai（Web 界面）：

python3 plugins/dev-tools/skills/skill-creator/scripts/package_skill.py <path/to/skill-folder>

这会创建一个 .skill 文件（zip 格式），用于上传到 claude.ai。

用于 Claude Code（CLI）：

技能以目录形式使用，无需打包。直接安装：

# Install from this repo
/plugin install ./skills/<skill-name>

# Or add a repo as a marketplace
/plugin marketplace add owner/repo-name
/plugin install <bundle-name>

打包脚本会：

1. 验证技能，自动检查：

   • YAML frontmatter 格式和必填字段
   • 技能命名规范和目录结构
   • 描述的完整性和质量
   • 文件组织和资源引用

2. 如果验证通过，则打包技能，创建一个以技能命名的 .skill 文件（例如，my-skill.skill），其中包含所有文件，并保留适合分发的目录结构。

如果验证失败，脚本会报告错误并退出，不会创建软件包。修复所有验证错误后，再次运行打包命令。

批量打包：

# Package all Claude AI-compatible skills
python3 plugins/dev-tools/skills/skill-creator/scripts/package_all.py --claude-ai-only

# Package all skills
python3 plugins/dev-tools/skills/skill-creator/scripts/package_all.py

# List skills and compatibility
python3 plugins/dev-tools/skills/skill-creator/scripts/package_all.py --list

双环境技能

技能可以同时在 Claude AI（Web）和 Claude Code（CLI）中使用。为这两种环境构建技能时，请注意以下差异：

功能	Claude AI	Claude Code
文件输出	/mnt/user-data/outputs/	本地文件系统
用户交互	ask_user_input 工具	终端提示
Web 搜索	内置 web_search 工具	WebSearch 工具
Shell 命令	不可用	Bash 工具
子 Agent	不可用	Task 工具（Explore、Plan 等）
MCP 工具	连接后名称相同	连接后名称相同
Artifacts	HTML、React 内联渲染	不可用

**标记兼容性：**对于需要本地文件系统、bash 或 CLI 工具的技能，请在其 frontmatter 中添加 compatibility: claude-code-only。没有此字段的技能默认可在两种环境中使用。

---
name: my-cli-skill
description: "..."
compatibility: claude-code-only
---

**编写双环境技能：**如果技能应根据环境调整其行为，请添加一个“环境说明”部分：

## Environment Notes

- **Claude AI:** Save output files to `/mnt/user-data/outputs/`. Use `present_files` to share.
- **Claude Code:** Save output files to the project directory or path specified by the user.

描述中的触发短语：description 字段是主要的触发机制。Claude 会用它来决定是否激活技能。请加入用户可能会说的具体短语，而不只是描述技能的功能。例如：“当用户说‘制作 favicon’、‘生成图标’、‘创建 favicon 包’，或提到缺少 favicon 时使用。”

步骤 6：迭代

测试技能后，用户可能会要求改进。通常，这种情况会在刚使用完技能后发生，此时用户对技能的表现还有新鲜的感受。

迭代工作流：

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