create-agent-skills

スキルとコマンドの作成

このスキルでは、code.claude.com/docs/en/skills の公式仕様に沿って、効果的な Claude Code スキルを作成する方法を説明します。

コマンドとスキルは同じものになりました

カスタムスラッシュコマンドはスキルに統合されました。.claude/commands/review.md のファイルと .claude/skills/review/SKILL.md のスキルは、どちらも /review を作成し、同じように動作します。既存の .claude/commands/ ファイルも引き続き機能します。スキルには、サポートファイル用のディレクトリ、呼び出しを制御するフロントマター、コンテキストの自動読み込みといったオプション機能があります。

スキルとコマンドの名前が同じ場合、スキルが優先されます。

どちらを作成するか

コマンドファイル（commands/name.md）を使う場合：

• シンプルで、単一ファイルで完結するワークフロー
• サポートファイルが不要
• タスク指向の操作（デプロイ、コミット、トリアージ）

スキルディレクトリ（skills/name/SKILL.md）を使う場合：

• 参照ファイル、スクリプト、テンプレートなどのサポートファイルが必要
• Claude が自動で読み込むべき背景知識がある
• 複雑で、段階的な開示が有効

どちらも、同じ YAML フロントマターと Markdown 本文の形式を使います。

標準的な Markdown 形式

YAML フロントマターと Markdown 本文を、標準的な Markdown 見出しとともに使用します。簡潔で、直接的な内容にしてください。

---
name: my-skill-name
description: What it does and when to use it
---

# My Skill Name

## Quick Start
Immediate actionable guidance...

## Instructions
Step-by-step procedures...

## Examples
Concrete usage examples...

フロントマターのリファレンス

すべてのフィールドは任意です。推奨されるのは description のみです。

フィールド	必須	説明
name	いいえ	表示名です。小文字、数字、ハイフンを使用します（最大64文字）。デフォルトはディレクトリ名です。
description	推奨	機能と、使用するタイミングを記述します。Claude はこれを自動検出に使用します。最大1024文字です。
argument-hint	いいえ	オートコンプリート時に表示するヒントです。例：[issue-number]
disable-model-invocation	いいえ	Claude による自動読み込みを防ぐには、true に設定します。/deploy や /commit など、手動で実行するワークフローに使用します。デフォルト：false。
user-invocable	いいえ	/ メニューに表示しない場合は、false に設定します。背景知識に使用します。デフォルト：true。
allowed-tools	いいえ	Claude が許可プロンプトなしで使用できるツールです。例：Read, Bash(git *)
model	いいえ	使用するモデルです。選択肢：haiku、sonnet、opus。
context	いいえ	分離されたサブエージェントのコンテキストで実行するには、fork に設定します。
agent	いいえ	context: fork の場合に使用するサブエージェントの種類です。選択肢：Explore、Plan、general-purpose、またはカスタムエージェント名。

呼び出しの制御

フロントマター	ユーザーが呼び出せる	Claude が呼び出せる	読み込みのタイミング
（デフォルト）	はい	はい	説明は常にコンテキストに含まれ、呼び出されると全文が読み込まれる
disable-model-invocation: true	はい	いいえ	説明はコンテキストに含まれず、ユーザーが呼び出した場合にのみ読み込まれる
user-invocable: false	いいえ	はい	説明は常にコンテキストに含まれ、関連する場合に読み込まれる

副作用を伴うワークフローには、disable-model-invocation: true を使用します。例：/deploy、/commit、/triage-prs、/send-slack-message。コードの準備が整っているように見えるという理由で、Claude がデプロイを決めてしまうのは避けたいものです。

コーディング規約、ドメインのコンテキスト、レガシーシステムのドキュメントなど、ユーザーが実行する操作として意味を持たない背景知識には、user-invocable: false を使用します。

動的機能

引数

ユーザー入力には $ARGUMENTS プレースホルダーを使用します。本文に含まれていない場合、引数は自動的に末尾に追加されます。

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---

Fix GitHub issue $ARGUMENTS following our coding standards.

個別の引数には、$ARGUMENTS[0] または省略形の $0、$1、$2 でアクセスできます。

動的コンテキスト注入

スキルは動的コンテキスト注入に対応しています。バッククォートで囲んだシェルコマンドの前に感嘆符を付けると、プリプロセッサが読み込み時に実行し、ディレクティブを標準出力で置き換えます。実行するコマンドの開始バッククォートの直前に感嘆符を記述します（たとえば、現在の Git ブランチを注入するには、感嘆符の後に git branch --show-current をバッククォートで囲んで記述します）。

重要： プリプロセッサは SKILL.md 全体をプレーンテキストとして走査し、Markdown の解析は行いません。フェンス付きコードブロック内やインラインコードスパン内のディレクティブも実行されます。スキル内でこの構文を文字どおりの例として記載すると、プリプロセッサが実行を試み、読み込みに失敗する原因になります。この機能を安全に説明するには、ここで行っているように文章で説明するか、参照ファイルに例を記載してください。参照ファイルは Claude によって必要に応じて読み込まれ、プリプロセッサによる処理は行われません。

スキルでの動的コンテキスト注入の具体例については、official-spec.md の「Dynamic Context Injection」節を参照してください。

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

context: fork を追加すると、分離された環境で実行できます。スキルの内容がサブエージェントのプロンプトになります。会話履歴は引き継がれません。

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

Research $ARGUMENTS thoroughly:
1. Find relevant files
2. Analyze the code
3. Summarize findings

段階的な情報開示

SKILL.md は 500 行未満にしてください。詳細な内容は参照ファイルに分割します。

my-skill/
├── SKILL.md           # Entry point (required, overview + navigation)
├── reference.md       # Detailed docs (loaded when needed)
├── examples.md        # Usage examples (loaded when needed)
└── scripts/
    └── helper.py      # Utility script (executed, not loaded)

SKILL.md から次のようにリンクします：For API details, see [reference.md](reference.md).

参照ファイルは SKILL.md から1 階層に保ってください。入れ子の参照チェーンは避けてください。

効果的な説明

説明はスキルの検索に役立ちます。何をするかといつ使うかの両方を含めてください。

良い例：

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.

悪い例：

description: Helps with documents

何をしますか？

1. 新しいスキルを作成 - ゼロから作成する
2. 新しいコマンドを作成 - スラッシュコマンドを作成する
3. 既存のスキルを監査 - ベストプラクティスに照らして確認する
4. コンポーネントを追加 - ワークフロー／参照／例を追加する
5. ガイダンスを受ける - スキル設計について理解する

新しいスキルまたはコマンドの作成

ステップ 1：種類を選ぶ

手動のワークフロー（デプロイ、コミット、トリアージ）ですか、それとも背景知識（規約、パターン）ですか？

• 手動のワークフロー → disable-model-invocation: true を指定したコマンド
• 背景知識 → disable-model-invocation を指定しないスキル
• 補助ファイルを伴う複雑なもの → スキルディレクトリ

ステップ 2：ファイルを作成する

コマンド：

---
name: my-command
description: What this command does
argument-hint: [expected arguments]
disable-model-invocation: true
allowed-tools: Bash(gh *), Read
---

# Command Title

## Workflow

### Step 1: Gather Context
...

### Step 2: Execute
...

## Success Criteria
- [ ] Expected outcome 1
- [ ] Expected outcome 2

スキル：

---
name: my-skill
description: What it does. Use when [trigger conditions].
---

# Skill Title

## Quick Start
[Immediate actionable example]

## Instructions
[Core guidance]

## Examples
[Concrete input/output pairs]

ステップ 3：参照ファイルを追加する（必要な場合）

SKILL.md から詳細な内容にリンクします：

For API reference, see [reference.md](reference.md).
For form filling guide, see [forms.md](forms.md).

ステップ 4：実際の使用でテストする

1. テストシナリオではなく、実際のタスクでテストする
2. /skill-name で直接呼び出して確認する
3. 説明に一致する内容を尋ね、自動的に起動するか確認する
4. 実際の動作をもとに調整する

監査チェックリスト

• 有効な YAML フロントマター（name + description）
• 説明にトリガーキーワードが含まれ、具体的である
• 標準の Markdown 見出しを使用している（XML タグではない）
• SKILL.md が 500 行未満である
• 副作用がある場合は disable-model-invocation: true を指定している
• 特定のツールが必要な場合は allowed-tools を設定している
• 参照が 1 階層に収まり、適切にリンクされている
• 例が抽象的ではなく具体的である
• 実際の使用でテストされている

避けるべきアンチパターン

• 本文中の XML タグ - 標準の Markdown 見出しを使用する
• 曖昧な説明 - トリガーキーワードを含め、具体的にする
• 深い入れ子 - 参照は SKILL.md から 1 階層に保つ
• 呼び出し制御の欠如 - 副作用のあるワークフローには disable-model-invocation: true が必要
• 選択肢が多すぎる - 既定の方法を示し、別の方法も選べるようにする
• Claude への丸投げ - スクリプトでエラーを明示的に処理する

参照ファイル

詳細なガイダンスについては、以下を参照してください：

• official-spec.md - スキルの公式仕様
• best-practices.md - スキル作成のベストプラクティス

ソース

• Claude をスキルで拡張する - 公式ドキュメント
• GitHub - anthropics/skills