Skill

Skill 是可重用的任务技能定义。

概述

Skill 是类似于 Command 的功能，但使用 Markdown 文件定义。Skill 可以在 .opencode/skill/ 或 .claude/skills/ 目录中定义，以 SKILL.md 命名。Skill 提供了更灵活的提示词组织和版本控制方式。

定义位置

packages/opencode/src/skill/skill.ts:17-22

属性说明

属性名类型必填说明
namestring是Skill 唯一名称
descriptionstring是Skill 描述
locationstring是Skill 文件路径

TypeScript 类型定义

export type Skill = {
  name: string
  description: string
  location: string
}

Skill 文件格式

Skill 文件使用 Frontmatter 格式：

---
name: frontend-design
description: Create distinctive, production-grade frontend interfaces with high design quality
---

# Frontend Design Skill

This skill is used when the user asks to build web components, pages,
artifacts, posters, or applications.

## When to Use

- User asks to build web components, pages, or applications
- User asks for styling or beautification
- Creating UI or design artifacts

## What to Do

1. Understand the user's requirements
2. Use the skill's specialized knowledge
3. Generate production-grade code
4. Avoid generic AI aesthetics

Skill 目录结构

OpenCode 支持以下目录中的 Skill：

OpenCode 目录

~/.opencode/skill/skill-name/SKILL.md
~/.opencode/skills/skill-name/SKILL.md
./.opencode/skill/skill-name/SKILL.md
./.opencode/skills/skill-name/SKILL.md

Claude 兼容目录

~/.claude/skills/skill-name/SKILL.md
./.claude/skills/skill-name/SKILL.md

优先级：

  1. 项目目录的 .claude/skills/
  2. 项目目录的 .opencode/skill/
  3. 全局目录 ~/.claude/skills/
  4. 全局目录 ~/.opencode/skill/

典型使用场景

1. 获取 Skill 配置

const skill = await Skill.get("frontend-design")

console.log(skill.name) // "frontend-design"
console.log(skill.description) // "Create distinctive..."
console.log(skill.location) // "/path/to/SKILL.md"

2. 列出所有 Skill

const skills = await Skill.all()

for (const skill of skills) {
  console.log(`${skill.name}: ${skill.description}`)
}

3. 读取 Skill 内容

const skill = await Skill.get("test-skill")

// 读取完整的 Markdown 文件
const markdown = await Bun.file(skill.location).text()

// 解析 Frontmatter
const { data, content } = ConfigMarkdown.parse(skill.location)

console.log(data.name) // Skill 名称
console.log(data.description) // Skill 描述
console.log(content) // Skill 正文

4. 在 AI 请求中使用 Skill

当用户请求需要特定技能时，AI 可以使用 Skill 的内容：

// AI 检测到用户需要 frontend-design skill
const skill = await Skill.get("frontend-design")
const markdown = await Bun.file(skill.location).text()

// 将 Skill 内容添加到系统提示词
const systemPrompt = `
You are an AI assistant with access to specialized skills.

Available Skill: ${skill.name}
Description: ${skill.description}

Skill Instructions:
${markdown}
`

Skill 解析

Skill 使用 Frontmatter 解析器读取元数据：

// SKILL.md
// ---
// name: skill-name
// description: Skill description
// ---

const parsed = ConfigMarkdown.parse(skillPath)

// parsed.data = { name, description }
// parsed.content = Markdown 正文

重复名称处理

当多个 Skill 文件具有使用相同名称时：

  • 第一个 Skill 被使用
  • 重复的 Skill 被记录到日志中
  • 可以通过检查 location 字段识别重复

错误处理

InvalidError

当 Skill 文件解析失败时：

class SkillInvalidError {
  data: {
    path: string
    message?: string
    issues?: ZodIssue[]
  }
}

NameMismatchError

当 Frontmatter 中的名称与文件名不匹配时：

class SkillNameMismatchError {
  data: {
    path: string
    expected: string
    actual: string
  }
}

对象关系

Skill 加载流程

变更历史

版本变更内容日期
v1初始 Skill 架构-
v1.1添加 Claude 兼容支持-
v1.2添加 Frontmatter 解析-

相关文档