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 the Apollo Solutions and Field teams following the Agent Skills specification.

本指南将帮助你遵循Agent Skills规范，为Apollo Solutions和现场团队创建高效的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)

Frontmatter（必填）

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

yaml

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

Frontmatter Fields

Frontmatter字段说明

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. Do not include `Bash(curl:*)` .

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

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识别何时激活该Skill：

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

该类别的相关规则
另一条规则

Ground Rules

基本准则

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

undefined

必须执行的重要事项
绝对禁止的问题操作
优先选择的实现方案

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 tokens）：所有Skill的
```
name
```
和
```
description
```
会在启动时加载
操作说明（< 5000 tokens）：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

标题使用 sentence case（句首字母大写，其余小写）
符号、命令、文件路径和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 Solutions-specific guidance:

Apollo Skills - Patterns and examples for Apollo Solutions skills

Apollo Solutions专属指导：

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

Versioning

版本控制

Use semantic versioning (

"X.Y.Z"

) for the

version

field in metadata:

yaml

metadata:
  author: apollosolutions
  version: "1.0.0"

Major (X): Breaking changes that alter how the skill behaves or activates
Minor (Y): New content or capabilities that are backward-compatible
Patch (Z): Small fixes that don't change behavior

Start new skills at

"1.0.0"

元数据中的

version

字段使用语义化版本（

"X.Y.Z"

）：

yaml

metadata:
  author: apollosolutions
  version: "1.0.0"

主版本号（X）：会改变Skill行为或触发逻辑的破坏性变更
次版本号（Y）：向后兼容的新增内容或功能
修订号（Z）：不改变功能的小修复

新Skill的初始版本号为

"1.0.0"

。

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
```
metadata.author
```
is set to
```
apollosolutions
```

发布Skill前，请确认：

```
name
```
与目录名一致且符合命名规则
```
description
```
清晰说明Skill的功能和适用场景
```
SKILL.md
```
内容不超过500行
参考文件主题聚焦且单文件不超过300行
操作说明清晰可执行
代码示例正确且经过测试
基本准则使用ALWAYS/NEVER/PREFER格式
内容符合Apollo风格指南要求
```
metadata.author
```
设置为
```
apollosolutions
```

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
ALWAYS set
```
metadata.author
```
to
```
apollosolutions
```
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
NEVER include
```
Bash(curl:*)
```
in
```
allowed-tools
```
as it grants unrestricted network access and enables
```
curl | sh
```
remote code execution patterns

必须在描述中包含触发条件（使用编号列表）
多步流程必须使用复选框
详细文档必须链接到参考文件
必须将
```
metadata.author
```
设置为
```
apollosolutions
```
禁止SKILL.md内容超过500行
禁止使用无法帮助Agent识别激活时机的模糊描述
优先使用具体示例而非抽象说明
优先给出明确的指导建议而非罗列多个选项
使用
```
allowed-tools
```
预批准Skill需要的工具
禁止在
```
allowed-tools
```
中包含
```
Bash(curl:*)
```
，因为它会授予无限制的网络访问权限，支持
```
curl | sh
```
远程代码执行模式

skill-creator

Original

Translation

Skill Creator Guide

Skill创建指南

What is a Skill?

什么是Skill？

Directory Structure

目录结构

SKILL.md Format

SKILL.md格式

Frontmatter (Required)

Frontmatter（必填）

Frontmatter Fields

Frontmatter字段说明

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

类别一

Ground Rules

基本准则

Progressive Disclosure

渐进式披露

Reference Files

参考文件

Reference Files

参考文件

Writing Style

写作风格

Tone

语气

Language

语言

Formatting

格式

Avoid

避免使用

Reference Files

参考文件

Versioning

版本控制

Checklist for New Skills

新Skill检查清单

Ground Rules

基本准则