概要
SkillはAIエージェントのための再利用可能なワークフローの単位です。必須のSKILL.mdファイルと任意の補助ファイルからなるディレクトリとして定義し、SKILL.mdに手順を書き起こします。すなわち、ステップごとのガイダンス、固定された出力フォーマット、そして本当に人の判断が必要な決定点です。
一度書けば、コマンドで呼び出すか自動発火で実行され、誰が実行しても同じような結果を生み出します。
本ページでは、Skillの背後にある原則、構造、そして作り方・呼び出し方を解説します。
設計の原則
Skillの目的は、実務に必要な文脈、すなわち組織固有の専門知識と手順をエージェントに渡すことです。その設計は次の4つの原則に立っています。専門知識の集約
組織やチーム固有の手続き的知識をバージョン管理できる形で書き起こし、エージェントが推測ではなく渡された文脈に基づいて動けるようにします。
再現可能なワークフロー
複数ステップのタスクを、誰が実行しても同じ手順をたどる、一貫した監査可能な手続きに変えます。
製品を越えた再利用
一度書けば、Skillに対応したどのエージェント・どの製品でも同じSkillを使えます。
Progressive disclosure
起動時に読み込まれるのは
nameとdescriptionだけで、本文と補助ファイルは必要になったときにのみ読み込まれます。Skillの構造
Skillは専用のディレクトリ（Claude Codeでは.claude/skills/<skill-name>/）に置き、SKILL.mdファイルと任意の補助ファイルで構成します。
ディレクトリ構成
ディレクトリ構成
SKILL.mdの構成
SKILL.mdは2つの部分から成ります。Skillを識別するYAML frontmatterと、指示と例を書くMarkdown本文です。
SKILL.md
Progressive disclosure
Skillは一度にすべて読み込まれるのではなく、段階的に読み込まれます。セッション開始時にエージェントが読むのは、インストール済みSkillのfrontmatterだけです。本文はリクエストがdescriptionに合致したときに読まれ、references/配下のファイルは本文が参照した場合にのみ読まれます。
システムプロンプトやMCPのツール定義に置けば常にコンテキストを占有する指示が、必要になる瞬間までほぼコストゼロになります。
Skillの作り方
発見されるための命名とdescription
nameとdescriptionは、Skillが選ばれる前に読み込まれる唯一の部分です。発見されるかどうかは、この2つにかかっています。
- Skill名は動作を表す小文字とハイフンで付けます。
helperやutilsのような曖昧な名前は避けます。 descriptionは三人称で書き、Skillが何をするかといつ使うかの両方を述べ、ユーザーが実際に言いそうな言葉を含めます。
賢い読み手に向けて書く
エージェントは一般的なプログラミング知識をすでに持っています。書くべきは、エージェントが推測できないことだけです。つまり、自分たちの規約・制約・手順です。 簡潔な指示のほうが網羅的な指示より良い結果を出します。SKILL.mdの本文はおよそ500行以内に保ちます。かさばる資料はreferences/のファイルへ移します。- 参照は1階層に留めます。補助ファイルはすべて
SKILL.mdから直接リンクします。参照の連鎖が深いと、途中のファイルが部分的にしか読まれなくなります。 - 1つの概念には1つの用語を使い続けます（「フィールド」「ボックス」「要素」を混在させず、常に「フィールド」と書きます）。
- 時間に依存する記述（「8月までは旧APIを使う」など）は避けます。気づかないうちに誤りになります。
- 「MUST」「NEVER」「ALWAYS」といった強調の多用は黄色信号です。禁止を並べるより、なぜそうするのかという理由を書くほうが、想定外の場面でもエージェントが適切に判断できます。
- 本筋から外れるケース（引数が渡されない、外部サービスがエラーを返すなど）での動きも書いておきます。手順が正常系だけだと、例外時の挙動が実行のたびに変わります。
出力フォーマットをテンプレートで用意する
出力の一貫性が重要なSkillには、出力フォーマットのテンプレートを用意します。厳密さはタスクに合わせて調整し、構造の参考例を示すだけにも、常にそのとおり出力させる厳密なテンプレートにもできます。- 後続の処理やツールが出力の形式に依存する場合（データフォーマット・定型レポートなど）は、常にこの構造で出力すると明記した厳密なテンプレートを使います。
- 内容に応じて構成が変わってよい場合は、参考のデフォルトとして示し、状況に合わせて調整してよいと添えます。
厳密なテンプレートの例（レポート生成の場合）
入出力の例で示す
スタイル・トーン・詳細度のような、言葉では説明しにくい要素は、入出力のペアで示します。望ましい出力を説明で伝えるより、例で見せるほうが確実に伝わります。本文での例示（commit-messageの場合）
references/のファイルへ分離し、必要なときだけ読ませます。
自由度を壊れやすさに合わせる
タスクの壊れやすさに応じて、指示が残す裁量の幅を決めます。 コードレビューや分析のように複数のアプローチが有効な場面では、判断の指針を示してエージェントに経路を選ばせます。マイグレーションやリリース手順のように壊れやすく一貫性が必須の操作では、正確なコマンドを示し、変更してはならないと明記します。 複数のツールが使える場面では、デフォルトを1つ指名し、それが使えないケースに限って代替を添えます。ツール権限を最小にする
Skillに許可するツールは、ワークフローで実際に使うものだけに絞ります。Claude Codeでは、SKILL.mdのfrontmatterにallowed-toolsとして宣言します。
- 手順に登場しないツールは許可しません。読み取りだけで完結するSkillにWriteやEditは不要です。
- Bashはコマンド単位で絞ります。
Bash(git *)のような広い指定は、Bash(git status*)とBash(git diff*)のような個別指定に分割します。 rmやgit push --forceのような破壊的コマンドは原則許可しません。
allowed-toolsの宣言自体が不要です。
検証を組み込む
複数ステップのSkillは、チェックポイントがないと逸脱します。次の2つのパターンが軌道を保ちます。- チェックリスト。 Skillにステップ一覧を出力させ、進行に合わせてチェックさせます。飛ばされたステップが見えるようになります。
- フィードバックループ。 各出力に検証ステップ（バリデータのスクリプト・lintの実行・チェックリスト照合）を対にし、合格するまで修正と再検証を繰り返してから次へ進むよう指示します。
サブエージェントを束ねる
ステップの多いSkillは、1つのエージェントに全手順を実行させるより、Skill本文を進行役（オーケストレーター）にして、独立したサブタスクをサブエージェントへ切り出すほうが安定します。- 依存関係のないサブタスクは並列に実行させます。観点別のレビューや複数領域の調査を、順番に行う理由はありません。
- 各サブエージェントへの指示は自己完結させます。サブエージェントは呼び出し元の会話を見られないため、必要な文脈はすべてプロンプトで渡します。
- 並列実行のあとには、結果を統合するステップを必ず置きます。
- ステップをまたぐデータの受け渡し（前のステップの出力を次のどのステップで使うか）を本文に明記します。
skill-creatorで作成する
skill-creatorは、新しいSkillの執筆を支援するAnthropic製のツールです。Claude Codeでは公式マーケットプレイスからインストールします。SKILL.md・references/のファイル・必要に応じてscripts/）を生成し、不要になったファイルを整理します。
Skillの呼び出し
Skillの呼び出し方は2通りです。コマンドで明示的に呼ぶ方法と、エージェントがリクエストをdescriptionと照合して自動的に発火させる方法です。
どちらの経路でも同じSKILL.mdが実行されます。コマンドは直接のハンドルにすぎません。
Skillは単発のタスクに限定されません。本文で、確認の質問を挟み、サブエージェントを並列に走らせ、他のSkillをステップとして呼び出す、長い対話的なフローを駆動できます。
Skillが前提とする協働の基礎はVibe Codingを、複数ステップのSkillが活躍する委任型の開発モデルはAgentic Workflowを参照してください。