エージェントスキル

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

ファイルの配置

スキル名ごとにフォルダを作成し、その中に 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
• プロジェクト agent 互換： .agents/skills/<name>/SKILL.md
• グローバル agent 互換： ~/.agents/skills/<name>/SKILL.md

発見の仕組み

プロジェクトローカルパスの場合、OpenCode は現在の作業ディレクトリから git ワークツリーのルートまで遡ります。途中の .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 から読み込まれます。

フロントマターの記述

各 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"
    }
  }
}

パターンはワイルドカードをサポート：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 が設定されたスキルはエージェントから隠されます