skill-creator

Skill 创建指南

本指南帮助你遵循 Agent Skills 规范，为 Apollo GraphQL 和 GraphQL 开发创建有效的技能。

什么是 Skill？

Skill 是一个目录，其中包含用于扩展 AI Agent 能力的指令，涵盖专业知识、工作流或工具集成。当 Agent 检测到相关任务时，Skill 会自动激活。

目录结构

Skill 至少需要一个 SKILL.md 文件：

skill-name/
├── SKILL.md              # Required - main instructions
├── references/           # Optional - detailed documentation
│   ├── topic-a.md
│   └── topic-b.md
├── scripts/              # Optional - executable helpers
│   └── validate.sh
├── templates/            # Optional - config/code templates
│   └── config.yaml
└── assets/               # Optional - static resources (images, schemas, data files)

SKILL.md 格式

Frontmatter（必需）

---
name: skill-name
description: >
  A clear description of what this skill does and when to use it.
  Include trigger conditions: (1) first condition, (2) second condition.
license: MIT
compatibility: Works with Claude Code and similar AI coding assistants.
metadata:
  author: your-org
  version: "1.0.0"
allowed-tools: Read Write Edit Glob Grep
---

Frontmatter 字段

字段	必需	说明
name	是	仅限小写字母和连字符。必须与目录名称一致。最多 64 个字符。
description	是	说明该 Skill 的作用以及适用场景。最多 1024 个字符。
license	否	许可证名称（例如 MIT、Apache-2.0）。
compatibility	否	环境要求。最多 500 个字符。
metadata	否	作者、版本等键值对。
allowed-tools	否	以空格分隔的预先批准工具列表。请勿包含 Bash(curl:*)。

名称规则

• 只能使用小写字母、数字和连字符
• 不得以连字符开头或结尾
• 不得使用连续连字符（--）
• 必须与父目录名称一致

正确示例：apollo-client、graphql-schema、rover 错误示例：Apollo-Client、-apollo、apollo--client

Description 最佳实践

编写有助于 Agent 判断何时激活 Skill 的描述：

# Good - specific triggers and use cases
description: >
  Guide for designing GraphQL schemas following industry best practices. Use this skill when:
  (1) designing a new GraphQL schema or API,
  (2) reviewing existing schema for improvements,
  (3) deciding on type structures or nullability,
  (4) implementing pagination or error patterns.

# Bad - vague and unhelpful
description: Helps with GraphQL stuff.

正文内容

Markdown 正文包含 Agent 应遵循的指令。请清晰地组织内容：

推荐章节

1. 概述 - 简要说明 Skill 的用途
2. 流程 - 分步骤的工作流（多步骤流程请使用复选框）
3. 快速参考 - 常见模式和语法
4. 安全 - 风险、缓解措施和验证（如果 Skill 涉及任何安全敏感内容）
5. 参考文件 - 详细文档的链接
6. 关键规则 - 按主题整理的重要指南
7. 基本规则 - 必须遵循和禁止事项

结构示例

# Skill Title

Brief overview of what this skill helps with.

## Process

Follow this process when working on [task]:

- [ ] Step 1: Research and understand requirements
- [ ] Step 2: Implement the solution
- [ ] Step 3: Validate the result

## Quick Reference

### Common Pattern

\`\`\`graphql
type Example {
  id: ID!
  name: String
}
\`\`\`

## Security

> **Risk: [brief description of what can go wrong].**
> [What the user MUST do to prevent it.]

- ALWAYS [secure default behavior]
- NEVER [dangerous configuration] in production

## Reference Files

- [Topic A](references/topic-a.md) - Detailed guide for topic A
- [Topic B](references/topic-b.md) - Detailed guide for topic B

## Key Rules

### Category One

- Rule about this category
- Another rule

### Category Two

- Rule about this category

## Ground Rules

- ALWAYS do this important thing
- NEVER do this problematic thing
- PREFER this approach over that approach

安全敏感内容

如果 Skill 会生成配置、代码或指导，而这些内容在误用时可能引发安全问题，则必须让 LLM 明确知晓并能看到这些风险。LLM 无法仅凭上下文推断安全影响，因此需要清晰标注的信号。

什么情况下 Skill 需要安全指导？

如果符合以下任一情况，该 Skill 就属于安全敏感内容：

• 生成控制数据访问的配置（缓存、身份验证、CORS、权限）
• 处理机密、凭证或令牌
• 生成以提升权限运行的代码
• 控制哪些数据会共享、公开或向用户展示
• 配置网络绑定、端点或外部访问

如何在 Skill 中明确安全信息

1. 专门的 Security 章节：放在 SKILL.md 或参考文件中，并标记为 ## Security。不要使用“Private data”或“Customization”——请使用“Security”一词，以便 LLM 识别该类别。

2. 在风险发生处明确警告：将安全指导放在会产生风险的配置或代码旁边，而不是放在 LLM 可能不会加载的单独文件中：

   ### Response caching scope
   
   > **Security: data leakage risk.** All cached data is PUBLIC by default.
   > User-specific fields MUST use `scope: PRIVATE` with a `private_id`
   > configured, or they will be shared across all users.
   

3. 验证清单项目：每项安全敏感功能都必须在验证清单中有对应检查。请将这些检查归在 ## Security 标题下。

4. 基本规则：为安全关键行为添加 ALWAYS/NEVER 规则。这些规则向 LLM 发出的信号最强。

5. 要求提供数据模型：如果正确配置安全设置需要了解用户的数据模型（例如，哪些字段属于特定用户），Skill 必须要求 LLM 在生成配置前询问用户。不要让 LLM 猜测。

反模式

• 描述安全敏感的默认设置（如“默认公开”），却未将其标明为安全问题
• 仅在按需加载的参考文件中提供安全指导——SKILL.md 本身必须包含关键警告
• 对严格的安全要求使用委婉措辞（如“你可以考虑”）——应使用“MUST”和“NEVER”
• 假设大模型知道架构中的哪些字段是私有的——要求用户明确输入

渐进式披露

对技能进行结构化，以尽量减少上下文用量：

1. 元数据（约 100 个令牌）：所有技能的 name 和 description 会在启动时加载
2. 说明（少于 5000 个令牌）：技能激活时加载完整的 SKILL.md
3. 参考资料（按需）：仅在需要时加载 references/ 中的文件

将 SKILL.md 控制在 500 行以内。将详细文档移至参考文件。

参考文件

使用 references/ 存放详细文档：

references/
├── setup.md          # Installation and configuration
├── patterns.md       # Common patterns and examples
├── troubleshooting.md # Error solutions
└── api.md            # API reference

参考文件应当：

• 聚焦于单一主题
• 独立完整（无需其他文件即可阅读）
• 每个文件少于 300 行

在 SKILL.md 中链接到参考资料：

## Reference Files

- [Setup](references/setup.md) - Installation and configuration
- [Patterns](references/patterns.md) - Common patterns and examples

脚本

使用 scripts/ 存放 Agent 可运行的可执行辅助脚本：

scripts/
├── validate.sh       # Validation commands
├── setup.py          # Setup automation
└── check-version.sh  # Version checking

脚本应当独立完整，包含错误处理，并在顶部附上用法注释。通过 allowed-tools 预先批准脚本（例如，Bash(./scripts/validate.sh:*)）。

模板

使用 templates/ 存放配置文件、样板代码或入门代码：

templates/
├── config.yaml       # Default configuration
├── config-v2.yaml    # Version-specific variant
└── example-app/      # Starter project

Agent 会复制或调整模板，而不是直接执行它们。

写作风格

所有技能内容均应遵循 Apollo Voice：

语气

• 平易近人、乐于助人
• 有主见且权威（明确推荐“最佳路径”）
• 直接且以行动为导向

语言

• 使用美式英语
• 语言简洁，避免习语
• 使用现在时和主动语态
• 使用祈使动词编写指令

格式

• 标题使用句首字母大写格式
• 符号、命令、文件路径和 URL 使用代码字体
• 用户需要点击的 UI 元素使用粗体
• 无序列表使用连字符（-）

避免

• “Simply”、“just”、“easy”（可能显得居高临下）
• “click here”等含糊表达
• 分号（改用句号）
• 除非明确指 Apollo，否则不要使用“We”

参考文件

Apollo GraphQL 专用指南：

• Apollo Skills - Apollo GraphQL 技能的模式和示例

版本控制

元数据中的 version 字段使用语义化版本号（"X.Y.Z"）：

metadata:
  author: apollographql
  version: "1.0.0"

• 主版本（X）：会改变技能行为或激活方式的破坏性变更（例如，触发条件重命名、移除章节、修改基本规则）
• 次版本（Y）：向后兼容的新内容或功能（例如，添加参考文件、新增章节、扩展示例）
• 修订版本（Z）：不改变行为的小修复（例如，修正拼写错误、调整措辞、修复格式）

新技能从 "1.0.0" 开始。

新技能检查清单

发布技能前，请确认：

• name 与目录名称一致，并符合命名规则
• description 清楚说明技能的功能及适用场景
• SKILL.md 少于 500 行
• 参考文件主题明确，且每个文件少于 300 行
• 说明清晰且可执行
• 代码示例正确且经过测试
• 基本规则采用 ALWAYS/NEVER/PREFER 格式
• 内容遵循 Apollo Voice 指南

基本规则

• 始终在描述中包含触发条件（使用编号列表）
• 多步骤流程始终使用复选框
• 始终链接到参考文件，以提供详细文档
• SKILL.md 不得超过 500 行
• 不得使用无法帮助 Agent 判断何时激活的模糊描述
• 优先使用具体示例，而不是抽象说明
• 优先提供明确的指导，而不是罗列多种选项
• 使用 allowed-tools 预先批准技能所需的工具
• 切勿在 allowed-tools 中包含 Bash(curl:*)，因为它会授予不受限制的网络访问权限，并允许使用 curl | sh 这类远程代码执行模式
• 如果技能会生成控制访问、缓存、身份验证、机密信息或数据暴露的配置或代码，始终包含 ## Security 部分
• 切勿仅将关键安全指导埋在参考文件中——必须在 SKILL.md 中列出关键警告，确保大模型始终能看到
• 始终要求大模型在生成敏感安全配置前询问用户的数据模型（例如，哪些字段属于用户专有数据，哪些数据是公开的）
• 在会造成安全风险的配置或代码旁，使用明确的引用块警告（> **Security: ...**）
• 始终为每项安全敏感功能添加验证清单项，并将其归入 ## Security 标题下