SKILL.mdの書き方 — progressive disclosureで巨大な業務知識を圧縮する【実運用13スキルの設計】

はじめに：業務知識をプロンプトに全部書くと破綻する

当社（合同会社ジョインクラス）は、書籍出版・記事執筆・Kindle登録準備などの業務を Claude Code の Skills で回しています。現在 .claude/skills/ 配下には13個のスキルがあり、/publish-kindle や /write-qiita のように呼び出して使っています。

最初に失敗したのは「業務知識を全部 CLAUDE.md に書く」やり方でした。Kindle の規約、EPUB の組版ルール、記事のスコアリング基準…と書き足していくうちに、どの会話でも関係のない知識がコンテキストを圧迫し、肝心の指示が埋もれていきました。

この記事では、その反省から辿り着いた progressive disclosure（段階的開示） による SKILL.md の設計を、実際に動いているファイルとスクリプトをベースに解説します。

progressive disclosure の3層構造

Skills は、内容を3段階に分けてロードします。

層	何が読まれるか	いつ読まれるか
1. メタデータ	フロントマターの name / description	常時（全スキル分）
2. 本文	SKILL.md の本体	スキルが選ばれたとき
3. 付属リソース	スクリプト・参照ファイル	本文の指示で必要になったとき

ポイントは 層1は全スキル分が常に読み込まれる ことです。ここが長いと13スキル×description分のトークンを毎回払うことになります。逆に層3は、実行されるまで1トークンも消費しません。つまり設計の原則は1つです。

重い知識ほど下の層に押し下げる。

実装1：層1 — description は「何を・いつ・どう呼ぶか」だけ

実際の /write-qiita のフロントマターです。

.claude/skills/write-qiita/SKILL.md

---
name: write-qiita
description: Qiita記事を作成する。LGTM最大化のスコアリング基準（100点満点）に基づき、80点以上の記事のみ出力。使い方 /write-qiita "テーマ"
---

# /write-qiita — Qiita記事作成スキル

あなたはQiita向け技術記事の専門ライターです。
**記事を書く前にスコアリング基準を確認し、80点以上の記事のみ出力します。**

description に入れているのは次の3点だけです。

1. 何をするか（Qiita記事を作成する）
2. 判断基準の要約（80点以上のみ出力）
3. 呼び出し方（/write-qiita "テーマ"）

スコアリング基準の中身（100点の内訳）は書きません。それは層2の本文の仕事です。

落とし穴：description が曖昧だと「選ばれない」

当社では write-zenn / write-qiita / write-note という似たスキルが並んでいます。初期は description が「技術記事を書く」程度だったため、意図と違うスキルが起動することがありました。プラットフォーム名と固有の判定基準を description に必ず入れることで解消しました。

実装2：層2 — 本文は「手順」と「判断」だけ、詳細はスクリプトへ

/publish-kindle の SKILL.md は214行あります。それでも肥大化しないのは、機械的に判定できる知識をすべてスクリプトに追い出しているからです。本文の該当ステップはこれだけです。

.claude/skills/publish-kindle/SKILL.md（抜粋）

### Step 2: EPUB品質チェック（機械検査が先）

python3 ~/workspace/one-ceo/.company/scripts/check-kindle-epub.py <EPUBパス>
python3 ~/workspace/one-ceo/.company/scripts/check-kindle-epub.py --all

違反があれば Step 3 へ。なければ Step 2b（目視確認）へ。

### Step 5: 修正確認

# 目次リンクが全数解決することを確認（必須）
python3 .company/scripts/fix-epub-toc.py --check {epub-path}
# → 「✅ 正常」であること

SKILL.md には「どのスクリプトを、どの順で、何を合格条件として実行するか」だけを書きます。禁止ドメインのリストや表紙比率といった知識そのものは本文に書きません。

実装3：層3 — 業務知識はスクリプトに「コードとして」封じ込める

呼ばれる側の check-kindle-epub.py の冒頭です（実ファイルから抜粋）。

.company/scripts/check-kindle-epub.py

#!/usr/bin/env python3
"""Kindle登録前のEPUB検査 — KDP規約違反と組版崩れを登録前に落とす。

2026-09-25、AI-DLCの教科書をKDPへ登録する直前に外部リンク13件が見つかった。
原因はZenn版のCTAをそのままKindle版に流し込んでいたこと。
手作業の目視では6冊中1冊の違反を見落としていたため、機械的に判定する。

使い方:
    check-kindle-epub.py <EPUBパス> [...]
    check-kindle-epub.py --all          # books/*/kindle/*.epub を全部

終了コード 0=合格 / 1=違反あり
"""
import re
import sys
import zipfile
from pathlib import Path

BOOKS_DIR = Path.home() / "workspace/zenn-content-company/books"

# KDPが本文からの誘導を禁止しているドメイン
BANNED_DOMAINS = {
    "amzn.to": "Amazonアフィリエイト（本文への挿入は禁止）",
    "zenn.dev": "Zenn（他販売サイトへの誘導）",
    "note.com": "note（他販売サイトへの誘導）",
    "qiita.com": "Qiita（外部サイトへの誘導）",
}

# 表紙はKDP推奨比率 1.6（1600x2560）。0.05以上ずれると警告。
COVER_RATIO = 1.6

このファイルは Claude が実行するだけで、中身を読む必要がありません。禁止ドメインが10個に増えても、SKILL.md のトークン数は1つも増えない。これが progressive disclosure の一番効く使い方です。

設計上のコツは2つあります。

• 終了コードで合否を返す（0=合格 / 1=違反）。Claude は出力を全部読まずに分岐できる
• docstring に「なぜこの検査があるか」を書く。将来 Claude がスクリプトを修正するときだけ読まれる、いわば「層4」の知識

筆者の実体験：目視チェックを SKILL.md に書いていた頃

以前は SKILL.md に「外部リンクがないか確認すること」と文章で書いていました。結果、6冊中1冊で違反を見落とし、登録直前に Amazon アフィリエイトリンクを含む外部リンク13件が見つかりました。自然言語の「確認すること」は、LLMにとっても人間にとっても抜け漏れる。判定可能なものはコードに落とす、と決めたのはこのときです。

その日にできる移行手順

既存の長い CLAUDE.md や SKILL.md を分割する手順です。

1. SKILL.md の各段落を「手順」「判断基準」「事実データ（リスト・閾値）」に色分けする
2. 「事実データ」をスクリプトの定数に移す（BANNED_DOMAINS のように）
3. 「判断基準」のうち機械判定できるものをスクリプトの検査ロジックにし、終了コードで返す
4. SKILL.md には「スクリプト名・実行順・合格条件」だけ残す
5. description を「何を・基準の要約・呼び出し方」の1〜2文に削る

検証方法

分割後は、次のコマンドで層ごとのサイズを確認しています。

cd ~/workspace/one-ceo

# 層2：本文の行数（当社の目安は300行以内）
wc -l .claude/skills/*/SKILL.md

# 層1：description の長さ。長すぎるものを洗い出す
for f in .claude/skills/*/SKILL.md; do
  desc=$(grep -m1 '^description:' "$f")
  echo "${#desc} $f"
done | sort -rn | head

# 層3：スクリプトが合否を終了コードで返すか
python3 .company/scripts/check-kindle-epub.py --all; echo "exit=$?"

当社の実測では、write-qiita が98行、publish-kindle が214行です。300行を超えたら「スクリプトに追い出せる知識が残っていないか」を見直す合図にしています。

最後に、実際にスラッシュコマンドでスキルを呼び、意図したスキルが選ばれるか、スクリプトが実行されてから判断しているかをトランスクリプトで確認します。スクリプトを呼ばずに「確認しました」と言っている場合は、SKILL.md の該当ステップに「必須」「合格条件」を明記すると改善しました。

まとめ

• 層1（description）は常時ロードされる。短く、ただし他スキルと区別できる固有語を入れる
• 層2（本文）は手順と合格条件だけ。知識そのものは書かない
• 層3（スクリプト）に業務知識をコードとして封じ込め、終了コードで合否を返す
• 「確認すること」という自然言語は抜け漏れる。判定できるものはコードにする

業務知識が増えるほど、AIに「全部読ませる」のではなく「必要なときだけ読ませる」設計が効いてきます。13スキルを運用してきた当社の結論は、SKILL.md は知識の置き場ではなく、知識への索引であるということです。

もっと深く知りたい方へ

Skills の設計パターン、付属リソースの構成、プラグインとしての配布方法までを体系的にまとめたのが『Claude Skills 完全ガイド』です。本記事の3層設計をさらに掘り下げています。

書籍一覧はこちら: https://zenn.dev/joinclass?tab=books