Claude Code の Agent Skills(SKILL.md)を自作する実装手順 — description で発火しない・allowed-tools・補助ファイル参照の3つのハマりどころ【2026】

はじめに / 対象と前提

Claude Code には、特定の作業手順やチェックリストをパッケージ化して Claude に読み込ませる Agent Skills という仕組みがある。SKILL.md というファイルを置くだけで「このタスクのときはこの手順書を読んでから作業して」を自動化できる。

この記事は以下の読者向け。

• Claude Code を日常的に使っていて、毎回同じ指示をプロンプトに書くのに疲れた人
• CLAUDE.md が肥大化してきて、常時読み込む必要のない手順を分離したい人

検証環境は macOS 15 / Claude Code v2.x(2026年時点)。Skills はプロジェクト単位・ユーザー単位のどちらでも動く。

TL;DR

• .claude/skills/<スキル名>/SKILL.md を作れば、Claude が関連タスクのときだけ自動で読み込む
• 発火のトリガーは frontmatter の description だけ。本文をどれだけ丁寧に書いても description が曖昧だと一切発火しない
• 補助ファイルは SKILL.md に「いつ読むか」を明記しないと読まれない。分割しただけでは動かない

手順 / 動かし方

1. フォルダと SKILL.md を作る

プロジェクト用なら .claude/skills/、全プロジェクト共通なら ~/.claude/skills/ に置く。

mkdir -p .claude/skills/db-migration

SKILL.md は YAML frontmatter + Markdown 本文の構成。

---
name: db-migration
description: DBマイグレーションファイルを作成・修正するときに使う。migration、schema変更、ALTER TABLE、カラム追加などの作業で必ず読むこと。
---

# DBマイグレーション手順

1. 既存のマイグレーション一覧を確認(`ls db/migrations/`)
2. up と down を必ずペアで書く
3. 本番データがある前提で、NOT NULL 追加は必ず DEFAULT を付ける
4. 作成後は必ずローカルで up → down → up を通す

2. 動作確認

新しいセッションを開始して(既存セッションはスキル一覧を再読み込みしないことがある)、トリガーに該当する依頼を投げる。

> users テーブルに last_login_at カラムを追加するマイグレーションを作って

発火すると、Claude がツール実行で SKILL.md を読み込んでから作業を始めるのがログで確認できる。発火しているかどうかの切り分けには /db-migration のようにスラッシュコマンドで明示起動できる(明示起動で動くのに自然文で発火しないなら、原因は description にある)。

3. ツール制限を付ける(任意)

frontmatter に allowed-tools を書くと、そのスキル実行中に使えるツールを絞れる。

---
name: log-analysis
description: 本番ログの調査・集計のときに使う。読み取り専用。
allowed-tools: Read, Grep, Glob, Bash
---

調査系スキルで Edit / Write を外しておくと、「ログ調査のつもりがファイルを書き換えられていた」事故を構造的に防げる。

ハマりどころ

1. description が抽象的だと発火しない

最初に自分が書いたのはこれだった。

description: データベース関連の便利な手順集

これだと migration 作業を頼んでも一切発火しない。Claude はセッション開始時に name と description のメタデータしか見ていない(本文はこの時点でコンテキストに載っていない)。つまり description は「人間向けの説明文」ではなく「発火条件の定義」として書く必要がある。

回避策は、ユーザーが実際に打ちそうなキーワードを具体的に列挙すること。

description: DBマイグレーションファイルを作成・修正するときに使う。migration、schema変更、ALTER TABLE、カラム追加などの作業で必ず読むこと。

「〜のときに使う」+具体的トリガー語の列挙、が経験上いちばん安定する。

2. frontmatter の構文エラーで黙って無視される

name に大文字やスペースを入れたり、frontmatter の --- を閉じ忘れたりすると、エラーは出ずにスキルがただ存在しないことになる。読み込み失敗のログが出ないので、「書いたのに発火しない」の原因が構文なのか description なのか切り分けに時間を食った。

チェックポイントは3つ。

• name は小文字英数字とハイフンのみ(フォルダ名と一致させる)
• frontmatter は1行目の --- から始まり --- で閉じる(先頭に空行があるだけでも無効)
• インデントにタブを使わない(YAML の一般的な罠)

/ を打ってスラッシュコマンド候補に自作スキル名が出るかどうかで、読み込み自体の成否を確認できる。

3. 補助ファイルは「分割しただけ」では読まれない

SKILL.md が長くなったので references/checklist.md に詳細を分割したところ、Claude がそのファイルを読まずに作業を進めることがあった。

原因は単純で、SKILL.md 側に「いつ・どのファイルを読むか」を書いていなかったから。補助ファイルは自動では読み込まれず、SKILL.md の指示に従って必要になったときに読まれる(段階的読み込み)。

## 詳細チェックリスト

本番適用前のレビュー時は、必ず references/checklist.md を読んで全項目を確認すること。

このように参照タイミングを明文化すれば安定して読まれる。逆に言えば、この仕組みのおかげで滅多に使わない詳細資料をコンテキスト消費ゼロで持てる。SKILL.md 本体は500行以内に収め、詳細は補助ファイルへ、が公式推奨の目安。

背景・補足

CLAUDE.md との使い分けは「常時必要か、特定タスクのときだけ必要か」で判断するとよい。CLAUDE.md は毎セッション全文がコンテキストに載るので、書けば書くほど常時コストがかかる。一方 Skills は発火するまで description(数十トークン)しか消費しない。自分の場合、CLAUDE.md に書いていた手順のうち「特定作業のときしか参照しないもの」を Skills に移したら、CLAUDE.md を大幅に痩せさせられた。

まとめ

• .claude/skills/<name>/SKILL.md を置くだけでタスク特化の手順書を自動読み込みできる
• description は説明文ではなく発火条件。具体的なトリガー語を列挙する
• 構文エラーは黙殺されるので、スラッシュコマンド候補に出るかで読み込みを確認する
• 補助ファイルは参照タイミングを SKILL.md に明記して初めて機能する
• 常時必要なものは CLAUDE.md、タスク特化のものは Skills に分離するとコンテキストを節約できる