创建你的第一个技能

学完你能做什么

完成本教程后，你将能够：

• 创建符合规范的技能目录结构
• 编写正确的 SKILL.md Frontmatter
• 理解技能的各个组成部分
• 让 OpenCode 自动发现并加载你的技能
• 测试技能是否正常工作

你现在的困境

你可能遇到了这些情况：

• 想为项目创建专用技能，但不知道从哪开始
• 尝试写了一个 SKILL.md，但插件找不到
• 技能被发现了，但加载时报错「YAML 解析失败」
• 不确定 Frontmatter 里应该填哪些字段

这些问题都是因为不了解技能的结构规范。OpenCode Agent Skills 遵循 Anthropic 的 Agent Skills 规范，有固定的格式要求。

什么时候用这一招

创建技能适用于以下场景：

• 项目特定工作流：为某个项目定制的代码审查、部署流程
• 团队规范：统一团队的 commit 规范、代码风格检查
• 工具集成：集成常用 CLI 工具（如 git、docker）
• 知识沉淀：将常用操作步骤文档化，供 AI 随时调用

🎒 开始前的准备

在开始之前，请确认：

前置检查

• ✅ 已安装 OpenCode Agent Skills 插件（参考安装教程）
• ✅ 熟悉基本的命令行操作（mkdir、cd、ls）
• ✅ 有一个项目目录用于存放技能

核心思路

OpenCode Agent Skills 的技能是一个目录，目录中必须包含 SKILL.md 文件。这个文件有两部分：

1. YAML Frontmatter：技能的元数据（名称、描述等）
2. Markdown 正文：AI 执行时遵循的指导内容

插件会从多个位置自动发现技能（按优先级排序）：

1. .opencode/skills/              (项目级 - OpenCode)
2. .claude/skills/                (项目级 - Claude Code)
3. ~/.config/opencode/skills/     (用户级 - OpenCode)
4. ~/.claude/skills/              (用户级 - Claude Code)
5. ~/.claude/plugins/cache/        (插件缓存)
6. ~/.claude/plugins/marketplaces/ (已安装插件)

同一名称的技能，第一个匹配的生效。

跟我做：创建第一个技能

我们将创建一个简单的「hello-world」技能，用于演示基本结构。

第 1 步：创建技能目录

为什么 技能必须放在特定的目录中，插件才能自动发现。

操作

# 在项目根目录创建技能目录
mkdir -p .opencode/skills/hello-world

你应该看到：

项目根目录/
└── .opencode/
    └── skills/
        └── hello-world/

第 2 步：编写 SKILL.md

为什么 SKILL.md 是技能的核心文件，包含元数据和指导内容。

操作

在 .opencode/skills/hello-world/SKILL.md 中写入：

---
name: hello-world
description: A simple greeting skill for demonstration
---

# Hello World Skill

This is a demonstration skill that shows how to create a basic skill.

## Usage

Use this skill when you need to greet users or demonstrate skill functionality.

## Example

When asked "Say hello to the user", respond with a friendly greeting.

你应该看到：

.opencode/skills/hello-world/
└── SKILL.md

第 3 步：验证技能被发现

为什么 确保 Frontmatter 格式正确，插件能正确解析。

操作

在 OpenCode 中询问：

列出所有可用的技能

你应该看到： 插件返回的技能列表中包含 hello-world。

或者直接调用工具：

get_available_skills()

预期输出：

Available skills:
- hello-world: A simple greeting skill for demonstration

第 4 步：加载并测试技能

为什么 验证技能内容能正确注入到会话上下文。

操作

在 OpenCode 中：

加载 hello-world 技能

你应该看到：

Skill 'hello-world' loaded successfully.

Available scripts: (none)
Available files: (none)

SKILL.md 内容已注入到上下文。

第 5 步：验证技能可用

为什么 确认 AI 能理解并遵循技能指导。

操作

询问 AI：

根据 hello-world 技能，向我打招呼

你应该看到： AI 根据技能内容输出友好的问候。

检查点 ✅

完成上述步骤后，检查以下几点：

• [ ] .opencode/skills/hello-world/SKILL.md 文件存在
• [ ] get_available_skills() 能列出 hello-world 技能
• [ ] use_skill("hello-world") 成功加载，无错误
• [ ] AI 能理解并遵循技能内容

如果任何一项不通过，请查看下面的「踩坑提醒」。

踩坑提醒

技能找不到？

错误现象	可能原因	解决方法
插件找不到技能	目录名或文件名错误	确认文件名是 SKILL.md（全大写）
插件找不到技能	Frontmatter 格式错误	检查 --- 是否存在，前后是否有空行
插件找不到技能	name 字段不符合规范	name 必须是小写字母、数字、连字符

解析失败？

错误现象	可能原因	解决方法
YAML 解析失败	Frontmatter 格式不对	确保使用正确的 YAML 格式，字符串用引号包裹
验证失败	name 包含大写字母或特殊字符	name 字段只能是小写字母、数字、连字符
验证失败	description 为空	description 必须有值

常见错误示例

# ❌ 错误：name 包含大写字母
---
name: HelloWorld
description: A skill
---

# ❌ 错误：name 包含空格
---
name: hello world
description: A skill
---

# ❌ 错误：name 包含特殊字符（除连字符）
---
name: hello_world
description: A skill
---

# ✅ 正确
---
name: hello-world
description: A skill for demonstration
---

Frontmatter 字段必填性

字段	是否必填	约束	示例
name	✅ 是	小写字母数字连字符	my-skill
description	✅ 是	非空字符串	A skill for git management
license	❌ 否	开源协议名称	MIT
allowed-tools	❌ 否	工具名称数组	["read", "write"]
metadata	❌ 否	key-value 对象	{"namespace": "project"}

本课小结

本教程讲解了：

1. 技能目录结构：.opencode/skills/<skill-name>/SKILL.md
2. Frontmatter 格式：YAML 格式，包含 name 和 description 必填字段
3. 技能发现规则：从 6 个位置按优先级自动发现
4. 技能加载流程：通过 use_skill 工具加载内容到上下文

现在你已经掌握了创建技能的基础知识。接下来，你将学习插件的技能发现机制，了解它如何自动扫描和管理多个技能。

下一课预告

下一课我们学习 技能发现机制详解。

你会学到：

• 技能发现的 6 个位置及优先级规则
• 同名技能的去重逻辑
• Claude Code 技能的兼容机制
• 如何查询技能的来源和命名空间

---

附录：源码参考

点击展开查看源码位置

更新时间：2026-01-24

功能	文件路径	行号
Frontmatter Schema 定义	src/skills.ts	105-114
解析 SKILL.md 文件	src/skills.ts	122-167
查找技能脚本	src/skills.ts	59-99
技能发现优先级列表	src/skills.ts	241-246
解析 YAML Frontmatter	src/utils.ts	41-49

关键常量：

• 脚本最大递归深度：maxDepth = 10
• 跳过的目录：node_modules, __pycache__, .git, .venv, venv, .tox, .nox

关键函数：

• parseSkillFile()：解析 SKILL.md 文件，验证 Frontmatter 并提取元数据
• findScripts()：递归查找技能目录下的可执行脚本
• discoverAllSkills()：从多个位置发现所有技能