skill-creator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill Creator Guide

Skill 创作者指南

This guide helps you create effective skills for Apollo GraphQL and GraphQL development following the Agent Skills specification.

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

What is a Skill?

什么是Skill？

A skill is a directory containing instructions that extend an AI agent's capabilities with specialized knowledge, workflows, or tool integrations. Skills activate automatically when agents detect relevant tasks.

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

Directory Structure

目录结构

A skill requires at minimum a

SKILL.md

file:

skill-name/
├── SKILL.md              # Required - main instructions
└── references/           # Optional - detailed documentation
    ├── topic-a.md
    └── topic-b.md

一个Skill至少需要一个

SKILL.md

文件：

skill-name/
├── SKILL.md              # 必填 - 主要指令
└── references/           # 可选 - 详细文档
    ├── topic-a.md
    └── topic-b.md

SKILL.md Format

SKILL.md 格式

Frontmatter (Required)

前置元数据（必填）

yaml

---
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"
allowed-tools: Read Write Edit Glob Grep
---

yaml

---
name: skill-name
description: >
  清晰描述本Skill的功能及适用场景。
  包含触发条件：(1) 第一个条件，(2) 第二个条件。
license: MIT
compatibility: 适用于Claude Code及类似AI编码助手。
metadata:
  author: your-org
  version: "1.0"
allowed-tools: Read Write Edit Glob Grep
---

Frontmatter Fields

前置元数字段

Field	Required	Description
`name`	Yes	Lowercase, hyphens only. Must match directory name. Max 64 chars.
`description`	Yes	What the skill does and when to use it. Max 1024 chars.
`license`	No	License name (e.g., MIT, Apache-2.0).
`compatibility`	No	Environment requirements. Max 500 chars.
`metadata`	No	Key-value pairs for author, version, etc.
`allowed-tools`	No	Space-delimited list of pre-approved tools.

字段	是否必填	说明
`name`	是	仅使用小写字母、数字和连字符，不能以连字符开头或结尾，不能使用连续连字符（ `--` ），必须与父目录名称匹配，最多64个字符。
`description`	是	描述Skill的功能及适用场景，最多1024个字符。
`license`	否	许可证名称（如MIT、Apache-2.0）。
`compatibility`	否	环境要求，最多500个字符。
`metadata`	否	包含作者、版本等信息的键值对。
`allowed-tools`	否	预批准工具的空格分隔列表。

Name Rules

命名规则

Use lowercase letters, numbers, and hyphens only
Do not start or end with a hyphen
Do not use consecutive hyphens (
```
--
```
)
Must match the parent directory name

Good:

apollo-client

graphql-schema

rover

Bad:

Apollo-Client

-apollo

apollo--client

仅使用小写字母、数字和连字符
不能以连字符开头或结尾
不能使用连续连字符（
```
--
```
）
必须与父目录名称匹配

正确示例：

apollo-client

graphql-schema

rover

错误示例：

Apollo-Client

-apollo

apollo--client

Description Best Practices

描述最佳实践

Write descriptions that help agents identify when to activate the skill:

yaml

undefined

编写描述时需帮助Agent识别激活时机：

yaml

undefined

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.

description: > 遵循行业最佳实践设计GraphQL Schema的指南。在以下场景使用本Skill： (1) 设计新的GraphQL Schema或API时， (2) 审查现有Schema以优化时， (3) 确定类型结构或可空性时， (4) 实现分页或错误模式时。

Bad - vague and unhelpful

糟糕示例 - 模糊且无用

description: Helps with GraphQL stuff.

undefined

description: 处理GraphQL相关事务。

undefined

Body Content

正文内容

The markdown body contains instructions the agent follows. Structure it for clarity:

Markdown正文包含Agent需遵循的指令，需结构清晰：

Recommended Sections

Example Structure

示例结构

markdown

undefined

markdown

undefined

Skill Title

Skill 标题

Brief overview of what this skill helps with.

本Skill的简要概述。

Process

流程

Follow this process when working on [task]:

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

处理[任务]时遵循以下流程：

步骤1：调研并理解需求
步骤2：实现解决方案
步骤3：验证结果

Quick Reference

快速参考

Common Pattern

常见模式

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

graphql

type Example {
  id: ID!
  name: String
}

Reference Files

参考文件

Topic A - Detailed guide for topic A
Topic B - Detailed guide for topic B

主题A - 主题A的详细指南
主题B - 主题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

undefined

ALWAYS执行此项重要操作
NEVER执行此项有问题的操作
PREFER使用此方法而非其他方法

undefined

Progressive Disclosure

渐进式信息披露

Structure skills to minimize context usage:

Metadata (~100 tokens):
```
name
```
and
```
description
```
load at startup for all skills
Instructions (< 5000 tokens): Full
```
SKILL.md
```
loads when skill activates
References (as needed): Files in
```
references/
```
load only when required

Keep

SKILL.md

under 500 lines. Move detailed documentation to reference files.

Skill的结构设计应尽量减少上下文占用：

元数据（约100个token）：所有Skill在启动时都会加载
```
name
```
和
```
description
```
指令（少于5000个token）：当Skill激活时加载完整的
```
SKILL.md
```
参考文件（按需加载）：仅在需要时加载
```
references/
```
目录下的文件

保持

SKILL.md

不超过500行，将详细文档移至参考文件中。

Reference Files

参考文件

Use

references/

for detailed documentation:

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

Reference files should be:

Focused on a single topic
Self-contained (readable without other files)
Under 300 lines each

Link to references from

SKILL.md

markdown

undefined

使用

references/

目录存放详细文档：

references/
├── setup.md          # 安装和配置
├── patterns.md       # 常见模式和示例
├── troubleshooting.md # 错误解决方案
└── api.md            # API参考

参考文件应满足：

聚焦单一主题
独立可读（无需依赖其他文件）
每篇不超过300行

在

SKILL.md

中链接到参考文件：

markdown

undefined

Reference Files

参考文件

Setup - Installation and configuration
Patterns - Common patterns and examples

undefined

安装配置 - 安装和配置指南
常见模式 - 常见模式和示例

undefined

Writing Style

写作风格

Follow the Apollo Voice for all skill content:

所有Skill内容需遵循Apollo语气风格：

Tone

语气

Approachable and helpful
Opinionated and authoritative (prescribe the "happy path")
Direct and action-oriented

亲切且有帮助
有主见且权威（指定“最佳路径”）
直接且注重行动

Language

语言

Use American English
Keep language simple; avoid idioms
Use present tense and active voice
Use imperative verbs for instructions

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

Formatting

格式

Use sentence casing for headings
Use code font for symbols, commands, file paths, and URLs
Use bold for UI elements users click
Use hyphens (-) for unordered lists

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

Avoid

避免

"Simply", "just", "easy" (can be condescending)
Vague phrases like "click here"
Semicolons (use periods instead)
"We" unless clearly referring to Apollo

使用“Simply”、“just”、“easy”等词（可能显得居高临下）
模糊短语如“click here”
分号（改用句号）
使用“We”，除非明确指代Apollo

Reference Files

参考文件

For Apollo GraphQL-specific guidance:

Apollo Skills - Patterns and examples for Apollo GraphQL skills

针对Apollo GraphQL的特定指导：

Apollo Skills - Apollo GraphQL Skill的模式和示例

Checklist for New Skills

新Skill检查清单

Before publishing a skill, verify:

```
name
```
matches directory name and follows naming rules
```
description
```
clearly states what the skill does and when to use it
```
SKILL.md
```
is under 500 lines
Reference files are focused and under 300 lines each
Instructions are clear and actionable
Code examples are correct and tested
Ground rules use ALWAYS/NEVER/PREFER format
Content follows Apollo Voice guidelines

发布Skill前，请验证以下内容：

```
name
```
符合命名规则且与目录名称匹配
```
description
```
清晰说明Skill的功能及适用场景
```
SKILL.md
```
不超过500行
参考文件聚焦单一主题且每篇不超过300行
指令清晰且可执行
代码示例正确且经过测试
基本原则使用ALWAYS/NEVER/PREFER格式
内容遵循Apollo语气风格指南

Ground Rules

基本原则

ALWAYS include trigger conditions in the description (use numbered list)
ALWAYS use checkboxes for multi-step processes
ALWAYS link to reference files for detailed documentation
NEVER exceed 500 lines in SKILL.md
NEVER use vague descriptions that don't help agents identify when to activate
PREFER specific examples over abstract explanations
PREFER opinionated guidance over listing multiple options
USE
```
allowed-tools
```
to pre-approve tools the skill needs

ALWAYS在描述中包含触发条件（使用编号列表）
ALWAYS为多步骤流程使用复选框
ALWAYS链接到参考文件以获取详细文档
NEVER让SKILL.md超过500行
NEVER使用模糊描述，以免Agent无法识别激活时机
PREFER使用具体示例而非抽象解释
PREFER提供有主见的指导而非列出多种选项
使用
```
allowed-tools
```
预先批准Skill所需的工具

skill-creator

Original

Translation

Skill Creator Guide

Skill 创作者指南

What is a Skill?

什么是Skill？

Directory Structure

目录结构

SKILL.md Format

SKILL.md 格式

Frontmatter (Required)

前置元数据（必填）

Frontmatter Fields

前置元数字段

Name Rules

命名规则

Description Best Practices

描述最佳实践

Good - specific triggers and use cases

良好示例 - 明确触发条件和使用场景

Bad - vague and unhelpful

糟糕示例 - 模糊且无用

Body Content

正文内容

Recommended Sections

推荐章节

Example Structure

示例结构

Skill Title

Skill 标题

Process

流程

Quick Reference

快速参考

Common Pattern

常见模式

Reference Files

参考文件

Key Rules

核心规则

Category One

类别一

Category Two

类别二

Ground Rules

基本原则

Progressive Disclosure

渐进式信息披露

Reference Files

参考文件

Reference Files

参考文件

Writing Style

写作风格

Tone

语气

Language

语言

Formatting

格式

Avoid

避免

Reference Files

参考文件

Checklist for New Skills

新Skill检查清单

Ground Rules

基本原则