技能创建器

此技能提供创建有效技能的中文指导。

关于技能

技能是模块化的、自包含的包，通过提供专门知识、工作流程和工具来扩展 AI 的能力。将它们视为特定领域或任务的”入门指南”——它们将 AI 从通用代理转变为配备了模型无法完全拥有的程序化知识的专业代理。

技能提供什么

1. 专门工作流程 – 特定领域的多步骤程序
2. 工具集成 – 处理特定文件格式或 API 的说明
3. 领域专业知识 – 公司特定知识、模式、业务逻辑
4. 捆绑资源 – 复杂和重复任务的脚本、参考资料和资产

核心原则

简洁是关键

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

默认假设：AI 已经很聪明。 只添加 AI 还没有的上下文。挑战每个信息片段：”AI 真的需要这个解释吗？” 和 “这个段落是否值得其 token 成本？”

偏好简洁示例而非冗长解释。

设置适当的自由度

将具体程度与任务的脆弱性和可变性匹配：

高自由度（基于文本的说明）：当多个方法都有效、决策取决于上下文或启发式指导方法时使用。

中等自由度（带有参数的伪代码或脚本）：当存在首选模式、某些变体是可以接受的或配置影响行为时使用。

低自由度（特定脚本、少量参数）：当操作脆弱且容易出错、一致性至关重要或必须遵循特定序列时使用。

将 AI 视为探索路径：有悬崖的狭窄桥梁需要具体护栏（低自由度），而开放田野允许许多路线（高自由度）。

技能剖析

每个技能由必需的 SKILL.md 文件和可选捆绑资源组成。详细的目录结构规范请参考 references/anatomy.json，其中以 JSON 格式定义了技能的完整结构要求，包括必需和可选组件。

SKILL.md (必需)

每个 SKILL.md 由以下组成：

• 前言 (YAML)：包含 name 和 description 字段。这些是 AI 读取的唯一字段，用于确定何时使用技能，因此非常重要的是清楚而全面地描述技能是什么以及何时使用它。
• 主体 (Markdown)：使用技能的说明和指导。只有在技能触发后才会加载（如果有的话）。

捆绑资源 (可选)

脚本 (scripts/)

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

• 何时包含：当反复重写相同代码或需要确定性可靠性时
• 示例：scripts/rotate_pdf.py 用于 PDF 旋转任务
• 好处：token 高效、确定性、可能在不加载到上下文窗口的情况下执行
• 注意：脚本可能仍需要由 AI 阅读以进行修补或环境特定调整

参考资料 (references/)

文档和参考资料，旨在根据需要加载到上下文中以告知 AI 的过程和思考，包括样例代码、模板和详细示例。

• 何时包含：对于 AI 在工作时应参考的文档，包括样例代码和模板
• 示例：references/finance.md 用于财务模式，references/mnda.md 用于公司 NDA 模板，references/policies.md 用于公司政策，references/api_docs.md 用于 API 规范，references/code_examples.md 用于样例代码和模板
• 用例：数据库模式、API 文档、领域知识、公司政策、详细工作流程指南、样例代码、模板代码
• 好处：保持 SKILL.md 精简，仅在 AI 确定需要时加载
• 最佳实践：如果文件很大（>10k 字），在 SKILL.md 中包含 grep 搜索模式
• 避免重复：信息应位于 SKILL.md 或参考文件之一，而不是两者兼有。偏好参考文件用于详细信息，除非它真正核心于技能——这保持 SKILL.md 精简，同时使信息可发现而不会占用上下文窗口。只在 SKILL.md 中保留基本程序说明和工作流程指导；将详细参考资料、模式和示例移到参考文件。

技能中不应包含什么

技能应仅包含直接支持其功能的必需文件。不要创建无关文档或辅助文件，包括：

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

技能应仅包含 AI 代理完成手头工作的所需信息。它不应包含关于创建过程的辅助上下文、设置和测试程序、面向用户的文档等。创建额外文档文件只会增加混乱。

渐进式披露设计原则

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

1. 元数据 (name + description) – 始终在上下文中 (~100 字)
2. SKILL.md 主体 – 当技能触发时 (<5k 字)
3. 捆绑资源 – AI 根据需要 (无限制，因为脚本可以在不阅读到上下文窗口的情况下执行)

渐进式披露模式

保持 SKILL.md 主体为基本内容且低于 500 行，以最小化上下文膨胀。当接近此限制时，将内容拆分为单独文件。在将内容拆分到其他文件时，非常重要的是从 SKILL.md 引用它们并清楚描述何时阅读它们，以确保技能的读者知道它们存在以及何时使用它们。

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

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

# PDF 处理

## 快速开始

使用 pdfplumber 提取文本：
[代码示例]

## 高级功能

- **表单填写**：请参阅 [FORMS.md](FORMS.md) 以获取完整指南
- **API 参考**：请参阅 [REFERENCE.md](REFERENCE.md) 以获取所有方法
- **示例**：请参阅 [EXAMPLES.md](EXAMPLES.md) 以获取常见模式

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

模式 2：特定领域组织

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

bigquery-skill/
├── SKILL.md (概述和导航)
└── reference/
    ├── finance.md (收入、计费指标)
    ├── sales.md (机会、管道)
    ├── product.md (API 使用、功能)
    └── marketing.md (活动、归因)

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

类似地，对于支持多个框架或变体的技能，按变体组织：

cloud-deploy/
├── SKILL.md (工作流程 + 提供商选择)
└── references/
    ├── aws.md (AWS 部署模式)
    ├── gcp.md (GCP 部署模式)
    └── azure.md (Azure 部署模式)

当用户选择 AWS 时，AI 仅阅读 aws.md。

模式 3：条件细节

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

# DOCX 处理

## 创建文档

使用 docx-js 创建新文档。请参阅 [DOCX-JS.md](DOCX-JS.md)。

## 编辑文档

对于简单编辑，直接修改 XML。

**对于跟踪更改**：请参阅 [REDLINING.md](REDLINING.md)
**对于 OOXML 细节**：请参阅 [OOXML.md](OOXML.md)

AI 仅在用户需要这些功能时阅读 REDLINING.md 或 OOXML.md。

重要指南：

• 避免深度嵌套参考 – 保持参考从 SKILL.md 一级深度。所有参考文件应直接从 SKILL.md 链接。
• 构建更长的参考文件 – 对于超过 100 行的文件，在顶部包含目录，以便 AI 在预览时看到完整范围。

技能创建过程

技能创建涉及这些步骤：

1. 通过具体示例理解技能
2. 规划可重用技能内容 (脚本、参考资料、资产)
3. 初始化技能 (请参阅 references/skill-initialization-guide.md)
4. 编辑技能 (实现资源并编写 SKILL.md)
5. 验证技能 (请参阅 references/skill-validation-guide.md)
6. 打包技能 (请参阅 references/skill-packaging-guide.md)
7. 基于实际使用迭代

按顺序遵循这些步骤，仅在有明确原因时跳过。

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

仅在技能的使用模式已经清楚理解时跳过此步骤。即使使用现有技能，它仍然有价值。

要创建有效技能，清楚理解技能将如何使用的具体示例。这个理解可以来自直接用户示例或生成的示例，这些示例通过用户反馈验证。

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

• “图像编辑器技能应支持什么功能？编辑、旋转，还有什么？”
• “你能给出一些这个技能将如何使用的示例吗？”
• “我可以想象用户要求像’从这个图像中去除红眼’或’旋转这个图像’之类的事情。还有其他你想象这个技能被使用的方式吗？”
• “用户说什么应该触发这个技能？”

为了避免让用户不知所措，避免在单个消息中问太多问题。从最重要的开始，根据需要跟进以获得更好的效果。

当对技能应支持的功能有清晰认识时，结束此步骤。

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

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

1. 考虑从头执行示例的方式
2. 识别在重复执行这些工作流程时有用的脚本、参考资料和资产

示例：构建 pdf-editor 技能处理像”帮助我旋转这个 PDF”这样的查询时，分析显示：

1. 旋转 PDF 需要每次重写相同代码
2. scripts/rotate_pdf.py 脚本将有助于存储在技能中

示例：为像”为我构建一个待办事项应用”或”为我构建一个跟踪步数的仪表板”这样的查询设计 frontend-webapp-builder 技能时，分析显示：

1. 编写前端 webapp 需要每次相同的 HTML/React 样板
2. 包含样板 HTML/React 代码的 references/code-examples.md 文件将有助于存储在技能中

示例：构建 big-query 技能处理像”今天有多少用户登录？”这样的查询时，分析显示：

1. 查询 BigQuery 需要每次重新发现表模式和关系
2. 记录表模式的 references/schema.md 文件将有助于存储在技能中

要建立技能的内容，分析每个具体示例以创建要包含的可重用资源列表：脚本、参考资料和资产。

步骤 3：初始化技能

此时，是时候实际创建技能了。

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

从头创建新技能时，请遵循 references/skill-initialization-guide.md 中的详细步骤。该指南提供创建技能目录结构、生成 SKILL.md 模板以及设置初始资源目录的完整说明。

步骤 4：编辑技能

编辑（新生成或现有）技能时，记住技能正在为另一个 AI 实例使用。包含对 AI 有益且不明显的的信息。考虑什么程序化知识、特定领域细节或可重用资产将帮助另一个 AI 实例更有效地执行这些任务。

学习经过验证的设计模式

根据您的技能需求咨询这些有帮助的指南：

• 多步骤过程：请参阅 references/workflows.md 以获取顺序工作流程和条件逻辑
• 特定输出格式或质量标准：请参阅 references/output-patterns.md 以获取模板和示例模式
• 技能结构剖析：请参阅 references/anatomy.json 以获取完整的目录结构规范

这些文件包含有效技能设计的既定最佳实践。

从可重用技能内容开始

要开始实现，从上面识别的可重用资源开始：scripts/ 和 references/ 文件。请注意，此步骤可能需要用户输入。例如，实现 brand-guidelines 技能时，用户可能需要提供要存储在 references/ 中的文档或样例代码。

添加的脚本必须通过实际运行来测试，以确保没有错误且输出符合预期。如果有很多相似脚本，只需要测试代表性样本以确保信心它们都有效，同时平衡完成时间。

不需要的任何示例文件和目录应删除。初始化过程在 scripts/ 和 references/ 中创建示例文件以演示结构，但大多数技能不需要所有这些。

更新 SKILL.md

编写指南： 始终使用祈使/不定式形式。

前言

使用 name 和 description 编写 YAML 前言：

• name：技能名称
• description：这是您的技能的主要触发机制，帮助 AI 理解何时使用技能。
  • 同时包括技能做什么以及何时使用的具体触发器/上下文。
  • 在此处包含所有”何时使用”信息 – 不在主体中。主体仅在触发后加载，因此主体中的”何时使用此技能”部分对 AI 无帮助。
  • 示例描述用于 docx 技能：”全面文档创建、编辑和分析，支持跟踪更改、注释、格式保留和文本提取。当 AI 需要处理专业文档 (.docx 文件) 用于：(1) 创建新文档，(2) 修改或编辑内容，(3) 处理跟踪更改，(4) 添加注释，或任何其他文档任务时使用”

不要在 YAML 前言中包含任何其他字段。

主体

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

重要： 所有生成的技能应使用中文编写 SKILL.md，包括描述和主体内容，以匹配用户的语言偏好。

步骤 5：验证技能

一旦技能开发完成，在打包或分发之前验证其结构和内容。请遵循 references/skill-validation-guide.md 中的详细检查清单，确保技能符合所有标准并能正常工作。

步骤 6：打包技能

验证通过后，将技能打包成可分发的 .skill 文件。请遵循 references/skill-packaging-guide.md 中的步骤创建 ZIP 格式的包文件，便于分发和安装。

步骤 7：迭代

测试技能后，用户可能请求改进。通常这发生在使用技能后不久，带有技能表现的新鲜上下文。

迭代工作流程：

1. 在实际任务上使用技能
2. 注意挣扎或低效
3. 识别应如何更新 SKILL.md 或捆绑资源
4. 实施更改并再次测试