skill-creator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Building Skills

构建Skill

Skills extend agent capabilities with specialized knowledge, workflows, and tools.

Skill可借助专业知识、工作流和工具扩展Agent的能力。

Quick Start

快速开始

Minimal viable skill in 30 seconds:

bash

mkdir my-skill && cat > my-skill/SKILL.md << 'EOF'
---
name: my-skill
description: Does X when Y happens. Use for Z tasks.
---

30秒创建最小可用Skill：

bash

mkdir my-skill && cat > my-skill/SKILL.md << 'EOF'
---
name: my-skill
description: Does X when Y happens. Use for Z tasks.
---

My Skill

Instructions go here. EOF


Place in `.opencode/skills/` (project) or `~/.config/opencode/skills/` (global).

Instructions go here. EOF


将Skill放置在 `.opencode/skills/`（项目级）或 `~/.config/opencode/skills/`（全局级）目录下。

Skill Type Decision Tree

Skill类型决策树

What are you building?
├─ Instructions only → Simple skill (SKILL.md only)
│   Example: code-review guidelines, commit message format
│
├─ Domain knowledge → Reference-heavy skill (+ references/)
│   Example: API docs, database schemas, company policies
│
├─ Repeatable automation → Script-heavy skill (+ scripts/)
│   Example: PDF processing, data validation, file conversion
│
├─ Complex multi-step workflow → Multi-file skill (all directories)
│   Example: release process, deployment pipeline
│
└─ Large platform → Progressive skill
    Example: AWS, GCP, Cloudflare (60+ products)

你要构建什么？
├─ 仅包含指令 → 简单Skill（仅需SKILL.md）
│   示例：代码评审指南、提交信息格式
│
├─ 领域知识 → 重参考型Skill（需搭配references/目录）
│   示例：API文档、数据库 schema、公司政策
│
├─ 可重复自动化流程 → 重脚本型Skill（需搭配scripts/目录）
│   示例：PDF处理、数据验证、文件转换
│
├─ 复杂多步骤工作流 → 多文件Skill（包含所有目录）
│   示例：发布流程、部署流水线
│
└─ 大型平台 → 渐进式Skill
    示例：AWS、GCP、Cloudflare（含60+产品）

When to Create a Skill

何时创建Skill

Create a skill when:

Same instructions repeated across conversations
Domain knowledge model lacks (schemas, internal APIs, company policies)
Workflow requires 3+ steps with specific order
Code rewritten repeatedly for same task
Team needs shared procedural knowledge

满足以下场景时建议创建Skill：

相同指令在对话中重复出现
模型缺乏特定领域知识（如schema、内部API、公司政策）
工作流包含3个以上有特定顺序的步骤
同一任务的代码被重复编写
团队需要共享流程化知识

When NOT to Create a Skill

何时无需创建Skill

Scenario	Do Instead
Single-use instructions	AGENTS.md or inline in conversation
Model already knows domain	Don't add redundant context
< 3 steps, no reuse	Inline instructions
Highly variable workflow	Higher-freedom guidelines
Just want to store files	Use regular directories

场景	替代方案
一次性指令	写入AGENTS.md或直接在对话中内联
模型已掌握相关领域知识	无需添加冗余上下文
步骤少于3个且无复用需求	直接内联指令
高度可变的工作流	使用自由度更高的指南
仅需存储文件	使用常规目录

Reading Order

阅读顺序

Task	Files to Read
New skill from scratch	anatomy.md → frontmatter.md
Optimize existing skill	progressive-disclosure.md
Add scripts/resources	bundled-resources.md
Find skill pattern	patterns.md
Debug/fix skill	gotchas.md

任务	需阅读的文件
从零创建新Skill	anatomy.md → frontmatter.md
优化现有Skill	progressive-disclosure.md
添加脚本/资源	bundled-resources.md
查找Skill模式	patterns.md
调试/修复Skill	gotchas.md

In This Reference

参考文档说明

File	Purpose
anatomy.md	Skill directory structures
frontmatter.md	YAML spec, naming, validation
progressive-disclosure.md	Token-efficient design
bundled-resources.md	scripts/, references/, assets/
patterns.md	Real-world skill patterns
gotchas.md	Common mistakes + fixes

文件	用途
anatomy.md	Skill目录结构说明
frontmatter.md	YAML规范、命名规则、验证方法
progressive-disclosure.md	令牌高效设计方案
bundled-resources.md	scripts/、references/、assets/目录说明
patterns.md	真实场景Skill模式
gotchas.md	常见问题与修复方案

Scripts

脚本工具

Script	Purpose
`scripts/init_skill.sh`	Scaffold new skill
`scripts/validate_skill.sh`	Validate skill structure
`scripts/package_skill.sh`	Create distributable zip

脚本	用途
`scripts/init_skill.sh`	快速搭建新Skill脚手架
`scripts/validate_skill.sh`	验证Skill结构合规性
`scripts/package_skill.sh`	创建可分发的压缩包

Pre-Flight Checklist

上线前检查清单

Before using a skill:

SKILL.md starts with
```
---
```
(line 1, no blank lines)
```
name:
```
field present, matches directory name
```
description:
```
includes what + when to use
Closing
```
---
```
after frontmatter
SKILL.md under 200 lines (use references/ for more)
All internal links resolve

Run:

./scripts/validate_skill.sh ./my-skill

使用Skill前请确认：

SKILL.md以
```
---
```
开头（第1行，无空行）
包含
```
name:
```
字段，且与目录名称一致
```
description:
```
字段包含Skill功能及适用场景
前置元数据后有闭合的
```
---
```
SKILL.md内容不超过200行（更多内容请放入references/目录）
所有内部链接均可正常访问

执行验证命令：

./scripts/validate_skill.sh ./my-skill

Skill Locations

Skill存放位置

Priority	Location
1	`.opencode/skills/<name>/` (project)
2	`~/.config/opencode/skills/<name>/` (global)
3	`.claude/skills/<name>/` (Claude-compat)

Discovery walks up from CWD to git root. First-wins for duplicate names.

优先级	位置
1	`.opencode/skills/<name>/` （项目级）
2	`~/.config/opencode/skills/<name>/` （全局级）
3	`.claude/skills/<name>/` （兼容Claude）

程序会从当前工作目录向上遍历到Git根目录查找Skill。重名时优先级高的会被优先加载。

扩展参考

Cloudflare Skill - Reference implementation

Cloudflare Skill - 参考实现示例

skill-creator

Original

Translation

Building Skills

构建Skill

Quick Start

快速开始

My Skill

My Skill

Skill Type Decision Tree

Skill类型决策树

When to Create a Skill

何时创建Skill

When NOT to Create a Skill

何时无需创建Skill

Reading Order

阅读顺序

In This Reference

参考文档说明

Scripts

脚本工具

Pre-Flight Checklist

上线前检查清单

Skill Locations

Skill存放位置

See Also

扩展参考