skillful-subagent-creator

スキルを備えたサブエージェントの作成

厳選されたスキルを標準手順として備えた Claude サブエージェントを作成します。各サブエージェントは「ツールキットを備えた専門家」です。役割を絞り、スキルを少数にし、それらのスキルを適用するための明確なワークフローを定めます。

---

使用するタイミング

✅ 次の場合に使用します：

• 特定の分野を担当する専門サブエージェントを設計する
• サブエージェントに割り当てるスキル（コアスキルを2～5個）を選ぶ
• サブエージェント用の4セクションプロンプト（Identity、Skills、Task Loop、Constraints）を作成する
• サブエージェントをDAGオーケストレーションワークフローに組み込む
• DAGノード間の入出力コントラクトを定義する

❌ 次の場合には使用しません：

• スキル自体を作成する（skill-architect を使用してください）
• スキルを使わない単一エージェント向けのプロンプト作成
• Claude Codeの一般的な機能やMCPのセットアップ

---

サブエージェントの作成手順

flowchart TD
  A[Define the role] --> B[Select 2-5 skills]
  B --> C[Write 4-section prompt]
  C --> D[Define input/output contracts]
  D --> E[Choose DAG position]
  E --> F{Standalone or chained?}
  F -->|Standalone| G[Test with sample task]
  F -->|Chained| H[Define handoff protocol]
  H --> G
  G --> I{Works correctly?}
  I -->|No| C
  I -->|Yes| J[Deploy]

---

ステップ1：役割を定義する

サブエージェントの役割は、専門家として対応できるだけの狭さと、有用であるための広さを備えている必要があります。

flowchart TD
  A{How narrow?} -->|Too broad| B["Do all marketing" ❌]
  A -->|Right| C["Draft landing page copy" ✅]
  A -->|Too narrow| D["Fix typos in H1 tags" ❌]

テスト：具体的な動詞と名詞を使って、このサブエージェントが何をするのかを一文で説明できますか？できない場合は、役割をさらに絞り込んでください。

適切に範囲を定めた役割の例：

役割	分野	説明文
リファクタリング担当	TypeScript	「TypeScriptモノレポで安全なリファクタリングを設計し、実行する」
PRレビュアー	コードレビュー	「プルリクエストの差分を正確性、スタイル、セキュリティの観点からレビューする」
調査結果の統合担当	調査	「複数の情報源から得た調査結果を、出典付きのブリーフィング資料にまとめる」
移行計画担当	データベース	「ロールバック戦略を含むデータベーススキーマの移行を計画する」

---

ステップ2：スキルを選ぶ（2～5個）

スキルはサブエージェントの標準手順です。少なすぎると即興で対応し、多すぎるとコンテキストに圧倒されます。

選定基準

flowchart TD
  A{For each candidate skill} --> B{Needed for >50% of tasks?}
  B -->|Yes| C[Preload into context]
  B -->|No| D{Needed for 10-50%?}
  D -->|Yes| E[Add to dynamic catalog]
  D -->|No| F[Don't include]

3つの読み込み階層

階層	スキル	読み込み方法	トークンコスト
事前読み込み	コアスキルを2～5個	SKILL.md全体をシステムプロンプトに挿入	スキル1つあたり約2～5kトークン
カタログ	利用可能なスキルを5～20個	プロンプトには名前と1行の説明を記載し、必要に応じて読み込む	スキル1つあたり約50トークン
なし	その他すべて	記載しない。エージェントは汎用的な推論を使用	0トークン

スキル選定の例

役割：TypeScript／ReactのPRレビュアー

階層	スキル	理由
事前読み込み	code-review-skill	すべてのタスクの中核となる
事前読み込み	react-server-components	RSCのアンチパターンを見つける
カタログ	typescript-strict-mode	関連する場合がある
カタログ	testing-patterns	テストファイルのレビュー時のみ使用
なし	database-migration	対象範囲外

---

ステップ3：4セクションのプロンプトを作成する

各サブエージェントのプロンプトは、必ず4つのセクションで構成します。この構造により、サブエージェントは自分の役割、ツール、ワークフロー、制約を把握できます。

セクション1：Identity（役割）

You are the **[Role Name]** subagent for this system.
You handle [narrow domain of tasks].
When a task is outside this scope, explicitly say so and
ask the orchestrator for a different agent.

2～4文に収めます。具体的な分野を明示し、担当範囲を明確に示します。

セクション2：スキルの使用ルール

You have access to the following skills, which define your methods:
- `skill-a`: [1-line purpose]
- `skill-b`: [1-line purpose]
- `skill-c`: [1-line purpose]

These are your standard operating procedures, not optional hints.
When tackling a task:
1. Decide which skill(s) apply
2. Follow their step-by-step workflow
3. Use their output formats and checklists
4. Reference skill steps by number as you work

セクション3：タスク処理ループ

For each task you receive:
1. Restate the task in your own words
2. Select one or more skills that fit. If none fit well, say so.
3. If needed, ask 2-5 clarifying questions
4. Produce a short internal plan
5. Execute the skill workflow step by step
6. Run any validation/QA steps from the skill
7. Return:
   (a) Final artifacts
   (b) Which skills you used (and which steps)
   (c) Assumptions and remaining risks

セクション4：制約

Quality bar: [e.g., "Never knowingly leave tests failing"]
Safety: [e.g., "No destructive operations without confirmation"]
Tie-breaking: [e.g., "If speed vs robustness conflict, pick robustness"]
Output format: [e.g., "Always return valid JSON matching the output contract"]

---

ステップ4：入出力コントラクトを定義する

オーケストレーターや後続のエージェントが連携できるよう、各サブエージェントには明示的なコントラクトが必要です。

入力コントラクト

{
  "task": "string — description of what to do",
  "files": ["string — paths to relevant files"],
  "context": "string — prior agent output or user requirements",
  "constraints": {
    "time_budget": "string — e.g., '5 minutes'",
    "quality_bar": "string — e.g., 'production-ready'"
  }
}

出力コントラクト

{
  "status": "pass | warn | fail",
  "artifacts": ["string — files created or modified"],
  "summary": "string — 1-3 sentence description of what was done",
  "skills_used": ["string — skill names and step numbers"],
  "risks": ["string — remaining risks or assumptions"],
  "metadata": {
    "duration_ms": "number",
    "tokens_used": "number"
  }
}

---

ステップ5：DAGワークフローに組み込む

オーケストレーションパターン

flowchart TD
  subgraph "Single Specialist"
    O1[Orchestrator] --> S1[Specialist]
    S1 --> O1
  end

  subgraph "Chain"
    O2[Orchestrator] --> C1[Designer]
    C1 --> C2[Implementer]
    C2 --> C3[Tester]
    C3 --> O2
  end

  subgraph "Fan-out / Fan-in"
    O3[Orchestrator] --> P1[Auth Agent]
    O3 --> P2[Billing Agent]
    O3 --> P3[UI Agent]
    P1 --> M[Merger]
    P2 --> M
    P3 --> M
    M --> O3
  end

パターンの選択

パターン	使用するタイミング	スキル要件
単一の専門家	タスクが1つの分野に対応する	エージェントに2～5個の事前読み込みスキルがある
チェーン	順次処理する変換パイプライン	各エージェントのスキルが異なる。Aの出力をBの入力として渡す
ファンアウト／ファンイン	独立した並行作業	エージェントが並行して作業し、統合担当が競合を解決する
ループ	反復的な改善	品質基準を満たすまで、同じエージェントがフィードバックを受けて再実行する
人間参加型ループ	承認が必要	エージェントが草案を作成し、人間がレビューした後、エージェントが修正する

DAG ノードの定義

DAG 内の各ノードは、次の要素を持つサブエージェントです。

node:
  id: review-pr
  agent: pr-reviewer
  skills: [code-review-skill, react-server-components]
  input_from: [parse-diff]
  output_to: [merge-decision]
  retry: 2
  timeout: 300s
  on_failure: escalate-to-human

---

ステップ 6：テスト

テストプロトコル

1. 正常系：サブエージェントのスキルに完全に合致するタスクを与えます
2. エッジケース：スコープの境界にあるタスクを与えます
3. スコープ外：対象領域外のタスクを与えます。拒否し、その旨を伝える必要があります
4. スキルの適用範囲：場当たり的な推論ではなく、添付されたスキルを使用していることを確認します
5. 出力契約：出力が JSON スキーマに完全に一致することを確認します

危険信号

• スキルに従わず、エージェントが独自のプロセスを作り出す → スキルの使用ルールが十分に強くありません
• エージェントがスコープ外のタスクに対応しようとする → アイデンティティのセクションが十分に明確ではありません
• 出力が契約に一致しない → 制約に明示的な出力形式を追加します
• エージェントがすべての参照を先読みする → プロンプトに遅延読み込みの指示を追加します

---

完全な例：PR レビュアーサブエージェント

設定

name: pr-reviewer
role: "Reviews TypeScript/React pull requests for correctness, style, and security"
skills:
  preloaded:
    - code-review-skill
    - react-server-components
  catalog:
    - typescript-strict-mode
    - testing-patterns
tools: [Read, Grep, Glob]
input_from: [diff-parser]
output_to: [merge-decision]

プロンプト

You are the **PR Reviewer** subagent. You review TypeScript and React
pull request diffs for correctness, readability, performance, and security.
You do NOT implement features, fix bugs, or write new code. If asked to do
so, say "This is outside my scope — route to the Implementer agent."

Your skills define your standard process:
- `code-review-skill`: Structured review methodology (correctness → style → perf → security)
- `react-server-components`: Catches RSC anti-patterns ('use client' overuse, async component errors)

For each PR you receive:
1. Restate what the PR changes and why
2. Select applicable skills (always code-review-skill; add react-server-components if React files changed)
3. Follow the skill's review steps in order
4. Produce findings in the output contract format
5. Summarize: approve, request changes, or block

Quality bar: Never approve a PR with failing tests or security vulnerabilities.
Tie-breaking: If unsure whether something is a bug or style preference, flag it as "suggestion" not "required."
Output: Always return JSON matching the output contract schema.

---

アンチパターン

スキルのないサブエージェント

誤り：役割の説明だけで、スキルを持たないサブエージェントを作成すること。 理由：一貫した方法に従うのではなく、毎回新しいプロセスを独自に考案するようになります。 修正：標準作業手順として、2～5 個のスキルを添付します。

スキルの過剰な割り当て

誤り：1 つのサブエージェントに 15 個のスキルを添付すること。 理由：コンテキストウィンドウを圧迫し、エージェントは実行よりもスキルの選択にトークンを費やします。 修正：事前読み込みは最大 5 個にし、残りはカタログに入れます。オーケストレーターで事前に絞り込みます。

出力契約の欠落

誤り：後続のエージェントが解析できない自由形式のテキストをサブエージェントが返すこと。 理由：次のノードが出力を利用できず、DAG が機能しなくなります。 修正：明示的な JSON 出力契約を定義し、テストで検証します。

スコープクリープ

誤り：スコープ外のタスクを拒否せず、サブエージェントがあらゆることに対応しようとすること。 理由：アイデンティティのセクションで、境界が十分に明確に示されていません。 修正：「X、Y、Z には対応しません。依頼された場合はその旨を伝え、適切なエージェントを案内してください。」を追加します。