Skills

Skills 是一种轻量的“知识/能力片段”，通过 SKILL.md 文件形式存在，可以被 Agent 在需要时加载到上下文中。

适合用来：

• 为某类任务写一份长提示词（Prompt），避免每次手打；
• 保存项目或团队内部的“操作手册”；
• 给 Agent 增强某个领域（如“如何写单元测试”、“如何审查安全问题”）。

---

文件位置

常见放置位置：

• 全局：~/.config/opencode/skills/<name>/SKILL.md
• 项目级：.opencode/skills/<name>/SKILL.md

其中 <name> 是 skill 的名称。

示例：

.opencode/skills/
  api-guidelines/
    SKILL.md
  testing/
    SKILL.md

---

SKILL.md 内容

SKILL.md 一般就是一份 Markdown 文档，可以包含：

• 标题、说明
• 使用步骤
• 代码示例
• 约束/规范

示例：

.opencode/skills/testing/SKILL.md

# Testing Skill

You are an expert at writing unit tests in this repository.

- Prefer table-driven tests where appropriate.
- Use existing helper functions from the `testutil` package.
- Keep tests deterministic and fast.

当 Agent 通过 skill 工具加载该 skill 时，SKILL.md 的内容会注入到当前对话上下文。

---

在对话中使用 Skills

OpenCode 会自动发现可用 Skills，并在需要时通过 skill 工具加载。例如：

• 当你在 Prompt 中提到“使用 testing skill”；
• 或 Agent 认为某个 skill 与当前任务强相关时。

你也可以在 .opencode/AGENTS.md / AGENTS.md 中写规则来提示 Agent 何时使用哪些 skill（参见 Rules 文档）。

---

权限控制

skill 工具也受权限系统控制：

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "skill": "allow"
  }
}

你可以在：

• 全局 permission 中控制是否允许加载 skills；
• Agent 级 permission 中进一步细化（例如只让某些 Agent 使用特定 skill）。

---

最佳实践

• 把“不会经常改动”的团队约定写进 SKILL.md，而不是每次手打长 Prompt；
• 按主题拆分多个 skill，而不是一个超长文件；
• 在 AGENTS.md 里写清楚“什么时候用哪个 skill”。