Claude Code Skillsの作り方｜SKILL.mdで作業を自動化する

公開: 2026年8月2日

Claude Code の Skills は、いつも同じ指示をコピペしている作業手順を SKILL.md というファイルにまとめておき、必要なときだけClaudeに読み込ませる仕組みです。一度作っておけば、該当する依頼をしたときに自動で発動したり、/スキル名 で明示的に呼び出したりできます。この記事ではSKILL.mdの構造から置き場所、自作の実例、他機能との使い分けまでをまとめて解説します。Claude Code全体の設定は「Claude Code設定完全ガイド」もあわせて参考にしてください。

前提・動作環境

Skillsはターミナル版のClaude Codeで利用できる機能です。あらかじめインストールとログインを済ませ、最新版にアップデートしておいてください。バージョンによって使える機能(サブエージェント実行や動的コンテキスト注入など)が異なるため、挙動が記事と違う場合は次のコマンドで確認しましょう。

claude --version

2.1.220 (Claude Code)

Skillsとは何か

Skillsは、特定の作業手順や知識を「必要になったときだけ」呼び出す仕組みです。CLAUDE.md にすべて書き込むと毎回コンテキストを消費しますが、Skillとして切り出せば、実際に使う場面まで本文は読み込まれません。「チャットに同じ指示を毎回貼り付けている」「CLAUDE.md の一部が事実の羅列ではなく手順になってきた」「リリースノート作成やPRレビューなど決まった手順の作業がある」といった場面がSkillを作るタイミングの目安です。

以前は「カスタムコマンド」(.claude/commands/ 配下のMarkdown)という別の仕組みがありましたが、現在はSkillsに統合されています。既存ファイルもそのまま動きますが、補助ファイルの同梱や呼び出し制御など、Skillsの方が機能は豊富です。

SKILL.mdの構造と置き場所

Skillは1つのディレクトリで表現され、中心となるのが SKILL.md です。ファイルはYAMLフロントマター(--- で囲まれた部分)と、その下に続くMarkdown本文の2部構成になっています。フロントマターの項目はすべて省略可能ですが、自動発動の判断材料になる description はほぼ必須です。本文はClaudeが実行時に読む指示そのもので、!`command` のように書くとClaudeに渡す前にシェルコマンドが実行され、出力が埋め込まれます(動的コンテキスト注入)。具体例は後述の実践編で示します。

置き場所によって適用範囲が変わります。

置き場所	パス	適用範囲
個人用	`~/.claude/skills/<name>/SKILL.md`	自分の全プロジェクト
プロジェクト用	`.claude/skills/<name>/SKILL.md`	このプロジェクトのみ
プラグイン	`<plugin>/skills/<name>/SKILL.md`	プラグインを有効化したプロジェクト

ディレクトリ名がそのままコマンド名(/<name>)になります。プロジェクト用としてリポジトリにコミットすれば、チーム全員が同じ手順を共有できます。

呼び出し方:自動発動と/コマンド

Skillsの呼び出し方は2通りです。1つ目は自動発動で、依頼内容が description にマッチすると、Claudeが自分で判断してSkillを読み込みます。2つ目は明示的な呼び出しで、/スキル名 と入力すると直接実行できます。

デプロイやコミットのように副作用のある作業は、ユーザーが呼び出したときだけ動かしたいものです。frontmatterに disable-model-invocation: true を追加すると、Claudeによる自動発動を禁止できます。逆に user-invocable: false を指定すると、/ メニューには出さず自動発動だけを許可できます。

実践編:リリースノート作成Skillを自作する

直近のタグからのコミット履歴を取得し、リリースノートの下書きを生成するSkillを作ってみます。.claude/skills/release-notes/SKILL.md を次の内容で保存します。

---
name: release-notes
description: 直近のタグからのコミット履歴を元にリリースノートの下書きを作成する。「リリースノートを作って」「変更点をまとめて」と頼まれたときに使う。
allowed-tools: Bash(git log *) Bash(git describe *)
---

## 直近のコミット履歴
!`git log $(git describe --tags --abbrev=0)..HEAD --oneline`

## 指示
上記のコミット一覧を元に、次の形式でリリースノートの下書きを作成してください。

1. 「新機能」「改善」「バグ修正」の3カテゴリに分類する
2. 各項目は日本語で1行に要約する
3. リファクタリングなど内部的な変更は末尾に「その他」としてまとめる
4. Markdown形式で出力する

allowed-tools を指定すると、このSkillが呼び出されたターンに限り、指定したGitコマンドを許可なしで実行できます。保存後は「リリースノートを作って」と話しかけるか、/release-notes と直接入力してテストしてください。

スラッシュコマンド・サブエージェントとの違いと使い分け

スラッシュコマンドは /help や /compact のように、Claude Code本体が持つ固定機能を呼び出す仕組みです。組み込みコマンドの一覧は「スラッシュコマンド一覧」で確認できます。Skillも /スキル名 として同じインターフェースに現れますが、中身はプロンプトベースの指示であり自由に追加できる点が異なります。

サブエージェントは .claude/agents/ に定義する、独立したコンテキストと権限を持つ実行主体です。Skillのfrontmatterに context: fork を指定すると、その内容をタスクとしてサブエージェントに渡し、バックグラウンドで実行させることもできます。会話履歴を汚したくない重い調査やレビューに向いています。

使い分けの目安は、単発の手順やナレッジは素のSkill、重い調査は context: fork 付きのSkill、Claude Code自体の機能はスラッシュコマンドです。Skillはプラグインとしてまとめて配布することもでき、詳しい手順は「プラグイン導入ガイド」で扱っています。

補助ファイルを同梱してSkillsを強化する

Skillのディレクトリには SKILL.md 以外のファイルも置けます。詳細なリファレンスやテンプレート、実行用のスクリプトを同梱すれば、SKILL.md 自体は簡潔なまま、必要なときだけ追加ファイルを読み込ませられます(例:template.md に出力フォーマット、scripts/validate.py に検証スクリプト)。補助ファイルは本文からリンクして参照させるのが基本です。パスを書くときは、置き場所によらず正しく解決される ${CLAUDE_SKILL_DIR} という変数を使うと安全です。

つまずきポイント/よくあるエラー

Skillが自動発動しない: description に、ユーザーが実際に使いそうな言葉が含まれているか確認しましょう。それでも発動しない場合は /スキル名 で直接呼び出せます。
意図しないタイミングで動いてしまう: description をより具体的にするか、disable-model-invocation: true で明示呼び出し専用にしましょう。
frontmatterのYAMLが壊れている: 構文エラーがあってもSkill自体は読み込まれますが、description が空扱いになり自動発動しなくなります。--debug 付きで起動するとパースエラーを確認できます。
編集が反映されない: 既存のSkillディレクトリはセッション中も監視されますが、新しくトップレベルのskillsディレクトリを作った場合は再起動が必要です。

よくある質問

SKILL.mdはどこに置けばいいですか?

個人的によく使う手順は ~/.claude/skills/<name>/SKILL.md に、チームで共有したい手順は .claude/skills/<name>/SKILL.md に置きます。後者はリポジトリにコミットすればメンバー全員が同じSkillを使えます。

Skillとスラッシュコマンドはどちらを使うべきですか?

Claude Code本体の固定機能(会話管理やモデル切り替えなど)はスラッシュコマンドが担当します。自分やチーム独自の作業手順を追加したい場合はSkillを作成してください。

既存のカスタムコマンドはSkillsに移行する必要がありますか?

必須ではありません。.claude/commands/ のファイルはそのまま動き続けます。補助ファイルの同梱や呼び出し制御を使いたい場合に、.claude/skills/<name>/SKILL.md の形式へ書き直すとよいでしょう。

まとめ

Skillsは、繰り返し使う作業手順を SKILL.md としてパッケージ化し、必要なときだけClaudeに読み込ませる機能です。個人用は ~/.claude/skills/、プロジェクト用は .claude/skills/ に置き、description で自動発動の精度を、disable-model-invocation や user-invocable で呼び出し方を制御できます。まずは自分がよく貼り付けている指示を1つ、Skillとして切り出してみてください。Claude Code全体の設定は「Claude Code設定完全ガイド」、組み込みコマンドの詳細は「スラッシュコマンド一覧」、Skillの配布方法は「プラグイン導入ガイド」でそれぞれ解説しています。