Claude Codeのカスタムスキルの作り方
Kitbay編集部 ·
Claude Codeのカスタムスキルを作るには、~/.claude/skills/(プロジェクトでは.claude/skills/)にスキル名のフォルダを作り、name、description、指示を書いたSKILL.mdファイルを追加します。そのうえで、そのタスクを頼むか/skill-nameと入力してテストします。その後は、Anthropicのskill-creatorスキルを使って、スキルの評価と改善ができます。
この形式が初めての場合は、先にClaude Skillsとはを読んでください。このガイドでは実際の手順を説明します。
ステップ1:仕事を1つに絞る
スキルがうまく働くのは、終わりがはっきりした、繰り返し行うタスクを1つだけ扱うときです。「プロジェクトを手伝う」ではなく、「マージされたプルリクエストからリリースノートを書く」のようなものです。Claude Codeのドキュメントでは、チャットに何度も貼り付けている指示をスキルにすることや、CLAUDE.mdの中の手順が長くなってきたらスキルに移すことを勧めています。
名前は、release-notesのように英小文字、数字、ハイフンを使った短いものにします。この名前がフォルダ名とスラッシュコマンドになります。
ステップ2:フォルダを作る
個人用のスキルは、自分のマシンのすべてのプロジェクトで使えます。
mkdir -p ~/.claude/skills/release-notes
プロジェクトのスキルは、リポジトリをクローンした全員で共有されます。
mkdir -p .claude/skills/release-notes
プラグインのskills/フォルダにスキルを入れることもできます。複数のスキルを多くのリポジトリで共有するときは、この方法が一般的です。
ステップ3:SKILL.mdを書く
---
name: release-notes
description: Drafts release notes from merged pull requests since the last tag. Use when the user asks for release notes, a changelog entry, or a summary of what shipped.
---
## Steps
1. Find the latest git tag and list pull requests merged after it.
2. Group changes under Added, Changed and Fixed.
3. Write one plain sentence per change and link the pull request.
## Rules
- Leave out internal refactors unless they change behaviour.
- Ask before publishing anything.
押さえておきたいポイントは3つあります。
- スキルがいつ読み込まれるかは説明文で決まる。 Claudeはリクエストを説明文と照らし合わせます。スキルが何をするのか、いつ使うのかを書き、ユーザーが自然に入力しそうな言葉を含めてください。Claude Codeはスキル一覧で長い説明文を切り詰めます(合計テキストの上限は1,536文字)。主な用途を最初に書きましょう。
- セッション中ずっと通用する指示を書く。 Claude Codeはスキルの内容を一度だけ会話に追加し、以降のターンではファイルを読み直しません。
- 短く保つ。
SKILL.mdは500行未満を目安にし、詳しい内容は別のファイルに移します。
ステップ4:必要に応じてスクリプトや参照ファイルを追加する
長い参考資料は別のファイルにまとめ、SKILL.mdからリンクします。こうすると、Claudeがいつそのファイルを開けばよいかがわかります。
release-notes/
├── SKILL.md
├── references/style-guide.md
└── scripts/list_merged_prs.py
スクリプトは、毎回同じ結果を出す必要がある手順に向いています。Claudeはスクリプトを実行し、その出力だけを見ます。Claude Codeでは、同梱のファイルを${CLAUDE_SKILL_DIR}変数で参照してください。スキルが個人用、プロジェクト用、プラグインのどれでインストールされていても、パスが正しく通ります。Agent Skillsの仕様では、スクリプトに依存関係を明記し、わかりやすいエラーメッセージを出力することを勧めています。
ステップ5:誰が起動できるかを決める
デフォルトでは、自分とClaudeの両方がスキルを起動できます。これを変えるClaude Codeのフィールドが2つあります。
| フィールド | 効果 | 主な用途 |
|---|---|---|
disable-model-invocation: true |
自分だけが/nameで起動できる |
デプロイ、メッセージの送信など、副作用のある作業 |
user-invocable: false |
/メニューに表示されず、Claudeだけが読み込む |
スタイルガイドのような背景知識 |
allowed-toolsフィールドを使うと、スキルを実行するターンで、指定したツールを事前に承認できます。許可はタスクに必要な最小限にしてください。
ステップ6:テストする
- Claude Codeを起動して「What skills are available?」と聞きます。自分のスキルが一覧に表示されるはずです。
- スキル名を出さずに、説明文に合うリクエストをして、Claudeがスキルを読み込むかを確認します。
/release-notesで直接実行します。
Claude Codeはスキルのフォルダを監視しているため、編集はセッション中に反映されます。ただし、セッション開始時に存在しなかったスキルフォルダを使うには/reload-skillsが必要です。YAMLの書式が壊れていると、スラッシュコマンドは動きますが、Claudeが説明文と照らし合わせられなくなります。claude --debugを実行するとパースエラーが表示され、claude plugin validate ~/.claude/skillsでフロントマターをチェックできます(Claude Code v2.1.233以降)。ほかのエージェントでも使うスキルなら、仕様のskills-ref validate ./my-skillコマンドで標準フィールドをチェックできます。
skill-creatorスキルを使う
Anthropicは、anthropics/skillsリポジトリでskill-creatorスキルを公開しています。このスキル自身の説明によると、新しいスキルの作成、既存のスキルの改善、スキルの性能の測定を行います。進め方は次のとおりです。
- スキルが何をするのか、いつ起動すべきか、どんな出力が望ましいかを尋ねます。
SKILL.mdと同梱のファイルの下書きを作ります。- 現実的なテスト用プロンプトを2〜3個作り、
evals/evals.jsonに保存します。 - 各プロンプトをスキルありとスキルなし(または前のバージョン)で実行し、結果を採点して、レビュー用に表示します。
- 満足するまで修正と実行を繰り返します。
- スキルを起動すべきプロンプトと起動すべきでないプロンプトを作り、起動の的中率が上がるように説明文を調整します。
Claude Codeでは、/plugin install skill-creator@claude-plugins-officialでプラグインとしてインストールし、たとえば「evaluate my release-notes skill with skill-creator」と頼みます。Claude Codeのドキュメントによると、各テストはクリーンなコンテキストを持つ別々のサブエージェントで実行され、結果にはスキルありとなしそれぞれの合格率、時間、トークン数が含まれます。
Codexには独自のskill-creatorが組み込まれていて、$skill-creatorで起動します。このスキルはKitbayのスキルの掲載でも探せます。
スキルを共有する
- チームで共有:
.claude/skills/をリポジトリにコミットします。 - 複数のリポジトリで共有: スキルをClaude Codeのプラグインにまとめます。
- claude.aiで使う: フォルダをzipファイルにしてアップロードします。claude.aiでは標準のフロントマターフィールドしか受け付けません。
- ほかのエージェントで使う: 標準フィールドだけを使い、各エージェントのドキュメントでスキルフォルダの場所を確認します。
カスタムスキルはClaude Code、claude.ai、APIの間で同期されないため、使う場所ごとに追加してください。
安全上の注意
スクリプトを含むスキルは、自分のマシンでコードを実行します。また、Claude Codeのドキュメントによると、プロジェクトのスキルのallowed-tools設定は、信頼済みとしてマークしていないフォルダでも有効になります。リポジトリに含まれているスキルは、ほかのコードと同じように慎重に確認してください。インストール前の確認事項は、サーバーとスキルのセキュリティに関するチェックポイントにまとめています。
次のステップ
スキルでほかのアプリのリアルタイムのデータが必要なら、MCPサーバーと組み合わせましょう。両者がどう補い合うかは、MCPとスキルの違いのガイドで説明しています。アイデアを探すなら、コードレビューやドキュメント作成のスキルを見てみてください。
よくある質問
- Claude Codeのカスタムスキルはどこに保存しますか?
- すべてのプロジェクトで使うなら~/.claude/skills/<skill-name>/SKILL.mdに、そのプロジェクトのチームと共有するならリポジトリ内の.claude/skills/<skill-name>/SKILL.mdに置きます。
- Claudeのskill-creatorとは何ですか?
- skill-creatorはAnthropicが公開しているスキルで、新しいスキルの下書き、テスト用プロンプトの作成、スキルありとなしの結果の比較、説明文の調整を手伝ってくれます。Claude Codeではプラグインとして使えます。
- Claudeが自分のスキルを使ってくれないのはなぜですか?
- 多くの場合、説明文がリクエストの言い回しと合っていません。ユーザーが実際に使う言葉を追加し、使えるスキルを尋ねたときに一覧に表示されるかを確認するか、/skill-nameで直接起動してください。
- 同じスキルをclaude.aiやCodexでも使えますか?
- 標準のフロントマターフィールドだけを使っていれば、使えることが多いです。claude.aiはスキルをzipでアップロードする形式で、不明なキーは受け付けません。Codexは.agents/skillsフォルダからスキルを読み込みます。
出典
- Extend Claude with skills (Claude Code docs)2026年11月14日 確認
- Agent Skills specification2026年11月14日 確認
- Agent Skills (Claude Platform docs)2026年11月14日 確認
- skill-creator SKILL.md (anthropics/skills)2026年11月14日 確認
- anthropics/skills repository2026年11月14日 確認
- Build skills (Codex docs)2026年11月14日 確認