「エージェントスキル」

「SKILL.md定義による再利用可能な動作の定義」

エージェントスキルにより、OpenCode はリポジトリまたはホームディレクトリから再利用可能な命令を検出できます。スキルはネイティブの skill ツールを介してオンデマンドでロードされます。エージェントは利用可能なスキルを確認し、必要に応じて完全なコンテンツをロードできます。

ファイルを配置する

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

プロジェクト構成: .opencode/skills/<name>/SKILL.md
グローバル構成: ~/.config/opencode/skills/<name>/SKILL.md
Project Claude互換: .claude/skills/<name>/SKILL.md
グローバルクロード互換: ~/.claude/skills/<name>/SKILL.md
プロジェクトエージェント互換: .agents/skills/<name>/SKILL.md
グローバルエージェント互換: ~/.agents/skills/<name>/SKILL.md

発見を理解する

プロジェクトのローカルパスの場合、OpenCode は現在の作業ディレクトリから git ワークツリーに到達するまで進みます。途中で、一致する skills/*/SKILL.md を .opencode/ に読み込み、一致する .claude/skills/*/SKILL.md または .agents/skills/*/SKILL.md を読み込みます。

グローバル定義は、~/.config/opencode/skills/*/SKILL.md、~/.claude/skills/*/SKILL.md、および ~/.agents/skills/*/SKILL.md からもロードされます。

前付を書く

各 SKILL.md は YAML フロントマターで始まる必要があります。次のフィールドのみが認識されます。

name (必須)
description (必須)
license (オプション)
compatibility (オプション)
metadata (オプション、文字列間のマップ)

不明なフロントマターフィールドは無視されます。

名前を検証する

name は次のことを行う必要があります。

1 ～ 64 文字であること
単一のハイフンで区切られた小文字の英数字であること
- で開始または終了しない
連続した -- を含まない
SKILL.md を含むディレクトリ名と一致する

同等の正規表現:

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

長さのルールに従ってください

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

例を使用する

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

---
name: git-release
description: Create consistent releases and changelogs
license: MIT
compatibility: opencode
metadata:
  audience: maintainers
  workflow: github
---

## What I do

- Draft release notes from merged PRs
- Propose a version bump
- Provide a copy-pasteable `gh release create` command

## When to use me

Use this when you are preparing a tagged release.
Ask clarifying questions if the target versioning scheme is unclear.

ツールの説明を認識する

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 などに一致します。

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

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

カスタムエージェントの場合 (エージェントフロントマター内):

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

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

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

スキルツールを無効にする

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

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

---
tools:
  skill: false
---

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

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

無効にすると、<available_skills> セクションが完全に省略されます。

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

スキルが表示されない場合:

SKILL.md のスペルがすべて大文字であることを確認してください
フロントマターに name と description が含まれていることを確認します
スキル名がすべての場所で一意であることを確認する
権限を確認してください - deny のスキルはエージェントから非表示になります