creating-skills

スキルの作成

Anthropic の公式ベストプラクティスに沿って Claude Code スキルを作成するためのガイドです。

クイックスタート

# 1. Create skill directory
mkdir -p ~/.claude/skills/<skill-name>

# 2. Create SKILL.md with frontmatter
cat > ~/.claude/skills/<skill-name>/SKILL.md << 'EOF'
---
name: <skill-name>
description: <What it does>. Use when <trigger phrases>. <Key capabilities>.
---

# <Skill title>

<Instructions for the skill workflow>
EOF

# 3. Add optional resources as needed
mkdir -p ~/.claude/skills/<skill-name>/{scripts,references,assets}

SKILL.md の構成

フロントマター（--- マーカーの間に記述する YAML）

フィールド	必須	説明
name	いいえ	表示名です。デフォルトはディレクトリ名です。小文字、ハイフンを使用し、最大 64 文字です。
description	推奨	内容、使用するタイミング、機能を記述します。最大 1024 文字です。Claude がスキルを有効にするタイミングを決定します。
allowed-tools	いいえ	スキルが有効なとき、許可を求めずに Claude が使用できるツールです。
argument-hint	いいえ	引数の自動補完ヒントです。例：[issue-number]
disable-model-invocation	いいえ	自動呼び出しを防ぐには true を指定します（手動での /name のみ）。
user-invocable	いいえ	/ メニューに表示しない場合は false を指定します（バックグラウンド知識のみ）。
model	いいえ	スキルが有効なときに使用するモデルの上書き設定です。
context	いいえ	分離されたサブエージェントのコンテキストで実行するには fork を指定します。
agent	いいえ	context: fork のときのサブエージェントの種類です。組み込み：Explore、Plan、general-purpose。
hooks	いいえ	このスキルに限定されたライフサイクルフックです。

呼び出し制御マトリックス

設定	ユーザーが呼び出せる	Claude が呼び出せる
（デフォルト）	はい	はい
disable-model-invocation: true	はい	いいえ
user-invocable: false	いいえ	はい

説明の構成式

<What it does>. Use when <trigger phrases>. <Key capabilities>.

行動を表す動詞（「作成する」「処理する」）、ユーザーの意図（「したい」「必要がある」）、ユーザーが使う分野のキーワードを含めます。

ディレクトリ構成

skill-name/
├── SKILL.md              # Required: instructions (keep under 500 lines)
├── scripts/              # Optional: executable code (deterministic, token-efficient)
├── references/           # Optional: docs loaded into context on demand
└── assets/               # Optional: files used in output, NOT loaded into context
                          #   (templates, images, fonts, boilerplate)

段階的な情報開示（3 段階の読み込み）

1. メタデータ（名前＋説明）- 常にコンテキストに含まれます（スキルあたり約 100 トークン）
2. SKILL.md 本文 - スキルが呼び出されたときに読み込まれます（5,000 語未満に収めます）
3. 同梱リソース - Claude が必要に応じて読み込みます

Claude がファイルの存在を把握できるよう、SKILL.md から補助ファイルを参照します。参照は 1 階層までにします。100 行を超えるファイルには目次を含めます。

スクリプト、リファレンス、アセットの使い分け

種類	目的	コンテキストに読み込まれるか
scripts/	決定論的な操作、複雑な処理	いいえ（bash 経由で実行）
references/	Claude が作業中に読むドキュメント	はい、必要に応じて
assets/	出力に使うテンプレート、画像、フォント	いいえ（出力にコピー／使用）

スクリプトを作成するのは、複雑な複数ステップの処理、コード生成の繰り返し、決定論的な信頼性など、価値がある場合のみにします。単一コマンドのラッパーには使用しません。

動的機能

コンテキストへの挿入

読み込み前に、シェルコマンドの出力をスキルの内容に挿入します。

## Recent commits
!`git log --oneline -5 2>/dev/null`

スキルの読み込み時に、このディレクティブが出力に置き換えられます。

文字列の置換

/skill-name arg1 arg2 で呼び出すスキルに引数を渡します。

変数	値
$ARGUMENTS	引数文字列全体
$ARGUMENTS[0]、$ARGUMENTS[1]	個々の引数
$1、$2	$ARGUMENTS[N] の省略形

サブエージェントでの実行

context: fork を使って、分離されたコンテキストでスキルを実行します。

---
name: deep-research
description: Research a topic thoroughly.
context: fork
agent: Explore
---

自由度

タスクの壊れやすさに応じて、具体性を調整します。

レベル	使用する場面	例
高（テキスト指示）	有効なアプローチが複数あり、コンテキストに依存する	「コードを分析して改善点を提案する」
中（パラメーター付きの疑似コード／スクリプト）	推奨されるパターンがあり、ある程度の変更は許容される	設定可能なパラメーターを備えたスクリプト
低（特定のスクリプト、少数のパラメーター）	壊れやすい操作、一貫性が重要	API 呼び出しの正確な順序

命名規則

• 小文字を使用し、単語の間にはハイフンを入れ、最大 64 文字にします
• 形式：動名詞（processing-pdfs）、名詞句（github-pr-creation）、接頭辞付きグループ（github-pr-*）

重要なルール

• 必ず、WHAT＋実行されるタイミング＋機能を含む説明を書いてください
• 必ず、SKILL.md を 500 行未満に保ち、上限に近づいたらリファレンスに分割してください
• 必ず、Claude が参照ファイルを見つけられるよう、SKILL.md からバンドルされたファイルを参照してください
• 決して、SKILL.md とリファレンスファイルの間で情報を重複させないでください
• 決して、単一のコマンドのためにラッパースクリプトを作成しないでください
• 決して、余分なファイル（README.md、CHANGELOG.md、INSTALLATION_GUIDE.md、QUICK_REFERENCE.md）を含めないでください
• 決して、Claude がすでに知っていること（標準ライブラリ、一般的なツール、基本的なパターン）を説明しないでください

リファレンス

• references/official_best_practices.md - 原則、アンチパターン、品質チェックリスト、テスト
• references/skill_examples.md - 新機能を使った具体的なスキルの例