OpenCode エージェントの作成

高品質な OpenCode エージェントを最適な構成、包括的なドキュメント、スキル統合で作成するエキスパートシステム。

コアプリンシプル

1. エージェントファイルは必ず英語で作成する

重要: ユーザーの言語に関わらず、すべてのエージェントファイルは英語で作成する必須です。

• Frontmatter: description、examples - すべて英語
• システムプロンプト: Role、責務、ワークフロー - すべて英語
• コメントとドキュメント - すべて英語

理由: LLM は英語をより効率的に処理するため、以下が実現します:

• より高速な応答時間
• トークン使用量の削減 (コスト削減)
• より優れたモデル理解
• より一貫した動作

ユーザーが別の言語でのエージェントをリクエストした場合、ファイルを作成する際に要件を英語に翻訳してください。エージェントは会話中にユーザーの希望言語で応答することができます。

2. エージェントは専門の支援者

エージェントが持たないコンテキストのみを追加してください。知性を前提としてください。基礎を教えるのではなく、設定と動作に焦点を当ててください。

3. 標準的な YAML + Markdown 形式

YAML frontmatter + markdown 本文を使用してください。XML タグは使用しない - 標準的な markdown 見出しを使用します。

---
description: 何をするか + いつ使うか + 例
mode: primary|subagent|all
tools: { read: true, write: false }
permission: { bash: ask, edit: deny }
---
あなたは [ROLE]。専門分野は [DOMAIN]。

4. プログレッシブディスクロージャー

• SKILL.md < 650行 (中核となる判断 + クイックリファレンステーブル)
• references/ 詳細なドキュメント (必要に応じてロード)
• templates/ すぐに使えるエージェントテンプレート
• workflows/ ステップバイステップのプロセス

5. 効果的なディスクリプション

使用タイミング (トリガー) と 何をするか を含めてください。三人称で記述してください。<example> ブロックを追加してください。

6. コンテキストファースト (重要なコンテキスト収集)

重要: すべてのエージェントはアクションを取る前にコンテキストを収集する必須です。

Operating Principles に「Context First」サブセクションを含めてください:

### Context First

リクエストに対してアクションを取る前に:

1. **不足しているものを特定する** - どのような仮定を立てていますか? 述べられていない制約は何ですか?
2. **対象を絞った質問をする** - 具体的に、影響度で優先順位付け、関連する質問をグループ化
3. **理解を確認する** - 進める前に理解を要約
4. **オーバーライドを尊重する** - ユーザーが「とにかくやって」などと言った場合は、適切なデフォルトで進める

仮定だけに基づいて重大な変更を進めないでください。

理由: 不完全な情報に基づいて行動するエージェントは害をもたらします。コンテキスト収集は:

• 誤った仮定によるミスを防ぎます
• 明確化を通じてユーザーの信頼を構築します
• より優れた成果と少ない手戻りをもたらします

7. 検証ループ (アクション後の検証)

重要: 変更を加えるすべてのエージェントは結果を検証する必須です。

ファイルを変更したりコマンドを実行するエージェントに「Verification Loop」セクションを含めてください:

## Verification Loop

変更の完了後:

1. **構文チェック** - ファイル構文を検証 (YAML、JSON、コード)
2. **機能テスト** - 関連するコマンドを実行して動作を確認
3. **パーミッションテスト** - アクセス制御が想定通りに機能することを確認

チェックが失敗した場合:
→ 問題を修正
→ 検証を再実行
→ すべてが合格するまで完了を報告しないこと

理由: プロフェッショナルなシステム (Claude Code、Codex、Gemini CLI) はすべて検証ループが必要です。メリット:

• ユーザーが見る前にエラーを捕捉します
• 信頼性を通じて信頼を構築します
• 手戻りの修正を削減します

クイックスタート

何をしたいですか?

1. 新しいエージェントを作成 → Write ツールを使って ~/.config/opencode/agent/<name>.md を作成
2. 既存エージェントを監査 → Read ツールを使ってレビュー、その後 Edit で修正を適用
3. プロンプトをエージェントにアップグレード → プロンプトを読んで、適切なエージェントファイルを作成
4. ガイダンスを取得 → 以下を読み続けてください

重要: このスキルはパッシブな知識です。エージェントを作成する際は、OpenCode の Write および Edit ツールを直接使用してエージェントファイルを作成/変更してください。ユーザーが スクリプトを手動で実行する必要がないようにしてください。scripts/ 内のスクリプトは 検証用のオプション CLI ユーティリティです - 主要なワークフローは直接ファイル作成です。

ワークフロー例:

ユーザー: "データベーススキーマをレビューするエージェントを作成してください"
    ↓
1. エージェントはこのスキルをガイダンス用にロード
2. エージェントは必要に応じてテンプレート/参考資料を読む
3. エージェントは Write ツールを使用して ~/.config/opencode/agent/db-schema-reviewer.md を作成
4. 完了! ユーザーは @db-schema-reviewer を使用できるようになりました

エージェント構造

必須の Frontmatter

フィールド	必須	最大長	例
description	はい	1024文字	何か + いつか + 例
mode	いいえ (デフォルト: all)	-	primary、subagent、all
tools	いいえ	-	{read: true, write: false}
permission	いいえ	-	パーミッションオーバーライド
model	いいえ	-	anthropic/claude-sonnet-4
temperature	いいえ	-	0.1 - 1.0
maxSteps	いいえ	-	5、10、250
hidden	いいえ	-	true (subagents のみ)

完全な仕様は references/frontmatter-spec.md を参照してください。

ネーミング規則

ジェランド形式 (動詞 + -ing) または名詞-ロールを使用してください:

✅ 良い例:

• analyzing-security
• reviewing-code
• security-auditor
• doc-writer
• db-admin

❌ 避けるべき:

• helper、utils、tool
• claude-*、opencode-*
• agent1、my-agent のような曖昧な名前

ボディ構造

---
[frontmatter]
---

あなたは [ROLE/PERSONA]。専門分野は [DOMAIN]。

## Core Responsibilities

1. [主要な責務]
2. [副次的な責務]

## Operating Principles

### Context First

リクエストに対してアクションを取る前に:

1. **不足しているものを特定する** - どのような仮定を立てていますか?
2. **対象を絞った質問をする** - 具体的に、影響度で優先順位付け
3. **理解を確認する** - 進める前に要約
4. **オーバーライドを尊重する** - ユーザーが「とにかくやって」と言った場合、デフォルトで進める

### Safety First

- 常に [ルール]
- しない [アンチルール]

## Workflow

1. **理解** - 要件を明確化
2. **計画** - アプローチを設計
3. **実行** - 実装
4. **検証** - 結果を検証

## Common Tasks

[コマンド付きの例]

エージェント型

詳細なガイドは references/agent-types.md を参照してください。

クイックリファレンス:

型	Mode	ツール	パーミッション	ユースケース
Builder	primary	すべて	edit=ask、bash=ask	フル開発
Planner	primary	read、grep	edit=deny、bash=deny	分析のみ
Reviewer	subagent	read、grep	write=deny	コードレビュー
Executor	subagent	bash、read	bash=patterns	システムタスク
Researcher	subagent	read、webfetch	write=deny	ドキュメント

エージェント複雑さスケール

エージェントに適切なサイズを選択してください:

複雑さ	行数	ツール	maxSteps	使用タイミング
🟢 Micro	50-100	1-2	5-10	単一タスク (git ヘルパー、フォーマットチェッカー)
🟡 Simple	100-200	2-4	10-25	焦点を絞った専門家 (コードレビュアー、ドキュメント作成者)
🟠 Standard	200-400	4-6	25-50	完全なワークフロー (開発者、テスター)
🔴 Complex	400+	6+	50-250	オーケストレーター、マルチドメインコーディネーター

判断ロジック:

単一の焦点を絞ったタスク → Micro
別の場合で 1 ドメイン、少数のツール → Simple
別の場合で完全なワークフロー + 検証 → Standard
別の場合で他のエージェントをコーディネート → Complex

デフォルト: Micro/Simple で開始。証明されたときのみアップグレード。

小さいことが良い理由:

• 呼び出しが高速 (プロンプト解析が少ない)
• 実行が安い (トークンが少ない)
• メンテナンスしやすい
• より予測可能な動作

セキュリティリスクレベル

パーミッション選択に適切なリスクレベルでエージェントを分類してください:

レベル	アイコン	許可されるツール	パーミッションパターン	例
Safe	🟢	read、grep、glob	すべての write/bash = deny	レビュアー、アナライザー
Moderate	🟡	+write、edit	bash = deny、edit = ask	ドキュメント作成者、リファクタラー
Elevated	🟠	+bash (patterns)	特定の許可のみ	ビルドエージェント、テスター
High	🔴	+bash (broad)	危険なすべてに対して ask	DevOps、DB 管理者

リスク評価の質問:

1. このエージェントはファイルを削除できますか? → 🟠 Elevated 以上
2. このエージェントは任意のコマンドを実行できますか? → 🔴 High
3. このエージェントはシークレット/認証情報にアクセスできますか? → 🔴 High
4. このエージェントは読み取り専用ですか? → 🟢 Safe

ルール: デフォルトは 🟢 Safe。各リスク段階の上昇をエージェントのドキュメントで正当化してください。

トーンキャリブレーションガイド

タイプに基づいてエージェント通信スタイルを設定してください:

エージェント型	冗長性	応答の長さ	スタイル
Reviewer	詳細	長い (調査結果報告)	批評的、徹底的
Builder	簡潔	必要に応じて	実用的、コード中心
Researcher	包括的	中程度~長い	有益、出典記載
Executor	最小	短い	直接的、アクション重視
Planner	詳細	長い	分析的、構造化

すべてのエージェントに含めてください:

## Tone and Style

- **Verbosity**: [minimal | concise | moderate | detailed | comprehensive]
- **Response length**: [short: 5-10行 | medium: 10-30行 | long: 30+行 | as needed]
- **Voice**: [通信スタイルを説明する 2-3 個の形容詞]

タイプ別の例:

# Reviewer Agent

## Tone and Style

- Verbosity: detailed - すべての調査結果を証拠と共に含める
- Response length: long - 包括的な監査レポート
- Voice: 批評的、徹底的、客観的

# Builder Agent

## Tone and Style

- Verbosity: concise - コードが語る、最小限のコメント
- Response length: 実装に必要な長さ
- Voice: 技術的、正確、実用的

# Executor Agent

## Tone and Style

- Verbosity: minimal - ステータス更新のみ
- Response length: short - エラー以外は最大 5 行
- Voice: 直接的、アクション重視、効率的

コスト最適化ガイド

パフォーマンスとコストのためにエージェント設定を最適化してください:

モデル選択

タスク型	推奨モデル	トークン/応答	コストレベル
シンプルなルーティング/トリアージ	claude-3-haiku	~500	💰 Low
コードレビュー/分析	claude-sonnet-4	~2000	💰💰 Medium
複雑な推論	claude-opus-4	~4000	💰💰💰 High
クイックルックアップ	claude-3-haiku	~200	💰 Low

ルール: 受け入れ可能な品質を達成できる最小モデルを使用してください。

maxSteps 設定

エージェント型	maxSteps	根拠
Reviewer (読み取り専用)	5-10	スコープが限定、反復不要
Doc writer	10-25	作成と検証
Builder/Developer	25-50	反復実装
Tester	25-50	複数のテストサイクル
Orchestrator	50-250	マルチエージェントコーディネート

警告: maxSteps が高い = コスト上昇の可能性が高い。タスクに適切な制限を設定してください。

Temperature ガイド

ユースケース	Temperature	動作
コード生成	0.1 - 0.3	決定論的、一貫性
分析/レビュー	0.3 - 0.5	バランス、徹底
ドキュメント	0.5 - 0.7	自然、読みやすい
クリエイティブライティング	0.7 - 0.9	バリエーション、表現的

デフォルト: ほとんどの技術エージェントで 0.3。

コスト削減パターン

1. 遅延ロード: 使用しないツールを有効にしない
2. 早期終了: 明確な完了基準を追加
3. スコープ制限: 範囲外のものを明示的に定義
4. バッチ操作: 関連するファイル操作をグループ化
5. キャッシュ結果: 再分析の代わりに以前の調査結果を参照

ツール選択

詳細なガイドは references/tool-selection.md を参照してください。

クイック判断ツリー:

• ファイルを読む必要がありますか? → read: true
• コンテンツを検索する必要がありますか? → grep: true, glob: true
• ファイルを変更する必要がありますか? → write: true, edit: true
• コマンドを実行する必要がありますか? → bash: true
• Web アクセスが必要ですか? → webfetch: true
• サブエージェントをスポーンする必要がありますか? → task: true
• タスク追跡が必要ですか? → todowrite: true, todoread: true

ルール: 最小限から始めてください。エージェントの目的に必要なツールのみを有効にしてください。

パーミッションパターン

完全なライブラリは references/permission-patterns.md を参照してください。

クイック例:

# デフォルトで安全
permission:
  bash:
    "*": ask                    # すべてに対して ask
    "git status*": allow        # 安全なコマンドを許可
    "rm *": deny                # 危険なコマンドを拒否

# 読み取り専用エージェント
permission:
  edit: deny
  write: deny
  bash: deny

# タスク固有 (データベース管理者)
permission:
  bash:
    "*": ask
    "psql -c 'SELECT*": allow
    "psql -c 'DROP*": deny

検証チェックリスト

エージェントを作成する前に確認してください:

• 英語で完全に作成されている (frontmatter、プロンプト、例)
• 有効な YAML frontmatter とディスクリプション名を含む
• ディスクリプションにはトリガーキーワードと <example> ブロックを含む
• ツールがエージェントの目的と一致している
• 危険なツールにはパーミッション制御がある
• システムプロンプトが明確な責務を定義している
• Operating Principles に Context First サブセクションを含む
• ワークフローがドキュメント化されている
• 実際のタスクでテスト済み

完全なルーティックは workflows/audit-agent.md を参照してください。

アクション後検証ループ

重要: エージェントを作成した後、正しく機能することを検証してください。

検証ステップ

# 1. Syntax Check - YAML frontmatter を検証
head -50 ~/.config/opencode/agent/<name>.md | yq .
# エラーなしでパースすること

# 2. File Check - ファイルが作成されたことを確認
ls -la ~/.config/opencode/agent/<name>.md

機能テスト

テスト	方法	期待される結果
呼び出し	@agent-name を入力	エージェントが適切に応答
パーミッション拒否	ブロックされたアクションをリクエスト	エージェントが拒否または質問
パーミッション許可	許可されたアクションをリクエスト	アクション成功
範囲外	無関係なタスクをリクエスト	エージェントが辞退または転向
エッジケース	空/曖昧な入力	エージェントが明確化を要求

検証判断ツリー

1. エージェントファイル作成
   ↓
2. Syntax は有効?
   NO → YAML エラーを修正 → リトライ
   YES ↓
3. シンプルなリクエストで呼び出し
   ↓
4. エージェントが正しく応答?
   NO → プロンプト/ツール編集 → ステップ 3 から リトライ
   YES ↓
5. パーミッション境界をテスト
   ↓
6. パーミッションが期待通りに機能?
   NO → パーミッション設定を修正 → ステップ 3 から リトライ
   YES ↓
7. ✅ エージェントは使用可能

レポートテンプレート

検証後、以下を報告してください:

## Agent Created: {name}

### Configuration

- Mode: {primary|subagent}
- Tools: {リスト}
- Risk Level: {🟢|🟡|🟠|🔴}

### Verification

- [x] YAML syntax 有効
- [x] 呼び出し機能
- [x] パーミッションテスト
- [x] エッジケース処理

### Usage

- 呼び出し: `@{name}` またはタブで切り替え
- 目的: {簡潔な説明}

アンチパターン

完全なリストは references/anti-patterns.md を参照してください。

一般的なミス:

1. ❌ 非英語コンテンツ - 他言語でエージェント作成 (常に英語を使用)
2. ❌ ツールオーバーロード - 「念のため」すべてのツールを有効化
3. ❌ パーミッション甘い - 制御なしで bash: allow
4. ❌ 曖昧なディスクリプション - 「コーディングタスクで支援」
5. ❌ 例不足 - <example> ブロックなし
6. ❌ モード誤り - セキュリティ監査者を subagent ではなく primary として使用
7. ❌ ワークフローなし - プロセスなし指示の積み重ね
8. ❌ 検証スキップ - 作成後のエージェントテストなし
9. ❌ 複雑さ誤り - Simple タスク用に Complex エージェント構築
10. ❌ トーン設定なし - クイックタスク用の冗長なエージェント
11. ❌ コスト無視 - Simple ルーティングタスクに opus 使用
12. ❌ Context First 不足 - エージェントが要件を収集せずに行動

テンプレート

templates/ ディレクトリに即座に使用可能なテンプレート:

基本テンプレート

• simple-agent.md - TODO 付きの基本テンプレート (開始点)

特化したテンプレート

• security-auditor.md - 変更なしのセキュリティレビュー (読み取り専用)
• doc-writer.md - ドキュメンテーション専門家
• db-admin.md - 安全なパーミッション付きのデータベース操作
• code-reviewer.md - コード品質分析 (読み取り専用)
• refactoring-agent.md - コード構造改善
• testing-agent.md - 自動テスト専門家
• api-developer.md - REST/GraphQL API 開発
• devops-agent.md - CI/CD とインフラストラクチャ自動化
• frontend-dev.md - React/Next.js フロントエンド開発

エージェント作成プロセス

完全なステップバイステップワークフローについては、**workflows/create-new-agent.md**を参照してください。

クイックサマリー

1. 理解 → 質問: 目的、トリガー、モード (primary/subagent)
2. 分類 → 判断: タイプ、複雑さ (🟢-🔴)、リスクレベル
3. 作成 → ファイルを ~/.config/opencode/agent/<name>.md に記述
4. 設定 → 設定: ディスクリプション、ツール、パーミッション、トーン
5. 検証 → 実行: Syntax チェック、呼び出しテスト、パーミッションテスト
6. レポート → 使用方法の指示で作成を確認

主要な方法: 直接ファイル作成

ユーザーがエージェント作成をリクエストした場合:

1. 要件を収集 (明確化する質問をする)
2. 関連するテンプレートを読む (`templates