Skillsフロントマター設計パターン——context:fork・argument-hint・allowed-toolsを組み合わせる【CCA Foundations対策】

Anthropic Academyの「Claude Code in Action」コースをもとに解説しています。

.claude/skills/ のSKILL.mdに書けるfrontmatterには context: fork・argument-hint・allowed-tools の3つがある。d03でそれぞれの機能は整理したが、重要なのは「どの問題にどれを使うか」という設計の判断軸だ。

この記事でわかること：

context: fork の本質が「コンテキストの量」ではなく「推論汚染の防止」である理由
argument-hint・allowed-tools がプロンプト指示と何が違うのか
3つのfrontmatterを組み合わせて複数の問題を一度に解決するパターン

context: fork が解決する2種類の問題

context: fork の説明として「大量のファイルを読んでもメイン会話が膨らまない」という量の観点がよく挙げられる。それは正しいが、見落とされやすいもう一つの観点——推論汚染——が設計上より重要になる場面がある。

量の問題

大量のファイルを走査するスキル（コードベース全体の分析など）をメイン会話で実行すると、コンテキストウィンドウが急速に埋まる。context: fork を使うとスキルは独立したサブエージェントのコンテキストで動くため、メイン会話はクリーンなまま保たれる。

推論汚染の問題（より重要なケース）

探索スキルで「アーキテクチャの代替案を検討する」という処理を行ったとする。そのスキルの中でClaudeが複数のアプローチを検討し、最終的にAプランを採用してBプランを放棄したとする。

context: fork なしでこのスキルを実行すると、Bプランへのすべてのやりとりがメインセッションのコンテキストに残る。後続の「実装してください」という会話でClaudeがBプランの断片を拾ってきたり、「以前検討したアプローチとして」と言及したりする事態が起こりうる。

context: fork を設定すると探索中の推論はサブエージェントのコンテキストに閉じる。スキルが返す要約だけがメイン会話に届くため、放棄されたアプローチが後続の実装を汚染しない。

---
# .claude/skills/explore-alternatives/SKILL.md
description: アーキテクチャの代替案を検討し、推奨を1つ返す
context: fork
---
以下の観点から複数のアプローチを検討し、最終的に1つの推奨案とその理由を返すこと。
...

argument-hint と allowed-tools：プロンプト指示との違い

argument-hint：引数なし呼び出しの防止

スキルが $ARGUMENTS を使う場合、開発者が引数なしで呼び出すとファイル名が空になるなどの問題が起きる。

プロンプトの中に「引数を指定してください」と書いても効果は薄い——スキルを呼び出す段階では引数を省略することがそもそもできてしまうからだ。

argument-hint はコマンドのオートコンプリート表示に期待する引数のヒントを出す。開発者がスキルを入力した瞬間に「何を指定すべきか」がわかる。

---
argument-hint: "マイグレーション名（例: add_user_roles）"
---

allowed-tools：破壊的操作のブロック

スキルが process_refund などの副作用ツールにアクセスできる状態で、プロンプトに「破壊的なことはしないでください」と書いても確率的な制御しかできない。

allowed-tools はスキルが呼び出せるツールをリスト単位で制限する。これはClaudeに渡されるツール定義の段階で除外されるため、プロンプト指示に依存しない決定論的な制御になる。

---
allowed-tools: Read, Grep, Bash(ls), Bash(cat)
---

ファイル読み込みだけを許可し、書き込み・削除・外部API呼び出しを不可にするといった設計が可能だ。

3つを組み合わせる設計パターン

たとえばデータベースマイグレーションファイルを生成するスキルで、次の3つの問題が同時に起きているとする：

引数なしで呼び出されてファイル名が空になる
過去の会話のスキーマ詳細が混入して誤った前提でマイグレーションが生成される
クリーンアップ用のツールに誤ってアクセスしてデータを削除する

それぞれの解決策を対応させると：

問題	解決する設定	理由
引数なし呼び出し	`argument-hint`	入力時に何を指定すべきかを表示する
過去コンテキストの混入	`context: fork`	実行を独立したサブエージェントに分離する
破壊的ツールへの誤アクセス	`allowed-tools`	ファイル書き込みのみに制限する

---
description: データベースマイグレーションファイルを生成する
argument-hint: "マイグレーション名（例: add_user_roles）"
context: fork
allowed-tools: Read, Write(db/migrations/*)
---

マイグレーション名: $ARGUMENTS

以下の形式でマイグレーションファイルを `db/migrations/` に作成すること。
...

3つの問題を3つのfrontmatterが解決している。プロンプト指示だけで解決しようとすると、Claudeが「従う」かどうかが確率的になる。frontmatterは実行環境レベルの制御なので、LLMの出力に依存しない。

まとめ

context: fork：探索スキルの推論汚染を防ぐ。量の問題だけでなく「放棄された推論がメイン会話に残る」問題も解決する
argument-hint：スキルの入力時にヒントを表示して引数なし呼び出しを防ぐ
allowed-tools：ツールをリスト制限する決定論的な制御。プロンプト指示より確実

3つの設定を個別ではなく「問題→解決策のセット」として理解しておくと、実際の設計判断でも迷いが少なくなる。

次の記事（#7）は .mcp.json を使ったプロジェクトスコープのMCP設定とチーム共有パターンを解説する。