OpenCodeの設定 - SKILL

概要

OpenCodeのスキル機能は、再利用可能な指示セットをSKILL.mdファイルとしてカプセル化し、スラッシュコマンドで呼び出せるようにする仕組みである。

スキルを活用することにより、以下に示すメリットが得られる。

再利用性
頻繁に使用する指示やワークフローをスキルとして定義し、プロジェクト間で共有できる。
一貫性
チーム全体で統一されたタスク実行手順を提供できる。
権限制御
スキルごとに使用可能なツールを制限し、セキュリティリスクを軽減できる。
モジュール性
スキルディレクトリ内にスクリプトやリファレンス等の補助ファイルを含めることができる。

スキルはカスタムコマンドと類似しているが、カスタムコマンドがプロンプトテンプレートを提供するのに対し、スキルはより構造化された指示セットと権限制御を提供する点が異なる。

SKILL.mdの基本構造

スキルは、SKILL.mdファイルによって定義される。
ファイル名は必ず大文字の SKILL.md とする必要がある。(小文字はエラーの原因となる)

SKILL.mdファイルは、YAMLフロントマターと Markdown指示の2つの部分で構成される。

YAMLフロントマター

YAMLフロントマターには、スキルのメタデータを記述する。

基本的なYAMLフロントマターの構造を以下に示す。

 ---
 name: スキル識別子
 description: スキルの説明 (最小20文字)
 license: MIT
 allowed-tools:
    - read
    - grep
    - glob
 metadata:
    internal: false
 ---

下表に、各フィールドの説明を示す。

YAMLフロントマターのフィールド
フィールド	必須	説明
`name`	必須	スキルの一意な識別子小文字とハイフンで構成する。ディレクトリ名と一致させる。
`description`	必須	スキルの機能説明最小20文字以上で記述する。
`license`	任意	ライセンス情報 (例: MIT)
`allowed-tools`	任意	使用可能なツールの制限リスト省略した場合は全ツールが使用可能
`metadata`	任意	カスタムキー・値ペア `internal: true` でスキル検出から非表示にできる。

Markdown指示

YAMLフロントマターの後に、Markdown形式でスキルの詳細な指示を記述する。

Markdown指示の記述例を以下に示す。

 ---
 name: code-review
 description: コードの品質とセキュリティを包括的にレビューする
 allowed-tools:
    - read
    - grep
    - glob
 ---
 
 # コードレビュースキル
 
 ## 概要
 
 このスキルはコードの品質、セキュリティ、パフォーマンスを包括的にレビューします。
 
 ## レビュー観点
 
 1. セキュリティ脆弱性の検出
 2. パフォーマンスへの影響
 3. コーディング規約の遵守
 4. エラーハンドリングの適切性
 
 ## 出力形式
 
 - 問題の重要度 (高/中/低)
 - 問題の説明
 - 改善提案

Markdown指示は、200行以下に収めることが推奨される。

ディレクトリ構造

スキルは、プロジェクト固有またはグローバルの2か所に配置できる。

スキルの配置ディレクトリ
スコープ	ディレクトリパス	説明
プロジェクト固有	.opencode/skills/	現在のプロジェクトのみで使用可能
グローバル	~/.config/opencode/skills/	全プロジェクトで使用可能

スキルディレクトリの標準的なレイアウトを以下に示す。

# プロジェクト固有 (例: QML/C++プロジェクト)
.opencode/
   skills/
      qt-api/                # Qt APIリファレンス調査スキル
         SKILL.md            #   スキル定義 (必須)
         references/          #   リファレンスドキュメント (任意)
            qt-widgets.md
      qml-design/            # QML UI設計ガイドスキル
         SKILL.md            #   スキル定義 (必須)
         assets/              #   アセットファイル (任意)
            component-template.qml
      cpp-optimization/      # C++パフォーマンス最適化スキル
         SKILL.md            #   スキル定義 (必須)
         scripts/             #   補助スクリプト (任意)
            profiler-helper.sh

# グローバル
~/.config/opencode/
   skills/
      doc-gen/               # ドキュメント生成スキル
         SKILL.md
      commit-review/         # コミットレビュースキル
         SKILL.md

同名のスキルがプロジェクト固有とグローバルの両方に存在する場合、プロジェクト固有のスキルが優先される。
重複する場合は警告がログに記録される。

スキルの作成手順

ステップ1 : スキルディレクトリの作成

スキル用のディレクトリを作成する。
ディレクトリ名がスキルの識別子となる。

# プロジェクト固有のスキルを作成する場合
mkdir -p .opencode/skills/my-skill

# グローバルスキルを作成する場合
mkdir -p ~/.config/opencode/skills/my-skill

ステップ2 : SKILL.mdファイルの作成

スキルディレクトリ内に SKILL.md ファイルを作成する。

ファイル名は必ず大文字の SKILL.md とすること。

 ---
 name: my-skill
 description: カスタムスキルの説明をここに記述する
 ---
 
 # My Skill
 
 ## 概要
 
 このスキルの目的と機能を記述する。
 
 ## 実行手順
 
 1. 最初のステップ
 2. 次のステップ
 3. 結果の報告

ステップ3 : 補助ファイルの配置 (任意)

必要に応じて、スキルディレクトリ内に補助ファイルを配置する。

scripts/
実行可能なヘルパースクリプトを配置する。
references/
スキルが参照するドキュメントを配置する。
assets/
出力で使用するテンプレートやリソースを配置する。

ステップ4: 動作確認

OpenCodeセッション内で /my-skill と入力して、スキルが呼び出されることを確認する。

スキルが認識されない場合は、OpenCodeを再起動する。

スキルの呼び出し方法

スラッシュコマンドによる呼び出し

チャット入力欄に /<スキル名> と入力することで、スキルを呼び出せる。

/code-review
/seo-audit
/translate

TUI (ターミナルUI) では、スキルは :skill サフィックス付きで表示され、カスタムコマンドと区別できる。

AIエージェントによる自動呼び出し

AIエージェントは、使用可能なスキルを自動的に検出し、タスク実行時に必要に応じてスキルを活用する。
この場合、ユーザが明示的にスキルを呼び出す必要はない。

エージェントによる自動呼び出しは、スキルのメタデータに基づいて判断される。
自動呼び出しを無効にしたい場合は、YAMLフロントマターで設定することができる。

ツールアクセスの制御

有効化 / 無効化

スキルのYAMLフロントマターの allowed-tools フィールドを使用して、スキルが使用できるツールを制限できる。

allowed-tools を省略した場合は、全てのツールが使用可能となる。

ツールを制限する例を以下に示す。

以下の例では、スキルは read、grep、glob ツールのみを使用でき、ファイルの書き込みやシェルコマンドの実行は制限される。

 ---
 name: read-only-audit
 description: 読み取り専用のコード監査を実施する
 allowed-tools:
    - read
    - grep
    - glob
 ---

権限設定

スキルの権限は、エージェントの権限と組み合わせて最終的なアクセス権が決定される。

権限マージのルールは以下の通りである。

エージェントのツール権限を取得する。
スキルの allowed-tools でさらに制限する。
最終的なツール利用可能性が決定される。

つまり、スキルはエージェントの権限を超えてツールを使用することはできない。
例えば、エージェントが write ツールを deny に設定している場合、スキルの allowed-tools に write を含めても書き込みは拒否される。

この仕組みにより、スキル権限昇格攻撃 (skill escalation) を防止することができる。

実用例

SEO監査スキル

Web記事のSEO最適化を監査するスキルの例を以下に示す。

 ---
 name: seo-audit
 description: Web記事のSEO最適化を包括的に監査し改善提案を提供する
 license: MIT
 allowed-tools:
    - read
    - grep
 ---
 
 # SEO監査スキル
 
 ## 概要
 
 このスキルはWeb記事のSEO最適化を評価し、改善提案を提供します。
 
 ## 監査項目
 
 1. タイトルタグの最適化
 2. メタディスクリプションの長さと品質
 3. 見出し構造 (H1-H6) の適切性
 4. キーワード密度の分析
 5. 内部リンク・外部リンク構造
 6. 画像のalt属性
 
 ## 出力形式
 
 - 項目ごとのスコア (1-10)
 - 具体的な改善提案
 - 優先度別のアクションリスト

セキュリティ検査スキル

コードのセキュリティ脆弱性を検査するスキルの例を以下に示す。

 ---
 name: security-check
 description: コードベースのセキュリティ脆弱性を検査し報告書を作成する
 allowed-tools:
    - read
    - grep
    - glob
 ---
 
 # セキュリティ検査スキル
 
 ## 概要
 
 このスキルはコードベースのセキュリティ脆弱性を包括的に検査します。
 
 ## 検査項目
 
 1. SQLインジェクション脆弱性
 2. クロスサイトスクリプティング (XSS)
 3. 認証・認可の問題
 4. ハードコードされた認証情報
 5. 安全でない依存関係
 
 ## 出力形式
 
 - 脆弱性の重要度 (Critical/High/Medium/Low)
 - 脆弱性の説明と影響範囲
 - 修正方法の提案

ドキュメント生成スキル

ソースコードからドキュメントを自動生成するスキルの例を以下に示す。

 ---
 name: doc-gen
 description: ソースコードからAPIドキュメントを自動生成する
 allowed-tools:
    - read
    - grep
    - glob
    - write
 ---
 
 # ドキュメント生成スキル
 
 ## 概要
 
 このスキルはソースコードを分析し、APIドキュメントを自動生成します。
 
 ## 対象
 
 - 関数・メソッドのシグネチャ
 - パラメータの型と説明
 - 戻り値の型と説明
 - 使用例
 
 ## 出力形式
 
 Markdownファイルとして出力します。

推奨される事柄

スキル設計の指針

明確な説明を記述する
description フィールドには、スキルの機能、制限、推奨用途を具体的に記述する。最小20文字以上とする。
具体的な指示を提供する
曖昧な指示ではなく、具体的な手順や評価基準を記述する。
ファイル名を正確に記述する
スキル定義ファイルは必ず大文字の SKILL.md とする。小文字の skill.md はエラーの原因となる。

権限の制限

必要最小限のツールのみを allowed-tools に指定する
セキュリティリスクを軽減するため、スキルが必要としないツールは制限する。
読み取り専用のスキルには書き込みツールを含めない
監査系スキルは read、grep、glob のみに制限することを推奨する。

コンテンツの最適化

Markdown指示は200行以下に収める
コンテキストウィンドウの効率化のため、簡潔な記述を心がける。
補助ファイルを活用する
詳細な参考資料は references/ ディレクトリに配置し、SKILL.md本体はコンパクトに保つ。

チームでの共有

プロジェクト固有のスキルはバージョン管理に含める
.opencode/skills/ ディレクトリをGitリポジトリにコミットする。
グローバルスキルは個人の環境に留める
~/.config/opencode/skills/ のスキルはバージョン管理に含めない。

トラブルシューティング

スキルが認識されない

スキルが / コマンドとして表示されない場合は、以下に示す事柄を確認する。

ファイル名を確認する。
ファイル名が大文字の SKILL.md であることを確認する。

小文字の skill.md は認識されない。
ディレクトリ構造を確認する。
.opencode/skills/スキル名/SKILL.md の構造になっているか確認する。

SKILL.mdがスキルディレクトリの直下に配置されているか確認する。
YAMLフロントマターの構文を確認する
YAMLの構文が正しいか確認する。

インデントにはスペースを使用し、タブは使用しない。
name フィールドを確認する
name フィールドの値がディレクトリ名と一致しているか確認する。
OpenCodeを再起動する
スキルを追加した後、OpenCodeを再起動することで反映される場合がある。

スキルの説明が短すぎるとエラーになる

description フィールドは最小20文字以上が必要である。
短い説明を指定した場合はエラーが発生する。

 # 正しい例
 ---
 name: my-skill
 description: プロジェクトのコード品質を包括的に評価する監査スキル
 ---
 
 # エラーになる例
 ---
 name: my-skill
 description: 短い説明
 ---

allowed-toolsで指定したツールが使用できない

allowed-tools で指定したツールが使用できない場合は、以下に示す事柄を確認する。

エージェントの権限を確認する
スキルはエージェントの権限を超えてツールを使用することはできない。

エージェント側でツールが deny に設定されている場合、スキルからも使用できない。
ツール名の正確性を確認する
allowed-tools に指定するツール名が正しいか確認する。

参考リンク

項目	スキル (SKILL.md)	カスタムコマンド
定義場所	.opencode/skills/スキル名/SKILL.md	.opencode/commands/コマンド名.md
ツール制限	`allowed-tools` で制御可能	制限なし
補助ファイル	ディレクトリ内に配置可能	単一ファイル
引数	なし	`$ARGUMENTS`、`$1`/`$2` 等のプレースホルダー対応
AI自動呼び出し	エージェントが自動的に検出・使用	ユーザが明示的に呼び出し