読み込み中

設定とマルチファイルスキル

レッスン 310 分
このレッスンの内容このレッスンを終えると、次のことができるようになります
  • allowed-tools や model など、高度なスキルのメタデータフィールドを設定する
  • 適切なリクエストで確実にトリガーされる、効果的なスキルの説明を書く
  • allowed-tools を使って、スキルに必要なツールを事前承認しつつ、Claude をそれらのツールに限定しない
  • progressive disclosure とマルチファイル構造を使って、複雑なスキルを 整理する

設定とマルチファイルスキル

読み込み中

設定とマルチファイルスキル · 4分

要約文字起こし

この動画では、スキルをより強力にする高度なテクニックを取り上げます。主要なメタデータフィールド、確実にトリガーされる説明の書き方、スキルに必要なツールの事前承認、そしてprogressive disclosureを使って大規模なスキルを複数のファイルに整理する方法です。複雑なユースケースに対応しながら、スキルを効率的に保つ方法を学びます。

重要なポイント

  • Claude Codeでは、すべてのフロントマターフィールドが任意ですが、descriptionのみが推奨されています。allowed-toolsとmodelは特に有用な追加フィールドの2つです
  • 優れた説明は2つの質問に答えます。スキルは何をするのか?Claudeはいつそれを使うべきか?
  • allowed-toolsは、スキルが有効な間、リストされたツールを事前承認するため、Claudeは確認なしにそれらを使用できます。また、Claudeをそれらのツールに限定するものでもありません
  • Progressive disclosure(段階的開示):SKILL.mdを500行未満に保ち、Claudeが必要なときにのみ読み込む補助ファイル(リファレンス、スクリプト、アセット)へリンクします
  • スクリプトは内容をコンテキストに読み込まずに実行されます — 出力のみがトークンを消費するため、コンテキストを効率的に保てます

基本的なスキルは名前と説明だけで機能しますが、Claude Codeでスキルをはるかに効果的にするいくつかの高度なテクニックがあります。主要なフィールド、説明のベストプラクティス、ツールの権限、そして大規模なスキルを構造化する方法について見ていきましょう。

スキルのメタデータフィールド

agent skillsのオープンスタンダードは、SKILL.mdフロントマターのコアフィールドを定義しており、Claude Codeはmodelなど独自のフィールドを多数追加しています。Claude Codeでは、すべてのフィールドが任意であり、descriptionのみが推奨されています。まずはこの4つから始めるとよいでしょう(残りはフロントマターリファレンスに記載されています)。

  • name(任意)— スキルを識別します。デフォルトではディレクトリ名が使用されます。Claude.aiまたはClaude APIにスキルをアップロードする場合は必須で、小文字、数字、ハイフンのみを使用して最大64文字に制限されます。
  • description(推奨)— Claudeにそのスキルをいつ使用すべきかを伝えます。Claude.aiまたはClaude APIにスキルをアップロードする場合は必須で、最大1,024文字に制限されます。Claudeはこのフィールドをマッチングに使用するため、最も重要なフィールドです。
  • allowed-tools(任意)— リストされたツールを事前承認し、スキルが有効な間、Claudeが許可を求めずにそれらを使用できるようにします。
  • model(任意)— スキルに使用するClaudeモデルを指定します。

効果的な説明の書き方

指示は明確にしましょう。もし誰かに「あなたの仕事はドキュメントを手伝うことです」と言われたら、何をすればいいか分からないはずです。Claudeも同じように考えます。

優れた説明は2つの質問に答えます。

  1. スキルは何をするのか?
  2. Claudeはいつそれを使うべきか?

期待通りにスキルがトリガーされない場合は、実際にリクエストを表現する際の言い回しに合ったキーワードを追加してみてください。説明はClaudeがスキルの関連性を判断するために使用するものなので、言葉遣いが重要です。

allowed-toolsによるツールの事前承認

スキルが実行のたびに同じ少数のツールに依存しており、呼び出しのたびに手動で承認したくない場合があります。allowed-toolsフィールドは、リストしたツールを事前承認するため、そのスキルを呼び出したターンの残りの間、Claudeは許可プロンプトなしでそれらを使用できます。この許可は、次のメッセージを送信すると解除されます。

エディタで開かれたcodebase-onboardingのSKILL.md。allowed-tools行がハイライトされており、以下のコードブロックに示されています。

この例では、allowed-toolsフィールドはRead, Grep, Glob, Bashに設定されています。このスキルが有効な間、Claudeはこれら4つのツールを許可を求めずに使用できます。他のツールへのアクセスを失うわけではありません。スキルの指示によってClaudeがファイルを編集または書き込む必要が生じた場合、それは他のツール呼び出しと同様に、通常の権限設定を経由します。1つ注意点があります。Bashを単独でリストすると、シェルコマンド全般が事前承認されるため、信頼できるスキルにのみ使用するか、Bash(git status *)のようなパターンに絞り込むようにしてください。

yaml
---
name: codebase-onboarding
description: Helps new developers understand the system works.
allowed-tools: Read, Grep, Glob, Bash
model: sonnet
---

allowed-toolsを完全に省略した場合、何も事前承認されず、Claudeはすべてのツールに対して通常の権限モデルを使用します。逆に、スキルが有効な間にツールを制限したい場合は、別のClaude Codeフロントマターフィールドであるdisallowed-toolsを使用してください。これはリストしたツールをClaudeが使用できるセットから除外します。

Progressive Disclosure(段階的開示)

スキルは、会話とClaudeのコンテキスト ウィンドウを共有します。Claudeがスキルを有効化すると、そのSKILL.mdの内容をコンテキストに読み込みます。しかし、スキルが依存するリファレンス、サンプル、ユーティリティスクリプトが必要になる場合もあります。

すべてを1つの2,000行のファイルに詰め込むと、2つの問題が生じます。コンテキスト ウィンドウの容量を大きく消費することと、保守が面倒になることです。

Progressive disclosureはこれを解決します。SKILL.mdには必須の指示だけを残し、詳細なリファレンス資料は、Claudeが必要なときにのみ読み込む別のファイルに置きます。

オープンスタンダードでは、スキルディレクトリを次のように整理することを推奨しています。

  • scripts/ — 実行可能なコード
  • references/ — 追加のドキュメント
  • assets/ — 画像、テンプレート、その他のデータファイル

その上で、SKILL.mdから補助ファイルへリンクし、いつそれらを読み込むべきかを明確に指示します。

SKILL.mdのレベル2とレベル3のセクションは、architecture-guide.mdとdeep-dive-guide.mdにリンクしており、要求があったときにのみ読み込まれます。

この例では、Claudeはシステム設計について尋ねられたときにのみarchitecture-guide.mdを読み込みます。コンポーネントをどこに追加すればよいかを尋ねられた場合は、そのファイルを読み込むことは一切ありません。これは、コンテキスト ウィンドウにドキュメント全体ではなく、目次だけを持たせているようなものです。

良い経験則として、SKILL.mdは500行未満に保ちましょう。それを超える場合は、内容を別のリファレンスファイルに分割すべきかどうかを検討してください。

スクリプトを効率的に使用する

スキルディレクトリ内のスクリプトは、内容をコンテキストに読み込まずに実行できます。スクリプトが実行され、出力だけがトークンを消費します。SKILL.mdに含めるべき重要な指示は、Claudeにスクリプトを読むのではなく実行するよう伝えることです。

これは特に次のような場合に役立ちます。

  • 環境の検証
  • 一貫性が必要なデータ変換
  • 生成されたコードよりもテスト済みコードとして実行する方が信頼性の高い操作

レッスンの振り返り

  • 複数のファイルを含む、構築したいスキルについて考えてみてください。SKILL.mdと補助的なリファレンスファイルをどのように構成しますか?
  • チームで共有するスキルについて、allowed-toolsでどのツールを事前承認し、どのツールについてはClaudeに引き続き確認してほしいと思いますか?

次のステップ

次のレッスンでは、スキルをClaude Codeをカスタマイズする他の方法 — CLAUDE.md、サブエージェント、フック、MCPサーバー — と比較し、それぞれの状況に適したツールを選べるようにします。