はじめに

この記事は前回の Claude Code 入門記事を読んでいる前提で書いています。「Skill ってそもそも何？」という方は先にこちらをご覧ください。

https://qiita.com/i-inose/items/e644e9b620ee1c8d3c1b

以前の記事で Claude Code の全体像を紹介したとき、Skill については「繰り返し行う作業をスラッシュコマンドとして定義・再利用する仕組みです」とざっくり説明するにとどめました。

今回はその続きです。実際に Skill を作って動かしながら、仕組みをひとつずつ掘り下げていきます。

この記事で紹介するのは、技術文書やコードを読んで学ぶための4つの Skill です。

スキル名	やること
`/explain`	ファイルの内容を日本語で解説する
`/summarize`	技術文書を要点まとめに変換する
`/quiz`	内容から理解度確認クイズを生成する
`/glossary`	登場する専門用語の用語集を生成する

解説で使うデモプロジェクトは GitHub に公開しています。手元で動かしながら読みたい方は、先にセットアップしておいてください。

以下をコピペしてクローンし、 demo/ に移動して Claude Code を起動するだけです。

git clone https://github.com/i-inose/demo.git
cd demo
claude

以下の順で解説していきます。

章	テーマ
第1章	Skill のおさらいと今回の構成
第2章	`/summarize` を作って SKILL.md の構造を理解する
第3章	`/quiz` で `$ARGUMENTS` の使い方を深掘りする
第4章	`/glossary` でフロントマターの他のオプションを見る
第5章	Skill を育てるコツ
ハンズオン	実際にSkillを作って動かしてみる

第1章 Skill のおさらいと今回の構成

前回の記事で Skill の基本は説明しましたが、簡単に振り返ります。

Skill は .claude/skills/<スキル名>/SKILL.md というファイルを作るだけで使えるようになります。プロジェクトのルートに .claude/ ディレクトリを置いて、その中に skills/ ディレクトリを作るだけです。

your-project/
└── .claude/
    └── skills/
        ├── explain/
        │   └── SKILL.md
        ├── summarize/
        │   └── SKILL.md
        ├── quiz/
        │   └── SKILL.md
        └── glossary/
            └── SKILL.md

今回使うデモプロジェクトはシンプルなタスク管理 CLI です。Python で書かれた task.py と cli.py、それからテストファイルが入っています。この3つのファイルを使って Skill を動かします。

第2章 `/summarize` の SKILL.md で構造を理解する

まず一番シンプルな /summarize から始めます。

SKILL.md を読んでみる

/summarize の SKILL.md はこんな内容です。

---
name: summarize
description: 指定した技術文書やファイルを要点まとめに変換する
allowed-tools: Read Grep Glob
---

$ARGUMENTS で指定されたファイルまたはテキストを読んで、日本語で要点まとめを生成してください。

以下の形式で出力してください。

## この文書について
- 何について書かれているか（1〜2文で）

## 重要なポイント
- 本文から読み取った主要な内容を箇条書きで（3〜5項目）

## キーワード
- 文中に登場する重要な技術用語や概念を列挙する

初めてこのテーマに触れる人にもわかるよう、平易な言葉でまとめてください。

SKILL.md の構造を読む

SKILL.md は大きく2つに分かれています。--- で囲まれた上部がフロントマター（メタ情報）で、その下が Claude へ渡すプロンプト本文です。

---
フロントマター（メタ情報）
---

プロンプト本文（Claude への指示）

フロントマターで使ったフィールドは3つです。

name はスラッシュコマンドの名前になります。name: summarize と書くと /summarize で呼べるようになります。

description は Claude が自動でこのスキルを呼ぶかどうかを判断するときに使われます。「この説明文を読んで、今の作業に合いそうなら呼び出す」という仕組みです。

allowed-tools は、このスキルが使えるツールを絞り込む設定です。Read Grep Glob と書いたので、ファイルの読み取りと検索だけ許可しています。ファイルを書き換えるツールは使えない状態になります。読み取り専用の作業には、余分な権限を与えないほうが安全です。

実際に動かしてみる

Claude Code を起動して /summarize task.py と入力します。

task.py の内容が「この文書について」「重要なポイント」「キーワード」の形式でまとめられました。プロンプトに書いたフォーマットのとおりに出力されているのがわかります。

第3章 `/quiz` の SKILL.md で `$ARGUMENTS` を理解する

次は /quiz です。このスキルを通して $ARGUMENTS の動きを確認します。

SKILL.md を読む

/quiz の SKILL.md はこんな内容です。

---
name: quiz
description: 指定したファイルの内容から理解度確認クイズを生成する
allowed-tools: Read Grep Glob
---

$ARGUMENTS で指定されたファイルを読んで、内容を理解できているか確認するためのクイズを日本語で生成してください。

以下の形式で出力してください。

## クイズ（全3問）

**Q1.**（内容から出題）
A. 選択肢1
B. 選択肢2
C. 選択肢3

**Q2.**（内容から出題）
A. 選択肢1
B. 選択肢2
C. 選択肢3

**Q3.**（内容から出題）
A. 選択肢1
B. 選択肢2
C. 選択肢3

## 答え
Q1: X（理由の説明）
Q2: X（理由の説明）
Q3: X（理由の説明）

難易度は「読めば答えられる」程度にしてください。

`$ARGUMENTS` の仕組み

$ARGUMENTS はスラッシュコマンドに渡した引数が展開される変数です。

/quiz task.py

と入力すると、プロンプト本文の $ARGUMENTS が task.py に置き換わります。つまり Claude には「task.py で指定されたファイルを読んで...」という指示として届きます。

複数の引数も渡せます。

/quiz task.py cli.py

この場合は $ARGUMENTS が task.py cli.py になります。スペース区切りで複数ファイルを渡すのも普通に動きます。

動かしてみる

まず task.py 1ファイルだけ渡してみます。

task.py の内容だけをもとにしたクイズが生成されました。

次に task.py と cli.py の2ファイルをまとめて渡してみます。

1ファイルのときと比べて、2つのファイルをまたぐ内容のクイズが出題されているのがわかります。$ARGUMENTS にスペース区切りで渡すだけで、Claude が両方のファイルを読んで出題範囲を広げてくれます。

第4章 `/glossary` でフロントマターの他のオプションを見る

最後は /glossary です。ここでは前の2つで使わなかったフロントマターのオプションを紹介します。

SKILL.md を読む

/glossary の SKILL.md はこんな内容です。

---
name: glossary
description: 指定したファイルに登場する専門用語の用語集を生成する
allowed-tools: Read Grep Glob
---

$ARGUMENTS で指定されたファイルを読んで、登場する専門用語・技術用語の用語集を日本語で生成してください。

以下の形式で出力してください。

## 用語集

| 用語 | 読み方 | 説明 |
|------|--------|------|
| 用語名 | よみがな | 初めて聞く人にもわかるような平易な説明 |

- 用語は登場順に並べる
- 説明は1〜2文で簡潔にまとめる
- 英語の技術用語には日本語での補足も添える

フロントマターで使えるその他のオプション

前回記事でも触れましたが、改めてフロントマターで使えるオプションをまとめます。

フィールド	説明
`name`	スラッシュコマンド名。`/` のあとに続く文字列
`description`	Claude が自動で呼ぶかを判断するときに参照する説明文
`allowed-tools`	このスキルが使えるツールをスペース区切りで指定する
`disable-model-invocation`	`true` にすると手動呼び出し専用になる
`context: fork`	サブエージェントのコンテキストで実行する

disable-model-invocation: true は使いどころが地味に重要です。description に書いた説明がたまたま今の作業に引っかかって、意図せず呼び出されるのを防げます。「このスキルは自分が明示的に呼んだときだけ動いてほしい」という場合に入れておくと安心です。

context: fork は、メインの会話コンテキストとは別の独立した場所でスキルを実行する設定です。スキルが大量のテキストを読み込んだり生成したりするとき、メインのコンテキストウィンドウを圧迫しないで済みます。

動かしてみる

cli.py を渡して実行してみます。

cli.py に登場する argparse（引数パーサー）、TaskManager、subparser などの用語が、よみがなと説明つきでまとめられました。

第5章 Skill を育てるコツ

description を丁寧に書く

Claude が Skill を自動で呼ぶかどうかは、description の内容で判断します。「何をするスキルか」だけでなく「どんな場面で使うか」まで書くと精度が上がります。

# 薄い書き方
description: ファイルの要点をまとめる

# 丁寧な書き方
description: 指定した技術文書やファイルを要点まとめに変換する。
  新しいコードを読み始めるときや「このファイルが何をしているか素早く把握したい」ときに使う。

公式ドキュメントでは「ユーザーが自然に口にするキーワードを description に含めること」「key use case を先頭に書くこと（長い description は途中で切り捨てられるため）」が推奨されています。Skill が期待通りに呼ばれないときのトラブルシューティングも公式に載っています。

500行以内に収める

公式ドキュメントは「SKILL.md は500行以内に収めること」を推奨しています。長くなりすぎた場合は、詳細な参考情報を別ファイルに切り出して SKILL.md から参照する形にします。

my-skill/
  SKILL.md           ← 概要と呼び出し手順だけ
  reference.md       ← 詳細なAPI仕様など
  examples/
    sample.md        ← 出力例

ハンズオン: `/explain` スキルを自分で作る

ここまで3つのスキルを動かしてきました。最後は /explain を自分で作ってみましょう。

クローンしたリポジトリには /explain スキルがすでに入っているので、まず削除するところから始めます。

rm -rf .claude/skills/explain

削除できたら、同じ場所に新しくディレクトリと SKILL.md を作ります。

mkdir -p .claude/skills/explain
touch .claude/skills/explain/SKILL.md

.claude/skills/explain/SKILL.md をエディタで開いて、以下の内容を書いてください。

---
name: explain
description: ファイルや関数の内容を日本語でわかりやすく説明する
allowed-tools: Read Grep Glob
---

$ARGUMENTS で指定されたファイルを読んで、日本語でわかりやすく説明してください。

以下の順で説明してください。

1. このファイルが何をするものか（一言で）
2. 主要なクラス・関数の役割
3. 他のファイルとの関係や依存

このコードを初めて見るエンジニアにもわかるように、平易な言葉で説明してください。

保存したら Claude Code から呼び出してみます。

/explain task.py

task.py が何をするファイルで、どんなクラスや関数があって、他のファイルとどう関係しているかが日本語で説明されます。SKILL.md に書いた指示のとおりに出力されているのが確認できます。

おわりに

4つの Skill を用いて、SKILL.md の構造・$ARGUMENTS・フロントマターのオプションを一通り試しました。

作ってみてあらためて感じたのは、Skill は「プロンプトを再利用可能にする仕組み」だということです。毎回 Claude に説明していた「この形式で出力して」「このファイルを読んで」という指示を一度 SKILL.md に書いておけば、以降は /summarize task.py の一言で済みます。

次は自分のプロジェクトに合わせた Skill を作ってみてください。allowed-tools で権限を絞る、context: fork でコンテキストを分離する、この2つを意識するだけで動作が安定します。

また、Skillを含め、Claude Codeについて深く知りたい方はベストプラクティス集を読んでみてください。