skills-best-practices

Skills のベストプラクティス

あらゆるエージェント向けの Agent Skills を構築するための独自のガイドです。Agent Skills オープン標準、Anthropic の公式ガイダンス、実運用で得られた経験をまとめ、公式見解から異なる箇所にはその旨を記しています。Skills は、特定のタスクへの対処方法をエージェントに教える手順、スクリプト、リソースを含むフォルダーです（多くの場合、ファイルは 1 つだけです）。

クイックスタート

最小限の skill は、SKILL.md ファイルを含むディレクトリです。

my-skill/
├── SKILL.md          # Required - instructions with YAML frontmatter
├── references/       # Optional - detailed docs loaded on demand
├── scripts/          # Optional - executable code
└── assets/           # Optional - templates, fonts, icons

最小限の SKILL.md：

---
name: my-skill-name
description: What it does. Use when [specific triggers].
---

# My Skill Name

[Instructions here]

frontmatter で必須なのは name と description だけです。

設計の基本原則

単一ファイルと references/ の使い分け（最重要）

基本的には、単一の SKILL.md を使用してください。 1 つのファイルなら、誰かに渡したり、gist にしたり、CLI バイナリに埋め込んだり、<tool> skill サブコマンドで表示したりできます。ディレクトリではできません。次の両方に当てはまる場合にのみ、references/ に分割してください。

1. 条件付き読み込み：意味のある分量のコンテンツが、一部の呼び出しでのみ必要となる（例：DOCX タスクの大半では参照されない変更履歴付き文書）。毎回の呼び出しで全体を読むのであれば、分割しても Read の往復が増え、共有しやすさが損なわれるだけで、何も節約できません。
2. サイズの制約：本文が以下の推奨上限を超える。

配布上の要件を優先してください。 skill を 1 つのファイルとして配布する必要がある場合（CLI に同梱する、コマンドで表示する、貼り付けて共有するなど）は、サイズにかかわらず単一ファイルのままにし、代わりに内容を簡潔にしてください。簡潔にするとは、重要な指示をすべて保ちながら、重複、埋め草、過剰な説明を削ることです。行数に合わせるために内容を失うのは、解決策ではなく失敗です。パターンの CLI 埋め込み型の単一ファイルパターンを参照してください。

サイズの目安（経験に基づく独自の基準であり、仕様で定められた上限ではありません）：wc -c SKILL.md で測定してください。文字数はトークン数と密接に関係します（約 4 文字で 1 トークン）。行数は指標になりません。同じ内容でも、書式によって行数が 2 倍変わることがあります。

Tier	文字数	超えた場合
推奨	25k	慎重に簡潔化し、条件付き読み込みのテストに合格する場合にのみ分割する
上限	50k	簡潔化するか、分割する必要があります

Anthropic の公式ガイダンスでは、500 行を超えたら分割するよう推奨しています。この助言は、めったに必要とされないサブトピックを含むレジストリインストール型の skills を前提とし、書式によって値が変わる単位でサイズを測っています。この skill では、その両方について意図的に異なる方針を採っています。

skill を分割すると、情報は次の 3 つのレベルで読み込まれます。

レベル	読み込み時	トークンコスト	内容
1：メタデータ	常時（起動時）	~chars / 4 + 25 - 長さを参照	frontmatter の name + description
2：指示	skill が起動したとき	5k トークン未満（推奨）	SKILL.md の本文
3：リソース	必要に応じて	実質的に無制限	同梱ファイル、スクリプト

タスクで必要な場合にのみ読み込まれるよう、SKILL.md から詳細を記載した参照ファイルを参照してください。

## Advanced features
- **Form filling**: See [FORMS.md](FORMS.md)
- **API reference**: See [reference.md](reference.md)

組み合わせやすさ

Skills は、ほかの skills と併用できます。自分の skill だけが読み込まれるとは想定しないでください。

移植性

Skills は、依存関係が利用可能であれば、変更を加えずに Claude.ai、Claude Code、API、Agent SDK で使用できます。

説明文の書き方（重要）

説明文は最も重要な単一のフィールドです。skill がいつ起動するかを決定します。Claude は、利用可能な 100 以上の skills の中から関連性を判断するために、説明文を使用します。

ルール

• 三人称で書きます（「ファイルを処理します」のように記述します。一人称や二人称では、適切なスキルの検出を妨げます）。
• 実行する内容と、使用するタイミングの両方を含めます。
• XML の山括弧は使いません。目標の長さについては長さを参照してください。
• 少し「強め」に書きます。Claude は過剰に実行するよりも、実行を控えすぎる傾向があります。
• ユーザーが自然に使いそうな具体的なトリガーフレーズを含め、該当する場合はファイルの種類も記載します。
• キーワードの羅列ではなく、自然な文章で書きます。一致判定は意味に基づくため、「X、Y、Z でトリガー」と長く列挙するより、明確な一文のほうが効果的です。
• スキルが MCP サーバーに依存する場合は、その名前を記載します（例：「...MCP 経由で実行します。Linear MCP サーバーへの接続が必要です。」）。

長さ

目標は 250 文字です。仕様で定める 1024 文字は上限であり、使い切るための文字数ではありません。 説明は、そのスキルが一度も実行されるかどうかにかかわらず、すべてのセッションのすべてのターンでトークンを消費する唯一の部分です。約 250 文字を超えると、トリガーが明確になるどころか、焦点がぼやけます。説明は要約ではなく、呼び出しの判断材料です。

長すぎる説明を短くする場合、通常は次の順で効果があります。

• 文章内で繰り返している技術スタックの列挙を削ります。 技術スタックを一度挙げれば十分です。「フロントエンド全体とバックエンド全体に対応」と言い直すのは、まったく不要な水増しです。
• アピール文句を削ります。 「網羅的な API 表を収録」は本文の説明であり、いつ実行するかを示すものではありません。
• トリガーの列挙をまとめます。 引用フレーズを 3 つ並べ、「〜の場合」を 4 つ加えるより、明確な節を 1 つにまとめるほうが効果的です。一致判定は意味に基づくため、似たトリガーを重ねても効果はありません。
• 除外条件と区別点は残します。 「セッション状態には使わない」「LanceDB 製品のことではない」といった記述は 30～40 文字程度で、誤ったスキルの選択を防ぐ唯一の手がかりになる場合があります。

良い例と悪い例

# GOOD - specific, actionable, includes triggers
description: Extract text and tables from PDF files, fill forms, merge
  documents. Use when working with PDF files or when the user mentions
  PDFs, forms, or document extraction.

# BAD - too vague
description: Helps with documents.

# BAD - missing triggers
description: Creates sophisticated multi-page documentation systems.

否定的なトリガー

スキルが過剰に実行される場合は、説明に境界条件を直接追加します。

description: Advanced data analysis for CSV files. Use for statistical
  modeling, regression, clustering. Do NOT use for simple data
  exploration (use data-viz skill instead).

手動で呼び出すスキル

disable-model-invocation: true を設定すると、スキルの自動実行が無効になります。説明は / メニューにのみ表示されるため、トリガーフレーズを記述しても機能しません。また、サブエージェントの事前読み込みやスケジュールされたタスクでもスキップされます。

デフォルトで設定しないでください。 ユーザーは /name と入力するよりも、「コミットする前にこれを整えて」のように文章でワークフローを依頼することがはるかに多く、このフラグを設定すると、そうした依頼に対してスキルの機能を損なう手作業の代替手順を強いることになります。本当に破壊的な単発操作に限って使用してください。設定する場合は、簡潔な 1 行の要約を書き、トリガーの調整は省略します。

Frontmatter リファレンス

必須フィールド

フィールド	ルール
name	ケバブケースで、最大 64 文字。小文字、数字、ハイフンのみ使用できます。「claude」または「anthropic」は使用できません
description	空欄不可、最大 1024 文字。XML タグは使用できません。実行する内容とタイミングを記載します

agentskills.io 標準と Claude API では、両方のフィールドが必須です。Claude Code ではより柔軟で、name はディレクトリ名に、description は最初の Markdown 段落にフォールバックします。それでも、移植性を確保するため、両方を記述してください。

仕様では、license、compatibility、metadata も任意のフィールドとして定義されています。compatibility は最大 500 文字で、対象製品、システムパッケージ、ネットワークアクセスなどの環境要件を記載します。

オプションフィールド（Claude Code）

フィールド	目的
argument-hint	[issue-number] などの自動補完ヒント
when_to_use	追加のトリガーコンテキスト。スキル一覧で description に追加されます
arguments	$name 置換に使う名前付き位置引数（スペース区切りの文字列またはリスト）
disable-model-invocation	true = ユーザーのみが呼び出せます。サブエージェントの事前読み込みとスケジュール済みタスクもブロックします。設定するメリットはあまりありません。手動で呼び出すスキルを参照してください
user-invocable	false = / メニューに表示されません（バックグラウンドの知識）
allowed-tools	現在のターンでツールを事前承認します（権限確認なし）。スペース区切りで指定します。例：Read Grep Glob。仕様の許可リストに含まれていますが、**（実験的）**とタグ付けされています
disallowed-tools	スキルが有効な間、Claude が利用できるツールから除外します。次のメッセージで解除されます
model	このスキルで使用するモデルを上書きします。inherit を指定できます。現在のターンのみ有効です
effort	努力度を上書きします：low、medium、high、xhigh、max
context	fork = 隔離されたサブエージェントで実行します
agent	context: fork の場合のサブエージェントの種類（例：Explore、Plan）
background	false にすると、フォークしたスキルはバックグラウンド実行から除外されます（v2.1.218+）
shell	bash（デフォルト）または powershell
hooks	このスキルのライフサイクルに限定されたフック
paths	スキルを有効化する条件を制限する Glob パターン

公開時の注意点： 上記のフィールドのうち allowed-tools を除くすべては Claude Code 固有です。Claude Code の実行時には動作しますが、公式の agentskills validate 仕様バリデーターでは拒否されます。このバリデーターが許可するのは name、description、license、compatibility、metadata、allowed-tools のみで、緩和フラグはありません。リポジトリや CI でこのバリデーターを実行する場合（ClawHub に公開するほとんどのリポジトリが該当します）、これらのフィールドを使うスキルは、検証または公開するコピーからフィールドを取り除かない限り、検証に失敗します。ClawHub レジストリ自体は、公開時に余分なトップレベルフィールドを許容する傾向がありますが、パイプラインのリファレンスバリデーターは許容しません。仕様に対する検証を参照してください。

命名規則

name（およびそのフォルダー）は、1～64 文字であること、小文字、数字、ハイフンのみを使うこと、ハイフンで始まったり終わったりしないこと、連続したハイフン（--）を含まないこと、親ディレクトリ名と一致することが必要です。Anthropic の各サービスでは、予約語の claude と anthropic も使用できません。

分かりやすさを重視して、動名詞形を推奨します。

• processing-pdfs、analyzing-spreadsheets、managing-databases
• 使用可能な例：pdf-processing、process-pdfs
• 避ける例：helper、utils、tools、documents

Claude Code 固有の仕様

公式ドキュメントでは、Claude Code のスキルの動作の大部分を説明しています。スキルのドキュメント（呼び出し制御、引数置換、検出と優先順位、ツールの権限、skillOverrides、コンテキスト予算）、現在バンドルされているスキルの一覧を確認できるコマンドのリファレンス（数リリースごとに頻繁に変わるため、一覧をハードコードしないでください）、および設定のリファレンスを参照してください。以下では、これらのドキュメントに記載されていない点や、実際の利用時に問題になりやすい点のみを説明します。

動的インジェクションの落とし穴

Claude Code は読み込み時に SKILL.md を前処理します。バッククォートで囲まれたコマンドの直前に感嘆符があると、そのコマンドは Claude が内容を見る前に実行されます（動的コンテキストのインジェクション）。前処理は Markdown を認識しません。

• コードフェンスやインラインコードスパン内であっても、リテラルな例は読み込み時に実行されます。また、失敗するプレースホルダーコマンドは、スキル全体の読み込み時にエラーを起こします
• インライン形式は行頭、または空白の後にある場合のみ実行されます。接頭辞を付ければ無効化できます（! の前に KEY= を置くと、リテラルとして扱われます）
• バッククォートの直後に ! を付けて開くフェンスは複数行形式であり、同様に実行されます
• references/ ファイルは Read ツールで読み込まれ、前処理されません。実行可能な例を安全に置けるのはここだけです。SKILL.md では、代わりに ! とバッククォートが隣接しないようにしてください（このセクションのように、! を独立したコードスパンで囲みます）
• 設定の "disableSkillShellExecution": true を指定すると、ユーザー、プロジェクト、プラグインのスキルでの実行が無効になります
• 公開するスキルでは、! ブロックよりも説明文を優先してください。 動的インジェクションはホスト固有です。他の環境ではブロックがリテラルテキストとして表示され、さらに、自身の権限プロンプトを抑制するためだけに allowed-tools を伴います。エージェントにコマンドの実行を指示すれば、ツール呼び出しは 1 回増えますが、どの環境でも機能します

文書化されていない動作

• display-name、default-enabled、fallback のフロントマターキーは存在しますが、公式のフロントマターテーブルには記載されていません
• フロントマターキーは大文字と小文字を区別せずに解析されます。kebab-case、snake_case、camelCase は同じフィールドとして解決されます。また、ブール値フィールドでは yes／no／on／off／1／0 も受け付けます（v2.1.218+）

注意が必要な動作

• context: fork のスキルは、v2.1.218 以降、デフォルトで バックグラウンド実行 されます（background: false で無効化できます）。バックグラウンド化されたフォークでは使用できるツールが少なくなり、編集内容はチェックポイントを経由しないため、/rewind で取り消せません。Explore／Plan のフォークでは CLAUDE.md と git status がスキップされます。v2.1.198 以降、Explore はセッションのモデルを継承します
• スキルは重ねて読み込めます。1 つのメッセージで /skill-a /skill-b args と指定すると、最大 6 個のスキルが読み込まれます（v2.1.199+）
• permissions.additionalDirectories では、指定したディレクトリからスキルは読み込まれません。読み込みには --add-dir フラグまたは /add-dir コマンドのみを使用できます
• allowed-tools の付与は現在のターンに限られます。スキルが「終了」したときではなく、ユーザーが次のメッセージを送信したときに解除されます
• /command の名前はスキルの ディレクトリ に由来します。フロントマターの name は表示ラベルにすぎません（プラグインスキルを除く）。ネストされたスキルは、たとえば /apps/web:deploy のように修飾名で呼び出せます
• 呼び出されたスキルの内容は、セッション中ずっとコンテキストに残り、再読み込みされません。一度限りの手順ではなく、継続して適用する指示を書いてください。自動圧縮後は、各スキルの直近の呼び出し内容が再度添付されます。共有の 25,000 トークンの予算を直近のものから順に使い、各スキルの先頭 5,000 トークンが対象です。全内容を復元するには、再度呼び出してください
• スキルの説明は起動時に読み込まれ、コンテキストウィンドウの 1% が一覧表示用の予算として使われます。使用頻度が低い説明から省略されます（名前は常に保持されます）。各項目の上限は 1,536 文字です。/doctor で診断し、skillListingBudgetFraction、skillListingMaxDescChars、または SLASH_COMMAND_TOOL_CHAR_BUDGET で調整してください

指示の構成

簡潔にする

エージェントは賢いものです。すでに把握している内容を改めて説明するのではなく、必要なコンテキストだけを追加してください。PDF とは何かを説明したり、選ぶ前に 4 つのライブラリを列挙したりするスキルは、エージェントが知っていることを伝えるためにトークンを消費します。

# BAD:  "PDF files are a common format containing text and images. To extract
#        text you need a library. There are many available..."
# GOOD: "Use pdfplumber for text extraction."

選択肢を増やしすぎない

選択肢を並べるのではなく、既定の方法を 1 つ示し、必要に応じて別の方法も選べるようにしてください。

# BAD:  "Use pypdf, or pdfplumber, or PyMuPDF, or pdf2image..."
# GOOD: "Use pdfplumber. For scanned PDFs needing OCR, use pdf2image with pytesseract."

自由度を設定する

• 自由度が高い（文章によるガイドライン）：複数の方法が有効で、状況によって異なります
• 自由度が中程度（疑似コード／テンプレート）：推奨されるパターンがありますが、ある程度の違いは許容されます
• 自由度が低い（厳密なスクリプト）：操作に失敗しやすく、一貫性が重要です

推奨される SKILL.md の構成

# Skill Name

## Quick start
[Minimal working example]

## Workflow Decision Tree
[Route to the right approach based on task type]

## Detailed Instructions
[Step-by-step for each workflow]

## Examples
[Concrete input/output pairs]

## Troubleshooting
[Common errors and fixes]

参考ファイル

参照ファイルは SKILL.md から1 階層以内に保ちます。「階層」とは、ファイルシステム上の階層ではなく、参照の連鎖（あるファイルが別のファイルを参照し、そのファイルがさらに別のファイルを参照すること）を指します。references/ サブディレクトリを使ってもかまいません。連鎖があると、Claude がファイルを部分的に読み込んで（head）、内容を見落とすことがあります。

# BAD: Too deep
SKILL.md -> advanced.md -> details.md -> actual info

# GOOD: One level
SKILL.md -> advanced.md (contains the info directly)
SKILL.md -> reference.md (contains the info directly)

100 行を超える参照ファイルには、先頭に目次を含めます。ファイルのサイズにも注意してください。数百行に及ぶ参照ファイルが 1 つあると、1 階層以内でも段階的な情報開示の妨げになります。Claude は、どのサブトピックについてもファイル全体を読み込むためです。大きな参照ファイルはサブトピックごとに分割し、タスクに必要なものだけを取得できるようにします。

パターン

よくあるワークフローの形

エージェントが推測できると思い込まず、本文でワークフローの形を明示します。

• 逐次処理：番号付きの手順を使い、各手順で実行する正確なコマンドを指定します
• 判断ツリー：最初にタスクの種類に応じて分岐します（「新しいコンテンツを作成しますか？→作成ワークフロー」）
• フィードバックループ：検証、修正、再検証を行い、合格するまでループを終了しないことを明記します
• チェックリスト：長いタスクでは、エージェントにチェックリストをコピーさせ、作業しながら項目にチェックを入れさせます

CLI に埋め込まれた単一ファイルのスキル

CLI ツールを説明するスキルの場合は、SKILL.md を CLI のソースコードと同じ場所に 1 つのファイルとして置き、バイナリにコンパイルし（go:embed、Rust の include_str!、または同等の方法）、内容を表示する <tool> skill サブコマンドを追加します。表示されるガイドはインストール済みのバージョンと常に一致し、1 つのコマンドでドキュメント全体を取得できます。playwright-cli、browser-use（browser-use skill show）、agent-browser（agent-browser skills get core）はいずれもこの形に収束しています。このようなスキルは references/ に分割せず、慎重に簡潔にまとめてください。

MCP とサブエージェントの活用

MCP はツールへのアクセスを提供し、スキルはそれらのツールを効果的に使うためのワークフロー知識を提供します。MCP ツールは修飾名で参照します（BigQuery:bigquery_schema、GitHub:create_issue）。スキルは移植可能な専門知識であり、サブエージェントは隔離された実行環境です。Claude Code では、フロントマターの context: fork によって、スキルがサブエージェント内で実行されます。

Claude を使ったスキルの開発（A/B ループ）

Claude の 2 つのインスタンスを使ってスキルを開発します。Claude A は設計と改善を支援します（フォーマットとエージェントに必要なものを把握しています）。Claude B は、スキルを読み込んで実際のタスクでテストする、新しいインスタンスです。通常の作業中に繰り返し提供しているコンテキストに注目し、それを A にスキルとしてまとめさせ、B でテストします。B の具体的な失敗（「テストアカウントをフィルタリングし忘れた」など）を A に伝え、これを繰り返します。仮定ではなく、観察された動作に基づいて反復します。出力スタイルを定めるスキルでは、入出力の例のペアが、どんな説明よりも望ましいスタイルを伝えます。

スクリプト

スキルに実行可能なコードを含める場合：

• 問題を解決し、丸投げしない：エラーを明示的に処理し、失敗するままにしないでください
• 定数の根拠を示す：マジックナンバーを使わず、各値を選んだ理由を記載してください
• 読み込みより実行を優先する：スクリプトはコンテキストに読み込まずに実行できます。トークンを消費するのは出力だけです
• 意図を明確にする：「analyze.py を実行する」（実行）と「analyze.py を参照する」（参考として読む）を区別します
• SKILL.md に依存関係を記載し、利用可能であることを確認します

テスト

評価を先に作成する

詳細な手順を書く前に評価を作成します。これにより、スキルが実際の問題を解決することを確認できます。スキルなしで Claude に代表的なタスクを実行させ、失敗を記録します。そのギャップを検証する約 3 つのシナリオを作成し、ベースラインを測定してから、合格に必要な最小限の指示を書きます。ベースラインと照らし合わせて反復します。

トリガーテスト

Should trigger:
- "Help me set up a new project in [Service]"
- "I need to create a project" (paraphrased)

Should NOT trigger:
- "What's the weather?" (unrelated)
- "Write Python code" (too generic)

機能テスト

通常の操作、エッジケース、対象外のリクエストをテストします。同じリクエストを 3～5 回実行し、一貫性を確認します。

トリガーのデバッグ

Claude に「この [skill-name] スキルはどのような場合に使いますか？」と尋ねます。Claude は説明をそのまま引用します。不足している点に基づいて調整します。

仕様に照らして検証する

公開前に、公式 Agent Skills バリデーターを実行してください。

uvx --from skills-ref agentskills validate path/to/skill

終了コード 0 は有効であることを示します。SKILL.md の形式を確認し、仕様で厳密に許可されているフロントマター（name、description、license、compatibility、metadata、allowed-tools）のみを認めます。ほとんどのレジストリ（例：ClawHub）や CI ゲートで実行されるため、ローカルで検証すれば問題を早期に発見できます。Claude Code 専用のフロントマター（Frontmatter Reference の公開に関する注意事項を参照）を使用している場合は、検証するコピーからそのフィールドを削除してください。

公開前チェックリスト

対象範囲に合わせて調整してください。プロジェクト単位または単一ユーザー向けのスキルでは、トリガー精度と配布時の衛生に関する項目は省略できます。

• フォルダー名と name は kebab-case で一致しており、ファイル名は正確に SKILL.md
• 説明：三人称、WHAT + WHEN、具体的なトリガー、1024 文字未満、山括弧なし
• 条件付きで読み込まれるコンテンツに references/ が必要な場合を除き単一ファイルにする。サイズ上限内（wc -c）
• 重要な指示を冒頭に記載する。擬似コードではなく動作する例を示し、用語を統一する
• 分割する場合：SKILL.md から references をリンクし、1 階層までとする。100 行を超えるファイルには目次を付ける
• スクリプト：明示的なエラー処理、説明のない定数を使わない、依存関係を記載し、実行するか読み取るかを明確にする
• トリガーをテストする：直接的な依頼とその言い換えで起動し、無関係な依頼や類似していても異なる依頼では起動しない
• 機能を確認する：通常ケースと境界ケースに合格し、3～5 回の実行で一貫した出力になり、複数のモデルでテスト済み
• 時間の経過で古くなる情報、Windows 形式のパス、非推奨の API がない
• 仕様バリデーターの終了コードが 0（上記のコマンド）
• アップロード後：実際の会話でトリガー不足・過剰を監視し、説明を改善し、変更のたびにバージョンを上げる

トラブルシューティング

症状	原因	対処方法
スキルがまったく読み込まれない	説明が曖昧すぎる	具体的なトリガーと重要なキーワードを追加する
スキルが誤ったタスクで読み込まれる	説明の範囲が広すぎる	否定的なトリガーを追加し、より具体的にする
指示に従わない	冗長すぎる、または埋もれている	重要な指示を冒頭に置き、見出しを使う
応答が遅い／品質が低下する	SKILL.md が大きすぎる	まず簡潔にする。コンテンツが条件付きで読み込まれる場合に限り references/ に分割する（「単一ファイルと references/」を参照）
「Could not find SKILL.md」	ファイル名が誤っている	正確に SKILL.md にする（大文字と小文字を区別）
「Invalid skill name」	空白または大文字が含まれている	kebab-case を使う：my-skill-name
読み込み時にスキル全体が黙ってスキップされる	説明が 1024 文字を超えている	短くする。ローダーは説明だけでなくファイル全体を拒否します
フロントマターの解析に失敗する	引用符で囲まれていない description はプレーンな YAML スカラーです。そのため、コロンとスペース（Triggers: 、Use when: ）や、その中の半角の "引用符" は解析エラーの原因になります	コロンを - に置き換えるか、値全体を引用符で囲む
ドキュメントの例でシェルコマンドが実行される	バッククォートで囲まれたコマンドの直前に ! があると、コードフェンス内でも読み込み時に実行される	例を references/ に移動するか、! とバッククォートが隣接しないようにする（Dynamic-Injection Footgun を参照）

配布

配布先	デプロイ方法
Claude.ai	Settings > Features > Upload zip
Claude Code（個人）	~/.claude/skills/<name>/SKILL.md
Claude Code（プロジェクト）	.claude/skills/<name>/SKILL.md
Claude Code（プラグイン）	<plugin>/skills/<name>/SKILL.md
API	Skill Management API でアップロードし、Messages API で使用する
Enterprise	管理対象の設定（組織全体）

スキルは配布先間で同期されないため、それぞれに個別にデプロイしてください。

API でのスキルの使用

カスタムスキルは Skill Management API を通じてアップロードします。anthropic タイプのスキルは Anthropic によって事前に構築されています。どちらも同じ方法で使用します。Messages API の container パラメーターに、それぞれ {type, skill_id, version} として渡します。type は anthropic または custom です。1 リクエストにつき最大 8 個のスキルを指定でき、アップロードの上限は 30 MB（全ファイルの合計）です。また、すべてのファイルは共通のルートディレクトリを共有する必要があります。コード実行ツールと、ベータヘッダー code-execution-2025-08-25 および skills-2025-10-02（ファイルのアップロード／ダウンロードには files-api-2025-04-14 も）を使用する必要があります。

ネットワークアクセスは環境によって異なります。 API のコード実行環境では、ネットワークアクセスも実行時のパッケージインストールもできません。依存関係をバンドルするか、プリインストール済みのパッケージを使用してください。一方、claude.ai では、スキルから npm や PyPI のパッケージをインストールしたり、GitHub から取得したりできます。

また、pause_turn の停止理由は、スキルの処理に時間がかかっていることを示します。container.id を使うと、ターンをまたいでコンテナを再利用できます。生成されたファイルは Files API を通じて返されます。スキルのリストを変更すると、プロンプトキャッシュが無効になります。スキルは ZDR の対象にはなりません。

セキュリティ

• 信頼できるソースのスキルのみを使用してください
• フロントマターに XML の山括弧を含めないでください（インジェクションの危険があります）
• サードパーティのスキルを使用する前に、バンドルされたすべてのスクリプトとリソースを監査してください
• 外部 URL から取得するスキルには注意してください
• 動的インジェクション構文の説明自体が危険です。ローダーはコードフェンス内であっても、読み込み時に例を実行します。作成を始める前に、Dynamic-Injection Footgun を参照してください

追加の参考資料

• ClawHub での公開 - ソース分析で明らかになったモデレーションの注意点：理由コードと修正方法、LLM レビューを通過するための方法、ClawHub のドキュメントに記載されていない制約

公式リソース

• Agent Skills Spec
• Claude Code Skills Docs
• API Skills Guide
• Best Practices
• Anthropic Skills Repo
• Engineering Blog: Agent Skills
• Complete Guide PDF