---
title: "使用 Agent Skills"
description: "理解 OpenCode Agent Skills：放在哪里、怎么写、什么时候加载，以及权限如何控制。"
verifiedAt: "2026-05-09"
---

Agent Skill 是一份可以被 OpenCode 按需加载的操作说明。它平时只暴露名称和描述，Agent 认为需要时，才通过原生 `skill` 工具加载完整 `SKILL.md`。

> [!NOTE]
> **这一篇用 10 分钟换什么**：你会知道 Skill 适合沉淀什么，应该放在哪个目录，`SKILL.md` frontmatter 怎么写，以及如何用权限控制内部 Skill。

## 先给结论：Skill 是流程包，不是大号规则文件

不要把 Skill 当成另一个 `AGENTS.md`。两者职责不同：

| 内容 | 应该放哪里 | 判断标准 |
| --- | --- | --- |
| 项目长期规则 | `AGENTS.md` / Rules | 每次进入项目都要遵守 |
| 一次性命令入口 | Commands | 用户明确调用 `/xxx` |
| 可复用操作流程 | Skill | 某类任务反复出现，但不需要常驻上下文 |
| 角色和权限边界 | Agent | 需要固定“谁来做”和“能做什么” |

Skill 最适合承载发布流程、PR 审查流程、文档生成流程、迁移检查清单、排障 SOP 这类可复用任务。临时要求不要做成 Skill，否则库会越来越臃肿。

## Skill 是怎么被发现和加载的

OpenCode 会先发现可用 Skill，把名称和描述放进 `skill` 工具说明里。Agent 先看摘要，判断需要时再加载完整内容。

```mermaid
flowchart LR
  Start[当前工作目录] --> Walk[向上查找到 git worktree]
  Walk --> Project[项目级 skills]
  Home[用户主目录] --> Global[全局 skills]
  Project --> List[可用技能列表<br/>name + description]
  Global --> List
  List --> Decide{Agent 判断是否需要}
  Decide -->|需要| Load[调用 skill 工具加载 SKILL.md]
  Decide -->|不需要| Skip[不占用上下文]
```

这个机制的关键是：`description` 写得越具体，Agent 越容易在正确时间加载它。

## 放在哪里

为每个 Skill 创建一个文件夹，并在里面放 `SKILL.md`。OpenCode 会搜索这些位置：

| 位置 | 适合场景 |
| --- | --- |
| `.opencode/skills/<name>/SKILL.md` | 当前项目专用 |
| `~/.config/opencode/skills/<name>/SKILL.md` | OpenCode 全局复用 |
| `.claude/skills/<name>/SKILL.md` | 兼容项目里的 Claude Code Skill |
| `~/.claude/skills/<name>/SKILL.md` | 兼容全局 Claude Code Skill |
| `.agents/skills/<name>/SKILL.md` | 兼容其他 Agent 目录 |
| `~/.agents/skills/<name>/SKILL.md` | 全局 Agent 兼容目录 |

选择顺序很简单：

1. 只服务当前仓库，放项目目录。
2. 多个仓库都要用，放全局目录。
3. 已经有 Claude Code Skill 库，优先复用兼容入口，不要复制一份大型目录。

> [!IMPORTANT]
> Skill 的位置就是影响范围。项目专用 Skill 不要放全局，否则其他仓库可能误触发。

## `SKILL.md` frontmatter 怎么写

每个 `SKILL.md` 必须以 YAML frontmatter 开头。官方识别这些字段：

| 字段 | 是否必填 | 用法 |
| --- | --- | --- |
| `name` | 必填 | Skill 名称，必须和目录名一致 |
| `description` | 必填 | 触发条件和产出边界 |
| `license` | 可选 | 分发或团队共享时写清楚 |
| `compatibility` | 可选 | 标明兼容平台，例如 `opencode` |
| `metadata` | 可选 | 字符串到字符串的补充信息 |

未知字段会被忽略，不要把关键约束写在 OpenCode 不识别的 frontmatter 字段里。

## 名称和描述怎么判断

`name` 要满足：

- 长度 1-64 个字符。
- 只用小写字母、数字和单个连字符。
- 不以 `-` 开头或结尾。
- 不包含连续 `--`。
- 与包含 `SKILL.md` 的目录名一致。

等效规则可以记成：

```text
^[a-z0-9]+(-[a-z0-9]+)*$
```

`description` 长度为 1-1024 个字符。它不是广告语，而是给 Agent 的触发条件。不要写 `help with git`，要写清楚“什么时候用、产出什么、有哪些边界”。

## 一个可用的最小 Skill

文件：`.opencode/skills/release-check/SKILL.md`

```md
---
name: release-check
description: Use when preparing a release; checks diff, changelog, tests, version bump, and publish command
license: MIT
compatibility: opencode
metadata:
  workflow: github-release
---

## When to use

Use this when preparing a tagged release or release candidate.

## Steps

1. Read the current diff and changelog.
2. Confirm tests and version bump.
3. Draft release notes.
4. Produce a publish command for human review.

## Boundaries

Do not publish automatically.
Do not include secrets or private customer names.
```

这个 Skill 的重点不是写得长，而是触发条件、步骤和边界都清楚。

## 权限如何控制

在 `opencode.json` 里可以用模式控制 Agent 能访问哪些 Skill：

```jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "skill": {
      "*": "ask",
      "release-check": "allow",
      "internal-*": "deny"
    }
  }
}
```

| 权限 | 行为 |
| --- | --- |
| `allow` | 允许直接加载 |
| `deny` | 对 Agent 隐藏并拒绝访问 |
| `ask` | 加载前先确认 |

模式支持通配符。比如 `internal-*` 可以覆盖 `internal-docs`、`internal-tools` 等内部技能。

> [!WARNING]
> 团队内部 Skill 不要默认全开。涉及发布、凭据、客户项目、生产环境的 Skill，先设为 `ask` 或 `deny`。

## 按 Agent 覆盖权限

你也可以让不同 Agent 使用不同 Skill 权限。比如审查 Agent 可以使用 `documents-*`，但普通聊天 Agent 看不到内部发布 Skill。

自定义 Agent frontmatter 示例：

```yaml
---
permission:
  skill:
    "documents-*": "allow"
    "internal-*": "ask"
---
```

内置 Agent 可以在 `opencode.json` 里覆盖：

```jsonc
{
  "agent": {
    "plan": {
      "permission": {
        "skill": {
          "research-*": "allow"
        }
      }
    }
  }
}
```

## 什么时候禁用 Skill 工具

有些 Agent 不应该加载 Skill：

- 只做规划、不执行流程的 Agent。
- 不应该接触内部资料的 Agent。
- 临时测试 Agent，避免误加载团队 Skill。

可以直接关闭 `skill` 工具。关闭后，可用技能列表会完全省略。

```yaml
---
tools:
  skill: false
---
```

## 排查加载问题

如果某个 Skill 没显示，按这个顺序查：

1. 文件名是否是全大写 `SKILL.md`。
2. frontmatter 是否包含 `name` 和 `description`。
3. `name` 是否和目录名完全一致。
4. 当前启动目录是否位于目标 git 工作树内。
5. 不同位置是否有同名 Skill 冲突。
6. 权限是否被设为 `deny`。

## 新手常见坑

- 描述太泛，Agent 不知道什么时候加载。
- Skill 太大，把整个团队手册塞进一个文件。
- 目录名和 `name` 不一致。
- 项目专用 Skill 放到全局，导致其他仓库误触发。
- 把真实密钥、账号、客户资料写进 Skill。
- 只会用一次的 prompt 也做成 Skill。

## 接下来去哪

<Cards>
  <Card title="配置 Agents" href="/docs/opencode/official/02-agents-skills/agents">
    Skill 只定义流程，Agent 才定义谁来做、能不能改文件、用什么权限。
  </Card>
  <Card title="安装插件" href="/docs/opencode/official/02-agents-skills/plugins">
    如果你要改变 OpenCode 运行时行为，再继续看 Plugin。
  </Card>
  <Card title="编写规则" href="/docs/opencode/official/02-agents-skills/rules">
    长期项目约束应该放 Rules，不要塞进 Skill。
  </Card>
  <Card title="Agents、Skills、Plugins 怎么分" href="/docs/opencode/understanding/05-agents-skills-plugins">
    回到完整分层，判断某个经验该沉淀到哪一层。
  </Card>
</Cards>

## 官方资料

- [OpenCode Agent Skills](https://opencode.ai/docs/skills/)
- [OpenCode configuration](https://opencode.ai/docs/config/)
