Claude Code の Agent Skills(.claude/skills/SKILL.md)を自作する実装手順 — スラッシュコマンド/サブエージェントとの違いと『発火しない』3つのハマりどころ【2026】

はじめに / 対象と前提

Claude Code に「よく使う定型作業」を覚えさせる方法は、スラッシュコマンド・サブエージェント・そして Agent Skills の3つがある。この記事は3つ目の Skills を 自作して自動発火させる ところまでを扱う。

• 想定読者: Claude Code を日常的に使っていて、.claude/commands や .claude/agents は触ったが Skills は未着手のエンジニア
• 前提環境: Claude Code v2.x(2026年7月時点)/ macOS or Linux / エディタは任意
• この記事のゴール: 最小の Skill を1個作り、/ を打たなくても Claude が状況を見て勝手に呼ぶ状態にする

「作ったのに一向に発火しない」で溶ける時間が一番長いので、そこを重点的に潰す。

TL;DR

• Skill の実体は .claude/skills/<name>/SKILL.md 1枚。frontmatter に name と description を書くだけで動く
• Claude は起動時に description だけ を読み、関連しそうな時に初めて本体を読む(progressive disclosure)。だから description の書き方が発火率を決める
• ハマりの9割は「description が曖昧で発火しない」「本体を盛りすぎて無駄」「name 規則違反・再起動忘れ」の3つ

Agent Skills とは / コマンド・サブエージェントとの違い

Skills は「特定の作業のやり方をまとめた説明書フォルダ」で、Claude が 自分で必要と判断したときに読み込む。ユーザーが明示的に呼ぶスラッシュコマンドとはトリガーが違う。

機能	置き場所	起動のされ方	向いている用途
スラッシュコマンド	.claude/commands/*.md	ユーザーが /name で明示的に	手動で毎回叩く定型プロンプト
サブエージェント	.claude/agents/*.md	別コンテキストに委譲	並列調査・独立した重い処理
Agent Skills	.claude/skills/<name>/SKILL.md	Claude が description を見て自動判断	「この状況ならこの手順で」という手続き知識

ざっくり言うと、コマンドは「手動ショートカット」、サブエージェントは「並列の別働隊」、Skills は「勝手に開いてくれるマニュアル」。

手順 / 動かし方

例として「コミットメッセージを Conventional Commits 形式で書く」Skill を作る。

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

mkdir -p .claude/skills/commit-writer

.claude/skills/commit-writer/SKILL.md:

---
name: commit-writer
description: >
  ステージ済みの変更から Conventional Commits 形式のコミットメッセージを生成する。
  ユーザーが「コミットメッセージを書いて」「commit して」と頼んだとき、
  または git commit の直前に使う。
allowed-tools: Bash(git diff:*), Bash(git status:*)
---

# コミットメッセージ生成

## 手順
1. `git diff --staged` でステージ済み差分を確認する
2. 変更の種類を判定し `type(scope): summary` を1行で作る
   - type は feat / fix / docs / refactor / test / chore から選ぶ
3. 本文に「なぜ変えたか」を2〜3行で添える

## 制約
- 件名は50文字以内、命令形
- 差分に無い変更を推測で書かない

2. 認識させる

追加しただけでは読まれないことがある。セッションを開き直すか、/ を一度開いて Claude にスキル一覧を再スキャンさせる。認識されているかは、Claude に「使えるスキルは?」と聞けば確認できる。

3. 動作確認

git add した状態で「コミットメッセージ作って」と頼む。/commit-writer と打っていないのに、Claude が上の手順に沿って差分を読み、Conventional Commits 形式で返してくれば発火成功。

ハマりどころ

① description が曖昧で永遠に発火しない(最頻)

一番多い失敗。description: コミットメッセージ用 のような一言だと、Claude は「今がその状況か」を判断できず素通りする。

description には 「何をするか」+「いつ使うか(トリガーになる状況・言葉)」 を三人称で具体的に書く。

# NG: 何をするかしか書いていない
description: コミットメッセージを生成する

# OK: いつ発火すべきかまで書く
description: >
  ステージ済み差分から Conventional Commits 形式のメッセージを生成する。
  「コミットメッセージを書いて」「commit して」と頼まれたとき、
  または git commit の直前に使う。

発火しないときは本体をいじる前に まず description を疑う。

② SKILL.md を盛りすぎて progressive disclosure を殺す

Skills の肝は「起動時は description だけ、必要になったら本体を読む」という段階的読み込み。ここで SKILL.md 本体に手順を数千行詰め込むと、発火のたびに全部がコンテキストに載って重くなる。

本体は薄く保ち、長い手順表・テンプレ・サンプルは同じフォルダの別ファイルに分けて、必要時だけ参照させる。

.claude/skills/commit-writer/
├── SKILL.md          # 概要と手順の骨子だけ(数十行)
├── examples.md       # 良いコミット例(必要時に読ませる)
└── types-reference.md # type の詳細定義

SKILL.md 内では「詳細な type 定義は types-reference.md を参照」と書いておけば、Claude はその作業が要るときだけ開く。本体 = 目次、詳細 = 別ファイル と割り切る。

③ name 規則違反・スコープ・allowed-tools のミス

• name はフォルダ名と一致・kebab-case。name: Commit Writer のようにスペースや大文字を入れると読み込まれない。フォルダ commit-writer なら name: commit-writer
• スコープ: プロジェクト共有は .claude/skills/、自分専用は ~/.claude/skills/。チームに配りたいのに personal 側へ置いて「他の人に出ない」となりがち
• allowed-tools 未指定だと全ツールを継承する。安全に絞りたい Skill では Bash(git diff:*) のように許可を明示する。逆に絞りすぎて必要な git status が動かない、も定番

背景・補足

なぜコマンドではなく Skills なのか。コマンドは「人間が発火タイミングを覚えている」前提だが、実務では タイミングごと忘れる。Skills は description をトリガー辞書として持たせることで、「この状況ならこの手順」という手続き知識を Claude 側に常駐させられる。使うほど「あの定型、勝手にやってくれた」が増えるのが利点。

まとめ

• Skill は .claude/skills/<name>/SKILL.md を置くだけ。frontmatter の name / description が肝
• Claude は description だけを常時読み、関連時に本体を開く(progressive disclosure)。発火率は description の具体性で決まる
• 詰まったら「description が曖昧」→「本体を盛りすぎ」→「name/スコープ/allowed-tools」の順に疑う
• 本体は目次、詳細は別ファイル。薄く保つほど速くて発火が安定する