スキルで、手順をスラッシュひとつで呼べる道具にする

前回の終わりに書いた問題から始めます。CLAUDE.md は常に読まれるので、常に関係することしか書けません。

ところが、作業には「そのときだけは全部必要だが、ふだんは邪魔」という手順があります。リリースの段取り、画像を生成する手順、特定の形式のデータを取り込む方法。これらを CLAUDE.md に書くと、関係ない依頼のときも毎回読まれることになります。

スキルは、この種類の知識のための置き場所です。

必要になったときだけ開かれる

仕組みは単純です。Claude は最初、各スキルの名前と説明文と置き場所だけを受け取っています。本文は読んでいません。

作業の内容から「これは使えそうだ」と判断したときに、SKILL.md を読みに行きます。読んだあとは、その中に書かれたファイルを見たり、スクリプトを実行したりします。

つまり、手順書が何ページあっても、使わない回には1行も読まれないということです。CLAUDE.md との一番の違いはここにあります。

作り方はフォルダ1つと SKILL.md 1つ

スキルの実体はフォルダです。その中に SKILL.md を置きます。

.claude/skills/
  release-blog/
    SKILL.md
    check-links.mjs

SKILL.md の先頭には、名前と説明文を書きます。

---
name: release-blog
description: ブログの記事をステージングから本番へ公開する手順。「リリース」「公開して」で使用する。記事の執筆そのものには使わない。
---

# ブログのリリース手順

1. 作業ブランチで npm run validate:content && npm run check:links を通す
2. ...

区切り線ではさまれた部分が設定、その下が手順の本文です。本文の書式に決まりはありません。人が読んで手順どおり動ける文章なら、そのまま通ります。

説明文が、呼ばれるかどうかを決める

本文をどれだけ丁寧に書いても、呼ばれなければ効きません。

説明文に書くのは、どういうときに使い、どういうときに使わないかです。上の例に「記事の執筆そのものには使わない」を足しているのはそのためで、使わない場面を書いておくと、関係のない依頼で誤って呼ばれることが減ります。

BenriWorks で動いているスキルの説明文も、同じ作りです。

description: Gemini APIで記事・アプリのアイキャッチ用フォトリアル写真を生成し、
public/images配下に配置する。「アイキャッチを生成」「写真を生成」「gen-image」で使用。
要 GEMINI_API_KEY 環境変数と generativelanguage.googleapis.com へのネットワーク許可。

何をするか、どの言葉で呼ばれるか、何が前提として要るか。1文ずつ入っています。

置き場所は用途で分ける

選び方は CLAUDE.md と同じ考え方です。チームの作業ならリポジトリ、自分の好みなら個人。リポジトリに置いたものは、他の人が読んで直せます。

自分から呼ぶ

Claude の判断に任せるだけでなく、自分で呼べます。ここが Claude Code のスキルの使いやすいところです。

入力欄で / を打つと、使えるコマンドの一覧が出ます。組み込みのコマンド、自分で書いたスキル、プラグインや MCP が足したコマンドが並びます。

引数も渡せます。/fix-issue 123 と打つと、123 がスキルの中の $ARGUMENTS に入ります。位置で受け取る $0 や $1、名前で受け取る形もあります。

スキルの中では、いくつかの値が使えます。

${CLAUDE_SKILL_DIR} が効きます。同梱したスクリプトを呼ぶときに、置き場所を決め打ちせずに書けます。

呼ばれ方を3通りに制御する

誰が呼べるかを設定で決められます。

デプロイのように外へ影響が出る手順は、Claude が自分の判断で呼べないようにしておく。第5回で決めた「戻せない操作は人が決める」という線を、スキルの側にも引けます。

paths を書くと、該当するファイルを扱っているときだけ有効になります。第9回の規則と同じ仕組みです。

依頼の前にコマンドの結果を差し込む

もう1つ、便利な仕組みがあります。スキルの本文にコマンドを書いておくと、Claude に渡る前に実行され、その出力が差し込まれます。

いまの変更: !`git diff HEAD`

複数行で書く形もあります。

```!
git status
node --version
```

コマンドはセッションの作業フォルダで走ります。異常終了すると、そのスキルの呼び出し自体が中止されます。

使いどころは、毎回同じ前提を集めてから依頼したいときです。「いまの差分を見てレビューして」と頼むとき、差分を取る手間を省けるだけでなく、取り忘れがなくなります。

別の文脈で走らせる

前書きに次の3行を足すと、そのスキルは別の文脈で走ります。

context: fork
agent: Explore
background: false

会話の履歴を持たない別の作業として動くので、長い調査をさせても本流の文脈が汚れません。第12回で扱うサブエージェントの入口が、ここにもあります。

文章より、実行できる形にする

スキルはフォルダなので、SKILL.md の横にスクリプトや資料を置けます。

手順の中で「このスクリプトを実行する」と書いておけば、実行されます。手順を文章で説明するより、この形のほうが結果は安定します。文章は解釈の幅がありますが、スクリプトにはありません。

BenriWorks の画像生成のスキルも、本文に手順を書きつつ、実処理はスクリプト側に置いています。

揺れてほしくないところをコードにし、揺れてよいところを文章にする。この切り分けが、スキルを書くときの実際的な設計になります。

何をスキルにするか

手順が決まっていること。間違えると面倒なこと。たまにしかやらないこと。この3つがそろう作業が向きます。

そろっている必要があります。手順が決まっていなければ書けません。間違えても困らないなら書く価値がありません。毎回やる作業は手が覚えるので、書いても読まれません。

向かないのは判断が要る作業です。「どの設計にするか決める」はスキルになりません。手順にできるのは、決めたあとの実行部分だけです。

次の回

CLAUDE.md とスキルは、どちらも書いて置いておける知識でした。

書いておけないものもあります。いま本番で出ているエラー、チケットの状態、外部サービスの現在の設定。第11回の MCP は、そこへ手を伸ばすための仕組みです。

参照した公式情報

• Anthropic「Skills」「Interactive mode」（code.claude.com/docs、2026年9月時点）
• 引用した説明文は BenriWorks のブログリポジトリで実際に使っているスキルのもの