はじめに
Claude Code の Skills を作るとき、「フォルダ構成をどうすればいいのか」「呼び出し方はどうなるのか」が最初の壁でした。Progressive Disclosure（段階的開示）という考え方でトークンを節約できることがわかりました。
この記事の対象読者・前提条件
対象読者
- Claude Code でカスタムスキルを作りたい方
- Skills のフォルダ構成がよくわからない方
前提条件
- Claude Code インストール済み
- Commands と Skills の違いを理解している
課題：1ファイルに全部書くとトークンを浪費する
従来の Commands 形式では、1ファイルに全部書いていたため、毎回すべての情報がコンテキストに読み込まれ、トークンを消費していました。
アプローチ
Skills のフォルダ構成
.claude/skills/generate-component/
├── SKILL.md ← メインの指示書
├── references/
│ └── naming-rules.md ← 命名規約の詳細
├── scripts/
│ └── validate.sh ← 検証スクリプト
└── examples/
└── sample.tsx ← サンプルコード
Progressive Disclosure の流れ
1層目: SKILL.md の frontmatter（description）
→ Claude が「このスキルを使うべきか？」を判断
→ 常にメモリ上にある（数十トークン）
2層目: SKILL.md の本文
→ スキルが選ばれたら読み込まれる
→ ゴール・制約・ワークフロー（数百トークン）
3層目: references/ 配下のファイル
→ Claude が「この情報が必要」と判断したときだけ読む
→ テンプレート・詳細規約（必要な分だけ消費）
$ARGUMENTS の使い方
スラッシュコマンドの後ろに渡すテキストが $ARGUMENTS に自動で置き換わります。Spring Boot の @PathVariable のようなものです。
/generate-component Button
↑ ここが $ARGUMENTS
2パターンの呼び出し方
| パターン | 例 | Commands | Skills |
|---|---|---|---|
| 明示的 | /generate-component Button |
○ | ○ |
| Claude自動判断 | 「Buttonコンポーネント作って」 | × | ○ |
まとめ
- Skills は SKILL.md + references/ + scripts/ + examples/ のフォルダ構成
- Progressive Disclosure で必要なときだけ補助ファイルを読む
-
$ARGUMENTSでスラッシュコマンドの引数を受け取れる - スラッシュコマンド + Claude自動判断の2パターンで呼び出せる