OpenCode Skills 文档

OpenCode Skills 文档

目录

1. 什么是 Skill
2. SKILL.md 文件格式
3. 发现路径与配置
4. 与 MCP、Subagent 的区别
5. 如何注入到 LLM
6. 渐进式加载策略
7. 如何自定义 Skill
8. 远程 Skill 托管

在AI编程这个领域，管理好上下文窗口一直是个让人头疼的问题。一方面希望AI能掌握足够多的项目规范和领域知识，另一方面又不想把宝贵的token浪费在无关信息上。OpenCode引入了一套叫做Skills的机制，试图从根上解决这个矛盾。这套机制不算复杂，但设计上很讲究——尤其是在信息与上下文的博弈上，值得花点时间理清楚。

什么是 Skill

简单点说，Skill就是一个按需加载的Markdown指令文件，专门用来给AI注入专项知识或操作规范。

每个Skill本质上就是一个SKILL.md文件，里面包含两部分内容：首先是YAML frontmatter，用来声明这个skill的名称和用途；然后是Markdown正文，承载具体的指令、规则、示例和各种最佳实践。

AI通过一个叫skill的工具按需加载这些内容，不需要的skill不会占用上下文。这意味着你可以把整个项目的编码规范、框架指南全扔进去，AI只在需要的时候才会读取。

典型用途包括：

• 项目编码规范（命名、文件结构、禁止使用的模式）
• 框架使用指南（比如如何正确使用Effect、React、Prisma）
• 工作流程规范（提交前检查清单、测试策略）
• 领域知识（业务术语定义、架构约束条件）

SKILL.md 文件格式

先看一个标准的SKILL.md文件长什么样：

---
name: my-skill
description: 简短描述这个 skill 的用途（AI 根据此决定是否加载）
---
# 正文内容
这里写具体的指令、规则、示例等。

## 章节一
...

## 章节二
...

Frontmatter 部分只有两个必填字段：

字段	类型	必填	说明
name	string	是	skill 的唯一标识符，用于skill工具调用
description	string	是	单行描述，显示在 AI 的工具描述和系统提示中

拿一个真实项目中的例子来说明。假设有个项目用了Effect-TS，那么在 .opencode/skills/effect/SKILL.md 里可能会写成这样：

---
name: effect
description: Guidelines for writing idiomatic Effect-TS code in this project
---
## Effect Coding Guidelines
- Always use `Effect.gen` for sequential async operations
- Prefer `pipe` over method chaining for readability
- Use `Schema` for all data validation
- Never use `Effect.runSync` in production code

## Error Handling
...

这里的关键是description要写得足够精准——AI就是靠这一行描述来判断要不要加载这个skill。如果描述写得太模糊，AI可能错过它；如果写得有误导性，AI可能在不该加载的时候把它塞进来。

发现路径与配置

OpenCode按以下优先级顺序扫描skill文件：

内置路径（自动扫描）

优先级	路径	用途
1	~/.claude/skills/	Claude 全局 skills
2	~/.agents/skills/	通用 agent skills
3	<项目根>/.opencode/skills/	项目级 skills
4	opencode.json中skills.paths指定的路径	自定义路径
5	opencode.json中skills.urls指定的远程 URL	远程 skills

扫描逻辑很简单：每个目录下的子目录，只要里面包含SKILL.md文件，就自动被视为一个skill。目录结构大致是这样的：

.opencode/
└── skills/
    ├── effect/
    │   └── SKILL.md          ← skill: effect
    ├── testing/
    │   ├── SKILL.md          ← skill: testing
    │   └── examples.md       ← 伴随文件（可在 SKILL.md 中引用）
    └── commit-style/
        └── SKILL.md          ← skill: commit-style

配置文件（opencode.json）

{
  "skills": {
    "paths": [
      "~/my-shared-skills",
      "/team/shared/opencode-skills"
    ],
    "urls": [
      "https://example.com/opencode-skills"
    ]
  }
}

字段	类型	说明
skills.paths	string[]	额外扫描的本地目录（支持~展开）
skills.urls	string[]	远程 skill 包的 URL（见远程托管）

与 MCP、Subagent 的区别

这是很多人容易混淆的地方。Skill、MCP Tool、Subagent这三者虽然都是扩展AI能力的机制，但定位完全不同。用一个表格来对比会清晰很多：

维度	Skill	MCP Tool	Subagent
本质	Markdown 指令文件	可执行工具（函数）	独立 AI 进程
作用	注入知识/规范到 AI	扩展 AI 的操作能力	将子任务委托给另一个 AI
运行时	无副作用，仅读取文本	调用外部进程/API	启动新的 AI 对话
上下文共享	在当前对话中内联	工具结果返回当前对话	独立上下文，结果汇报
定义方式	SKILL.md 文件	服务器进程 + JSON Schema	代码调用 AI API
加载时机	按需（AI 主动调用skill工具）	启动时注册到 LLM	任务执行时动态创建
适合场景	编码规范、领域知识、操作指南	文件读写、代码执行、API 调用	并行任务、隔离复杂子任务

换个更直观的方式来理解：

• Skill
  = 给AI读的"说明书"，告诉它"应该怎么做"

• MCP Tool
  = 给AI用的"工具箱"，让它能"做某件事"

• Subagent
  = 给AI雇的"助手"，让它"帮你做某件事"

如何注入到 LLM

Skills采用的是一套两阶段注入机制，核心目标是在信息可见性和上下文效率之间找到平衡。

阶段一：系统提示列表（每次请求都包含）

每次LLM调用时，系统提示中会自动插入所有可用skill的概览。大概是这个格式：

  
    effect
    Guidelines for writing idiomatic Effect-TS code in this project
  
  
    testing
    Testing strategy and patterns for this codebase
  
  
    commit-style
    Commit message format and branch naming conventions
  

AI看到这个列表后，就知道有哪些skill可用，然后根据当前任务判断是否需要加载。同时，skill工具的描述中也会嵌入可用skill列表（简短格式），供AI调用时参考：

Load the content of a skill.
A vailable skills:
- effect: Guidelines for writing idiomatic Effect-TS code in this project
- testing: Testing strategy and patterns for this codebase
- commit-style: Commit message format and branch naming conventions

阶段二：按需加载（AI 主动调用skill工具）

当AI判断某个skill与当前任务相关时，会调用skill工具：

{
  "tool": "skill",
  "input": { "name": "effect" }
}

工具返回的是完整内容：

## Effect Coding Guidelines
- Always use `Effect.gen` for sequential async operations...

  packages/core/src/effect-utils.ts
  packages/core/src/schema.ts

返回内容包含两部分：skill的完整Markdown指令正文，以及相关文件列表（最多10个）。这个文件列表是怎么来的？OpenCode会用ripgrep在项目中搜索与skill同名的文件，帮助AI快速定位相关代码。

完整流程示意

整个流程走下来是这样的：

会话开始
│
▼
系统提示构建
├─ ...其他系统提示内容...
└─  列表（所有已发现的 skill 名称+描述）
│
▼
LLM 收到请求
├─ 看到  列表，了解有哪些 skill
└─ 根据任务决定是否调用 skill 工具
│
（AI 决定加载某个 skill）
▼
AI 调用: skill("effect")
│
▼
OpenCode 读取 SKILL.md
├─ 解析 frontmatter
├─ 返回完整 Markdown 内容
└─ 附加相关文件列表（ripgrep 搜索）
│
▼
AI 将 skill 内容纳入上下文
└─ 按 skill 指令执行后续任务

渐进式加载策略

渐进式加载（Progressive Loading）是这套机制里最值得细说的部分。它描述的是一种从粗到细、按需展开的资源获取方式。不是一次性把所有相关信息塞进上下文，而是从极低代价的元信息开始，随着任务推进逐步加载更具体的内容。

三个层次

层次 1：描述（系统提示中的 skill 列表）
    ↓  AI 判断与当前任务相关
层次 2：规则（SKILL.md 正文 + 文件列表）
    ↓  AI 判断需要了解具体实现
层次 3：代码（SKILL.md 中列出的资源文件）

层次	内容	上下文代价	何时触发
描述	skill 名称 + 一句话说明	极低（每个 skill ~20 tokens）	每次请求自动包含
规则	SKILL.md 完整正文 + 相关文件列表	中（几百到几千 tokens）	AI 调用skill工具时
代码	文件列表中的实际源码文件	高（按文件大小）	AI 主动读取文件时

核心思想其实很简单：只有真正需要某个层次的信息时，才付出对应的上下文代价。

复杂示例：实现一个新的业务 Service

假设项目背景是这样的——有这样一个目录结构：

.opencode/skills/backend/
├── SKILL.md               ← 规则：Service 编写规范
├── service-template.ts    ← 资源：Service 模板
├── error-codes.md         ← 资源：错误码定义表
└── existing-service-example.ts  ← 资源：现有 Service 示例

现在有一个任务： "帮我实现OrderService，支持创建订单和查询订单详情"

系统提示中包含了这样的内容：

  
    backend
    Service layer patterns, dependency injection rules, and error handling conventions
  
  ...

AI识别到任务需要编写Service，于是决定加载backend skill。此时上下文里只有一句话描述，代价极低。

AI调用：

{ "tool": "skill", "input": { "name": "backend" } }

返回的内容包含具体的规则和文件列表：

## Service 编写规范
### 结构要求
- 每个 Service 必须通过 `Effect.Service` 定义，不能用普通 class
- 依赖其他 Service 通过构造参数注入，禁止在方法内直接 import
- 所有公开方法返回 `Effect`，不允许 throw

### 错误处理
- 业务错误使用 `error-codes.md` 中定义的错误码
- 数据库错误统一包装为 `DatabaseError`，不能透传 Prisma 错误

### 命名约定
- 文件名：`.service.ts`
- 查询方法：`find*`（单个）、`list*`（列表）
- 写入方法：`create*`、`update*`、`delete*`

  .opencode/skills/backend/service-template.ts
  .opencode/skills/backend/error-codes.md
  .opencode/skills/backend/existing-service-example.ts
  packages/api/src/services/user.service.ts
  packages/api/src/services/product.service.ts

现在AI已经知道了三件事：Service的结构规范（Effect.Service、依赖注入、返回类型）、错误处理约定、以及有哪些资源文件可以参考。但此时还没有读取任何资源文件，代价只有SKILL.md正文的tokens。

AI根据任务复杂度决定读取哪些文件。通常会先读模板文件，因为它直接给出了代码骨架：

// service-template.ts
import { Effect, Layer } from "effect"
import { PrismaService } from "./prisma.service"

export class TemplateService extends Effect.Service()("TemplateService", {
  effect: Effect.gen(function* () {
    const prisma = yield* PrismaService
    return {
      findById: (id: string) =>
        Effect.tryPromise({
          try: () => prisma.client.template.findUniqueOrThrow({ where: { id } }),
          catch: (e) => new DatabaseError({ cause: e }),
        }),
    }
  }),
}) {}

export const TemplateServiceLive = TemplateService.Default

有了这个骨架，AI就知道如何套用到OrderService上了。接着，如果需要处理错误，可以去读错误码表：

| 错误码 | 类名 | 含义 |
|--------|------|------|
| ORDER_NOT_FOUND | OrderNotFoundError | 订单不存在 |
| ORDER_ALREADY_PAID | OrderAlreadyPaidError | 订单已支付 |
| INSUFFICIENT_STOCK | InsufficientStockError | 库存不足 |

如果模板已经足够清晰，AI甚至可以跳过existing-service-example.ts和user.service.ts，省下更多的上下文空间。

最终上下文消耗对比：

全量预加载（假设）:
5 个技能 × 平均 2000 tokens = 10,000 tokens（大量无关内容）

渐进式加载（实际）:
层次 1：80 tokens（5 个 skill 的描述）
层次 2：800 tokens（backend SKILL.md 正文）
层次 3：600 tokens（service-template.ts + error-codes.md）
─────────────────────
合计：约 1,480 tokens（节省约 85%）

资源文件的两个来源

skill工具返回的文件列表其实来自两处，AI会根据相关性选择性读取：

来源	示例	特点
skill 目录中的伴随文件	service-template.ts、error-codes.md	由 skill 作者精心准备，直接相关
项目中同名搜索结果	user.service.ts、product.service.ts	ripgrep 搜索 skill 名称找到的真实代码

伴随文件是"教材"（规范示例），项目文件是"参考实现"（已有代码的惯用法）。两者结合，AI既了解规范，又了解当前项目的实际写法。

如何在 SKILL.md 中引导渐进式加载

在SKILL.md正文中主动告诉AI什么时候该读哪个文件，可以让加载行为变得更可预测：

---
name: backend
description: Service layer patterns, dependency injection rules, and error handling conventions
---
## 使用指引
**新建 Service 时：** 先读 `service-template.ts` 获取骨架，再根据需要查阅 `error-codes.md`
**排查错误时：** 直接查阅 `error-codes.md` 中的错误码定义
**不确定惯用法时：** 参考 `existing-service-example.ts` 或项目中现有的 `*.service.ts`

## 规则
...

这样，AI在读完SKILL.md后就能精准判断下一步应该读哪个文件，而不是盲目地读取所有列出的文件。

如何自定义 Skill

步骤一：创建目录结构

# 项目级 skill（推荐）
mkdir -p .opencode/skills/my-skill

# 或全局 skill（所有项目可用）
mkdir -p ~/.claude/skills/my-skill

步骤二：编写 SKILL.md

---
name: my-skill
description: 描述这个 skill 的用途（简洁，一句话）
---
# My Skill

## 规则
1. 规则一：...
2. 规则二：...

## 禁止事项
- 不要做 X
- 避免 Y 模式

## 示例
...

编写时要注意几点：description一定要精准，AI靠它决定是否加载skill；正文使用清晰的Markdown结构，便于AI理解；可以包含代码示例、对比示例（好/坏）；保持专注，一个skill只解决一类问题。

步骤三：添加伴随文件（可选）

可以在同一目录放置辅助文件，比如模板、示例等。AI调用skill时会在文件列表中看到它们：

.opencode/skills/my-skill/
├── SKILL.md       ← 主文件（必须）
├── template.ts    ← 模板文件
└── examples.md    ← 详细示例

步骤四：验证

重启OpenCode后，在对话中测试：

请使用 my-skill skill 帮我...

或者直接询问AI有哪些可用的skill。

远程 Skill 托管

可以将skills托管在HTTP服务器上，方便团队共享。

服务器目录结构

https://example.com/opencode-skills/
├── index.json       ← 索引文件（必须）
├── effect/
│   └── SKILL.md
└── testing/
    └── SKILL.md

index.json 格式

{
  "skills": [
    {
      "name": "effect",
      "files": ["effect/SKILL.md"]
    },
    {
      "name": "testing",
      "files": ["testing/SKILL.md", "testing/examples.md"]
    }
  ]
}

字段	类型	说明
skills	array	skill 列表
skills[].name	string	skill 名称（对应目录名）
skills[].files	string[]	该 skill 包含的文件路径（相对于 URL 根）

配置使用

{
  "skills": {
    "urls": [
      "https://example.com/opencode-skills"
    ]
  }
}

远程skill下载后会被缓存到~/.cache/opencode/skills/，避免每次重复下载，这一点考虑得很周到。

源码位置参考

功能	文件
Skill 服务（发现、加载、fmt）	packages/opencode/src/skill/index.ts
远程 skill 下载	packages/opencode/src/skill/discovery.ts
skill工具定义	packages/opencode/src/tool/skill.ts
工具描述（含 skill 列表）	packages/opencode/src/tool/skill.txt
系统提示注入	packages/opencode/src/session/system.ts
配置 schema	packages/opencode/src/config/skills.ts
工具注册（enriched description）	packages/opencode/src/tool/registry.ts