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

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

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

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

必須ではありません。.claude/commands/のファイルはそのまま動きます。 補助ファイルの同梱や呼び出し制御を使いたい場合は.claude/skills//SKILL.md形式へ書き直すとよいでしょう。 ハブネコのひとこと 毎回同じ指示を貼り付けている作業があるなら、Skillに切り出すだけでコンテキストの消費がだいぶ変わってきます。副作用のある作業はdisable-model-invocationで自動発動を止めておくと安心です。

公開: 2026年8月2日 / 更新: 2026年8月11日・読了目安8分

#Skills #自動化

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

先に結論: Skillsは毎回貼り付けている指示手順をSKILL.mdとして切り出し必要な場面だけ読み込ませる機能で、descriptionへの一致で自動的に、または/スキル名で明示的に呼び出せます。

Claude CodeのSkillsは、いつも同じ指示をコピペしている作業手順をSKILL.mdにまとめ、必要なときだけClaudeに読み込ませる仕組みです。作っておけば該当する依頼で自動発動したり、/スキル名で明示的に呼び出したりできます。

この記事ではSKILL.mdの構造から置き場所、自作の実例、他機能との使い分けまでを解説します。Claude Code全体の設定は「Claude Code設定完全ガイド」もあわせて参考にしてください。

この記事の要点

SkillsはSKILL.mdに作業手順をまとめ、必要なときだけClaudeに読み込ませる仕組みです。

個人用は~/.claude/skills/、プロジェクト用は.claude/skills/に置き、ディレクトリ名がコマンド名になります。

呼び出し方はdescription一致による自動発動と、/スキル名による明示的呼び出しの2通りです。

disable-model-invocation: trueで自動発動を禁止、user-invocable: falseで/メニュー非表示にできます。

frontmatterのcontext: forkでサブエージェントとしてバックグラウンド実行させられます。

前提・動作環境

Skillsはターミナル版のClaude Codeで使える機能です。あらかじめインストール・ログインを済ませ最新版に更新してください。

バージョンで使える機能(サブエージェント実行や動的コンテキスト注入など)が異なるため、挙動が記事と違う場合は次のコマンドで確認しましょう。

claude --version

2.1.220 (Claude Code)

Skillsとは何か

Skillsは、作業手順や知識を「必要なときだけ」呼び出す仕組みです。CLAUDE.mdに書き込むと毎回コンテキストを消費しますが、Skillとして切り出せば実際に使う場面まで本文は読み込まれません。

「同じ指示を毎回貼り付けている」「決まった手順の作業が増えてきた」場面がSkillを作るタイミングの目安です。

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

SKILL.mdの構造と置き場所

Skillは1つのディレクトリで表現され、中心がSKILL.mdです。YAMLフロントマターとMarkdown本文の2部構成で、項目は省略可能ですが自動発動の判断材料になるdescriptionはほぼ必須です。

本文はClaudeが実行時に読む指示そのもので、!`command` と書くとシェルコマンドが実行され出力が埋め込まれます(動的コンテキスト注入・具体例は実践編)。

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

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

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

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

Skillsの呼び出し方は2通りです。1つ目は自動発動で、依頼内容がdescriptionにマッチすると、Claudeが自分で判断してSkillを読み込みます。

2つ目は明示的な呼び出しで、/スキル名と入力すると直接実行できます。

Skillsの呼び出し方が、descriptionに一致して自動発動する経路と、/スキル名で明示的に呼び出す経路の2つに分かれ、どちらもSKILL.mdの読み込み・実行に合流することを示す図解

デプロイやコミットのように副作用のある作業はユーザーが呼び出したときだけ動かしたいものです。

frontmatterにdisable-model-invocation: trueで自動発動を禁止、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自体の機能はスラッシュコマンドです。

Claude Code本体の固定機能はスラッシュコマンド、単発の手順やナレッジは素のSkill、重い調査やレビューはcontext:fork指定のSkillでサブエージェントとして実行するという3つの使い分けを示す図解

Skillはプラグインとしてまとめて配布もでき、詳しい手順は「プラグイン導入ガイド」で扱っています。

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

SkillのディレクトリにはSKILL.md以外のファイルも置けます。

リファレンスやテンプレート、実行用スクリプトを同梱すればSKILL.mdは簡潔なまま必要時だけ追加ファイルを読み込ませられます(例:template.mdに出力フォーマット、scripts/validate.pyに検証スクリプト)。

補助ファイルは本文からリンク参照させるのが基本で、パスは置き場所によらず解決される${CLAUDE_SKILL_DIR}という変数を使うと安全です。

話題のSkill事例:diagram-designとobsidian-skills

公開されているSkillには作業を強力に自動化する例もあります。cathrynlavery/diagram-designはアーキテクチャ図やフローチャート、ER図など27種類の図解タイプに対応し、自己完結型のHTML+SVGを出力するSkillです。

URLを伝えると配色・フォントを自動抽出し、ブランドに合わせた図解をPNG/SVGで生成できます。

もう一つの例がkepano/obsidian-skillsです。

Obsidian CEOのSteph Ango氏(GitHub: kepano)自身が公開したSkillで、Obsidian Flavored MarkdownやBases、JSON Canvasなど独自フォーマットをClaudeが直接読み書きできる5つのSkillをまとめ、開発元自身が自社フォーマット用に整備した事例として参考になります。

業界動向:Vercelの「Agent Plugins」共通規格とClaude Code

2026年8月6日、Vercelは複数ベンダー横断でAIエージェント拡張機能をパッケージ化する共通規格「Agent Plugins」を発表しました。

plugin.jsonマニフェストと標準ディレクトリ構成でAgent SkillsやMCPサーバーを配布でき、対応クライアントはChatGPT/Codex・Cursor・GitHub Copilot・Kiro・VS Code、技術運営委員会にはAWS・Cursor・Microsoft・OpenAI・Vercelが参加しています。

ただしClaude Codeは一覧に含まれず、対応するかは公式未確認です。本記事のSKILL.md形式のSkillsは現時点ではClaude Code独自の仕組みで、最新情報はVercel・Anthropicの公式発表を確認してください。

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

バグイヌ

descriptionをちゃんと書いたはずのSkillが、いつまで経っても自動で発動してくれないんです…!

ハブネコ

frontmatterのYAML構文が壊れていると、Skill自体は読み込まれてもdescriptionが空扱いになります。--debug付きで起動してパースエラーを確認してみてください。

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形式へ書き直すとよいでしょう。

ハブネコのひとこと

毎回同じ指示を貼り付けている作業があるなら、Skillに切り出すだけでコンテキストの消費がだいぶ変わってきます。副作用のある作業はdisable-model-invocationで自動発動を止めておくと安心です。

まとめ

Skillsは、繰り返し使う作業手順をSKILL.mdにパッケージ化し、必要なときだけClaudeに読み込ませる機能です。

個人用は~/.claude/skills/、プロジェクト用は.claude/skills/に置き、disable-model-invocationやuser-invocableで呼び出し方を制御できます。

まずは自分がよく貼り付けている指示を1つ、Skillとして切り出してみてください。

設定は「Claude Code設定完全ガイド」、組み込みコマンドは「スラッシュコマンド一覧」、配布方法は「プラグイン導入ガイド」で解説、Codexの同機能は「Codex Skills」で紹介しています。