skill-creator

技能创建器

本技能提供创建有效技能的指导。

关于技能

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

技能提供的内容

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

核心原则

简洁至关重要

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

默认假设：Gemini CLI 已经非常智能。 只添加 Gemini CLI 尚不具备的上下文。审视每条信息：“Gemini CLI 真的需要这个解释吗？”以及“这段内容值得占用相应的 token 吗？”

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

设置适当的自由度

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

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

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

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

可以把 Gemini CLI 想象成在探索一条道路：有悬崖的窄桥需要明确的护栏（低自由度），而开阔地带则允许有多条路线（高自由度）。

技能的组成

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

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter metadata (required)
│   │   ├── name: (required)
│   │   └── description: (required)
│   └── Markdown instructions (required)
└── Bundled Resources (optional)
    ├── scripts/          - Executable code (Node.js/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 字段。这是 Gemini CLI 用来判断何时使用技能的唯一字段，因此清晰、全面地说明技能是什么以及何时使用非常重要。
• 正文（Markdown）：使用该技能的说明和指导。仅在技能触发后加载（如果触发）。

捆绑资源（可选）

脚本（scripts/）

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

• 何时包含：需要反复重写相同代码，或需要确定性可靠性时
• 示例：用于 PDF 旋转任务的 scripts/rotate_pdf.cjs
• 优势：节省 token、结果确定，并且无需加载到上下文中即可执行
• Agent 操作体验：脚本必须输出便于大模型使用的标准输出。抑制标准回溯信息。输出清晰、简洁的成功／失败消息，并对输出进行分页或截断（例如“成功：处理后文件的前 50 行……”），以防上下文窗口溢出。
• 注意：Gemini CLI 仍可能需要读取脚本，以便进行修补或针对特定环境进行调整

参考资料（references/）

按需加载到上下文中的文档和参考资料，用于指导 Gemini CLI 的流程和思考。

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

资源文件（assets/）

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

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

技能中不应包含的内容

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

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

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

渐进式披露设计原则

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

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

渐进式披露模式

将 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

Gemini CLI 仅在需要时加载 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)

当用户询问销售指标时，Gemini CLI 只读取 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 时，Gemini CLI 只读取 aws.md。

模式 3：条件式详细信息

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

# CSV Processing

## Basic Analysis

Use pandas for loading and basic queries. See [PANDAS.md](PANDAS.md).

## Advanced Operations

For massive files that exceed memory, see [STREAMING.md](STREAMING.md). For timestamp normalization, see [TIMESTAMPS.md](TIMESTAMPS.md).

Gemini CLI reads REDLINING.md or OOXML.md only when the user needs those features.

重要指南：

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

技能创建流程

技能创建包括以下步骤：

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

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

技能命名

• 仅使用小写字母、数字和连字符；将用户提供的标题规范化为连字符格式（例如，“Plan Mode” -> plan-mode）。
• 生成名称时，长度应少于 64 个字符（字母、数字、连字符）。
• 优先使用简短、以动词开头且能描述操作的短语。
• 在有助于提高清晰度或触发效果时，按工具命名空间区分（例如，gh-address-comments、linear-address-issue）。
• 技能文件夹的名称必须与技能名称完全一致。

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

只有当技能的使用模式已非常明确时，才跳过此步骤。即使使用现有技能，此步骤仍然很有价值。

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

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

• “图像编辑器技能应支持哪些功能？编辑、旋转，还有其他功能吗？”
• “能否给出一些使用此技能的示例？”
• “我能想到用户可能会说‘去除这张图片中的红眼’或‘旋转这张图片’。你还想到其他使用方式吗？”
• “用户说什么时应该触发此技能？”

避免反复追问： 每次不要提出超过一两个澄清问题。优先采取行动：根据初步理解提出一份具体的功能或示例清单，并请用户进行调整。

当你明确了解技能应支持的功能后，即可结束此步骤。

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

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

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

示例：创建 pdf-editor 技能来处理“帮我旋转这个 PDF”这类请求时，分析结果表明：

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

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

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

示例：创建 big-query 技能来处理“今天有多少用户登录了？”这类请求时，分析结果表明：

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

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

步骤 3：初始化技能

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

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

从头创建新技能时，始终运行 init_skill.cjs 脚本。该脚本可以便捷地生成新的技能模板目录，并自动包含技能所需的一切，从而大幅提高技能创建过程的效率和可靠性。

注意： 请使用 available_resources 部分中提供的脚本绝对路径。

用法：

node <path-to-skill-creator>/scripts/init_skill.cjs <skill-name> --path <output-directory>

该脚本会：

• 在指定路径创建技能目录
• 生成带有适当 frontmatter 和 TODO 占位符的 SKILL.md 模板
• 创建示例资源目录：scripts/、references/ 和 assets/
• 添加示例文件（scripts/example_script.cjs、references/example_reference.md、assets/example_asset.txt），供你自定义或删除

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

步骤 4：编辑技能

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

学习经过验证的设计模式

根据技能需求，查阅以下实用指南：

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

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

从可复用的技能内容开始

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

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

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

更新 SKILL.md

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

Frontmatter

编写包含 name 和 description 的 YAML frontmatter：

• name：技能名称
• description：这是技能的主要触发机制，可帮助 Gemini CLI 理解何时使用该技能。
  • 同时说明技能的功能，以及适用的具体触发条件或情境。
  • 必须是单行字符串（例如，description: Data ingestion...）。引号可选。
  • 将所有“何时使用”信息都写在这里，不要写在正文中。正文只会在触发技能后加载，因此在正文中添加“何时使用此技能”章节对 Gemini CLI 没有帮助。
  • 示例：description: Data ingestion, cleaning, and transformation for tabular data. Use when Gemini CLI needs to work with CSV/TSV files to analyze large datasets, normalize schemas, or merge sources.

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

正文

编写使用该技能及其附带资源的说明。

步骤 5：打包技能

技能开发完成后，必须将其打包为可分发的 .skill 文件并提供给用户。打包流程会先自动验证技能（检查 YAML 并确保没有遗留 TODO），以确保其符合所有要求：

注意： 使用 available_resources 部分中提供的脚本绝对路径。

node <path-to-skill-creator>/scripts/package_skill.cjs <path/to/skill-folder>

可选的输出目录指定：

node <path-to-skill-creator>/scripts/package_skill.cjs <path/to/skill-folder> ./dist

打包脚本将：

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

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

2. 验证通过后打包技能，创建一个以技能命名的 .skill 文件（例如，my-skill.skill），其中包含所有文件，并保留正确的目录结构以供分发。.skill 文件是扩展名为 .skill 的 zip 文件。

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

步骤 6：安装和重新加载技能

技能打包为 .skill 文件后，主动询问用户是否要安装，并确认他们希望将其安装到当前文件夹（工作区范围）还是用户级别（用户范围）。

如果用户同意安装，请立即使用 run_shell_command 工具执行安装：

• 本地（工作区范围）：

  gemini skills install <path/to/skill-name.skill> --scope workspace
  

• 用户级别（用户范围）：

  gemini skills install <path/to/skill-name.skill> --scope user
  

重要： 安装完成后，告知用户必须在其交互式 Gemini CLI 会话中手动执行 /skills reload 命令，以启用新技能。之后，他们可以运行 /skills list 来验证安装。

注意：你（Agent）无法自行执行 /skills reload 命令；必须由用户在 Gemini CLI 的交互式实例中执行。不要尝试代替用户运行此命令。

第 7 步：迭代

测试技能后，用户可能会要求改进。通常，这会发生在使用技能后不久，此时用户对技能的表现还记忆犹新。

迭代工作流：

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