14.1 Skill 的定义与结构

模型: claude-opus-4-6 (anthropic/claude-opus-4-6) 生成日期: 2026-02-17

---

如果说 Plugin 是对 OpenCode 引擎层的扩展（修改工具、拦截消息、注入参数），那么 Skill 则是对 Agent 知识层的扩展——它向 Agent 注入特定领域的知识、指令和最佳实践。

一个简单的类比：Plugin 像是给汽车加装新的硬件（涡轮增压、导航系统），而 Skill 像是给司机一本新的操作手册（"在雪地驾驶时应该这样做"）。

14.1.1 Skill 文件格式：Markdown

Skill 的定义格式极其简单——一个带 YAML frontmatter 的 Markdown 文件，文件名固定为 SKILL.md：

---
name: git-master
description: Expert at Git operations including atomic commits, rebase, squash, and history search
---

# Git Master Skill

When performing Git operations, follow these guidelines:

## Commit Messages
- Use conventional commits format: `type(scope): description`
- Types: feat, fix, refactor, docs, test, chore
...

## Rebase Strategy
...

Skill 的数据模型由 Zod Schema 定义：

// skill/skill.ts
export const Info = z.object({
  name: z.string(),          // Skill 名称（从 frontmatter 解析）
  description: z.string(),   // Skill 描述
  location: z.string(),      // SKILL.md 文件的绝对路径
  content: z.string(),       // Markdown 正文内容（不含 frontmatter）
})

YAML frontmatter 的解析使用 ConfigMarkdown.parse()——与 OpenCode 的配置文件解析器共享同一套逻辑，支持注释和灵活的格式。

14.1.2 Skill 目录发现机制

Skill 的发现是一个多层扫描过程，按照从全局到项目、从外部到内部的顺序搜索：

搜索层级（优先级从低到高）：

1. 全局外部目录
   ~/.claude/skills/**/SKILL.md
   ~/.agents/skills/**/SKILL.md

2. 项目外部目录（向上遍历到 worktree 根目录）
   <project>/.claude/skills/**/SKILL.md
   <project>/.agents/skills/**/SKILL.md

3. OpenCode 配置目录
   <config-dirs>/{skill,skills}/**/SKILL.md

4. 配置中声明的额外路径
   config.skills.paths 中的目录

5. 远程 URL（通过 Discovery.pull() 下载）
   config.skills.urls 中的地址

源码中的搜索逻辑：

// skill/skill.ts
const EXTERNAL_DIRS = [".claude", ".agents"]
const EXTERNAL_SKILL_GLOB = new Bun.Glob("skills/**/SKILL.md")
const OPENCODE_SKILL_GLOB = new Bun.Glob("{skill,skills}/**/SKILL.md")

const state = Instance.state(async () => {
  const skills: Record<string, Info> = {}

  // 1. 扫描全局外部目录
  if (!Flag.OPENCODE_DISABLE_EXTERNAL_SKILLS) {
    for (const dir of EXTERNAL_DIRS) {
      const root = path.join(Global.Path.home, dir)
      await scanExternal(root, "global")
    }

    // 2. 从项目目录向上扫描到 worktree 根
    for await (const root of Filesystem.up({
      targets: EXTERNAL_DIRS,
      start: Instance.directory,
      stop: Instance.worktree,
    })) {
      await scanExternal(root, "project")
    }
  }

  // 3. 扫描 OpenCode 配置目录
  for (const dir of await Config.directories()) {
    for await (const match of OPENCODE_SKILL_GLOB.scan({ cwd: dir })) {
      await addSkill(match)
    }
  }

  // 4. 扫描配置中的额外路径
  for (const skillPath of config.skills?.paths ?? []) {
    // 支持 ~/ 和相对路径
    const resolved = resolveSkillPath(skillPath)
    for await (const match of SKILL_GLOB.scan({ cwd: resolved })) {
      await addSkill(match)
    }
  }

  // 5. 从远程 URL 下载 Skill
  for (const url of config.skills?.urls ?? []) {
    const list = await Discovery.pull(url)
    for (const dir of list) {
      // ...
    }
  }

  return { skills, dirs }
})

兼容性设计：OpenCode 不仅搜索自己的 .opencode/skills/ 目录，还搜索 .claude/skills/ 和 .agents/skills/——这使得已有的 Claude Code Skill 和其他 Agent 框架的 Skill 可以直接被 OpenCode 使用。

重名处理：如果多个路径中出现同名 Skill，后加载的会覆盖先加载的（项目级覆盖全局级），并记录一条警告日志。

14.1.3 Skill 元数据

每个 Skill 的元数据从 YAML frontmatter 中提取：

字段	必填	说明
name	是	Skill 的唯一标识符
description	是	Skill 的简短描述（会显示给 Agent 和用户）

Skill 的 content 字段是 Markdown 正文——去除 frontmatter 后的纯内容。这个内容会在 Agent 调用 skill 工具时被注入到对话上下文中。

14.1.4 远程 Skill 发现

Discovery.pull() 函数实现了从远程 URL 下载 Skill 的能力：

// skill/discovery.ts
export async function pull(url: string): Promise<string[]> {
  // 1. 获取 index.json（Skill 索引文件）
  const data = await fetch(new URL("index.json", base).href)
    .then(response => response.json())

  // index.json 格式：
  // {
  //   "skills": [
  //     { "name": "git-master", "files": ["SKILL.md", "examples/..."] },
  //     { "name": "frontend-ui", "files": ["SKILL.md"] }
  //   ]
  // }

  // 2. 并行下载每个 Skill 的所有文件
  await Promise.all(list.map(async (skill) => {
    const root = path.join(cache, skill.name)
    await Promise.all(skill.files.map(async (file) => {
      const link = new URL(file, `${host}/${skill.name}/`).href
      const dest = path.join(root, file)
      await get(link, dest)  // 带缓存的下载
    }))
  }))

  return result  // 返回包含 SKILL.md 的目录列表
}

远程 Skill 被下载到缓存目录（~/.cache/opencode/skills/），并且使用文件存在性检查实现简单的缓存——如果文件已存在就跳过下载。

14.1.5 小结

Skill 系统的设计体现了几个理念：

1. 简单的格式：纯 Markdown + YAML frontmatter，不需要编程知识就能创建 Skill。

2. 多源发现：全局目录、项目目录、配置路径、远程 URL——Skill 可以来自任何地方。

3. 跨工具兼容：通过搜索 .claude/ 和 .agents/ 目录，兼容其他 AI 编程助手的 Skill 格式。

4. Instance 级缓存：Skill 列表通过 Instance.state() 管理，每个项目实例有独立的 Skill 集合。