opencode怎么使用skills

本文最后更新于 2026年1月24日。

在 OpenCode 平台（通常指开源的 AI 编程 Agent 工具，如 opencode-cli）中，Skills（技能） 是一种让 AI 助手按需加载特定知识或自动化脚本的机制。它的核心逻辑是“按需加载”：AI 只有在需要处理特定任务时才会读取技能内容，从而节省上下文窗口（Tokens）。

以下是使用 OpenCode Skills 的详细指南：

1. 技能的基本结构

每一个技能本质上是一个文件夹，里面必须包含一个 SKILL.md 文件。

• 目录结构示例：

  Plaintext

  my-skill/
  ├── SKILL.md       # 核心文件：包含元数据和指令
  ├── scripts/       # (可选) 自动化脚本，如 Python 或 Shell
  └── references/    # (可选) 参考文档、API 规范等
  

• SKILL.md 内容模板：

  文件顶部必须有 YAML 格式的元数据（Frontmatter），这是 AI 识别技能的关键。

  Markdown

  ---
  name: git-expert
  description: 用于编写符合规范的 Git Commit 信息和处理复杂的 Merge 冲突。
  ---
  # Git 专家技能
  当你被要求提交代码时，请遵循以下规范：
  1. 使用 <type>(<scope>): <subject> 格式。
  2. 允许的 type 包括：feat, fix, docs, style, refactor...
  

---

2. 放置技能的位置

OpenCode 会在启动时扫描特定目录。你可以将技能放在以下位置：

• 项目级（仅限当前项目）：

  ./.opencode/skills/<技能名>/SKILL.md

• 全局级（所有项目通用）：

  ~/.config/opencode/skills/<技能名>/SKILL.md

• 兼容模式：

  OpenCode 也支持 Claude Code 的路径：~/.claude/skills/ 或 ./.claude/skills/。

---

3. 在对话中使用 Skills

在 OpenCode 的终端界面（TUI）或 CLI 中，你可以通过以下方式调用技能：

A. 自动触发（推荐）

只要你的 SKILL.md 中的 description 写得清晰，AI 会在识别到相关意图时自动加载。

• 例子：如果描述是“处理数据库迁移”，当你输入“帮我写个迁移脚本”时，AI 会发现匹配并自动激活该技能。

B. 手动强制调用

如果 AI 没有自动识别，你可以直接在对话中命令它：

• "Use the git-expert skill to commit my changes."

• "Load my-skill and run the setup script inside it."

C. 使用命令（新版本特性）

在 OpenCode v1.0.190 后的版本中，你可以使用内置工具命令：

• skill_find "关键词"：搜索相关技能。

• skill_use "技能名称"：强制将该技能加载到当前会话。

---

4. 高级进阶：带脚本的技能

Skills 不仅仅是文档，还可以包含可执行脚本。

1. 在技能文件夹的 scripts/ 下放入脚本（如 optimize_image.py）。

2. 在 SKILL.md 指令中告诉 AI：“如果用户要求优化图片，请运行 ./scripts/optimize_image.py”。

3. AI 在获得授权后，会调用系统 Shell 执行该脚本并获取返回结果。

---

💡 提示：如何写出好的 Skill？

• 描述要“标题党”：技能的 description 是 AI 决定是否加载的唯一依据，写得越明确越好（例如：使用“必须加载此技能来格式化代码”比“这是一个代码格式化器”更有效）。

• 保持精简：不要在一个 Skill 里塞入所有东西。将复杂的任务拆分成多个小 Skill（例如 git-commit 和 git-rebase 分开），可以显著提高 AI 的响应速度。