エージェントスキル

エージェントスキルにより、OpenCode はリポジトリやホームディレクトリから再利用可能な指示を検出できます。スキルはネイティブの skill ツールを介してオンデマンドで読み込まれ、エージェントは利用可能なスキルを把握し、必要に応じて完全なコンテンツを読み込めます。

ファイルを配置する

スキル名ごとに 1 つのフォルダを作成し、その中に SKILL.md を配置します。 OpenCode は次の場所を検索します。

プロジェクト設定：.opencode/skills/<name>/SKILL.md
グローバル設定：~/.config/opencode/skills/<name>/SKILL.md
プロジェクト Claude 互換：.claude/skills/<name>/SKILL.md
グローバル Claude 互換：~/.claude/skills/<name>/SKILL.md
プロジェクトエージェント互換：.agents/skills/<name>/SKILL.md
グローバルエージェント互換：~/.agents/skills/<name>/SKILL.md

検出の仕組みを理解する

プロジェクトローカルパスでは、OpenCode は現在の作業ディレクトリから git worktree に到達するまで上位にたどります。その途中で .opencode/ 内の skills/*/SKILL.md、および .claude/skills/*/SKILL.md と .agents/skills/*/SKILL.md の合致するものをすべて読み込みます。

グローバル定義は ~/.config/opencode/skills/*/SKILL.md、~/.claude/skills/*/SKILL.md、~/.agents/skills/*/SKILL.md からも読み込まれます。

frontmatter を記述する

各 SKILL.md は YAML frontmatter で始める必要があります。認識されるフィールドは次のものだけです。

name (必須)
description (必須)
license (任意)
compatibility (任意)
metadata (任意、文字列から文字列へのマップ)

未知の frontmatter フィールドは無視されます。

名前を検証する

name は次の条件を満たす必要があります。

1〜64 文字
単一のハイフン区切りを使用した小文字の英数字
ハイフン - で始まったり終わったりしない
連続する -- を含まない
SKILL.md を含むディレクトリ名と一致する

同等の正規表現は次のとおりです。

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

長さのルールに従う

description は 1〜1024 文字である必要があります。エージェントが正しく選択できるよう、十分に具体的な内容にしてください。

例を使用する

.opencode/skills/git-release/SKILL.md を次のように作成します。

---
name: git-release
description: 一貫したリリースと変更履歴を作成します
license: MIT
compatibility: opencode
metadata:
  audience: maintainers
  workflow: github
---

## 私の機能

- マージされた PR からリリースノートを起草する
- バージョンバンプを提案する
- コピー＆ペースト可能な `gh release create` コマンドを提供する

## いつ使用するか

タグ付きリリースを準備する際にこれを使用します。
対象のバージョニング方針が不明確な場合は、明確化のための質問を行います。

ツールの説明を認識する

OpenCode は skill ツールの説明内で利用可能なスキルを表示します。各エントリには、スキル名と説明が含まれます。

<available_skills>
  <skill>
    <name>git-release</name>
    <description>Create consistent releases and changelogs</description>
  </skill>
</available_skills>

エージェントはツールを呼び出すことでスキルを読み込みます。

skill({ name: "git-release" })

権限を設定する

opencode.json のパターンベースの権限を使用して、エージェントがアクセスできるスキルを制御します。

{
  "permission": {
    "skill": {
      "*": "allow",
      "pr-review": "allow",
      "internal-*": "deny",
      "experimental-*": "ask"
    }
  }
}

権限	振る舞い
`allow`	スキルはすぐに読み込まれる
`deny`	スキルはエージェントから非表示になり、アクセスは拒否される
`ask`	読み込み前にユーザーに承認を求めるプロンプトが表示される

パターンはワイルドカードをサポートします。internal-* は internal-docs、internal-tools などに一致します。

エージェントごとに上書きする

特定のエージェントにグローバルデフォルトとは異なる権限を与えます。

カスタムエージェントの場合 (エージェントの frontmatter 内)：

---
permission:
  skill:
    "documents-*": "allow"
---

組み込みエージェントの場合 (opencode.json 内)：

{
  "agent": {
    "plan": {
      "permission": {
        "skill": {
          "internal-*": "allow"
        }
      }
    }
  }
}

skill ツールを無効化する

スキルを使用すべきでないエージェントに対して、スキルを完全に無効化します。

カスタムエージェントの場合：

---
tools:
  skill: false
---

組み込みエージェントの場合：

{
  "agent": {
    "plan": {
      "tools": {
        "skill": false
      }
    }
  }
}

無効化されている場合、<available_skills> セクションは完全に省略されます。

読み込みのトラブルシューティング

スキルが表示されない場合は、次のことを確認します。

SKILL.md がすべて大文字で記述されているか
frontmatter に name と description が含まれているか
スキル名がすべての場所で一意であるか
権限を確認する — deny が設定されたスキルはエージェントから非表示になります