【2026年最新】Claude Skills開発実践ガイド｜SKILL.md設計

「結局、Skillって何が便利なのか」を5分で

Claude Skillsという公式機能が2025年10月にGAになって以降、社内のClaude Code利用者から「CLAUDE.mdに全部書いてるけどあれと何が違うの？」という質問が増えました。実際に私のMacには記事執筆時点で200個以上のSkillを入れていて、仕事の8割をClaude Codeに任せる運用をしています。その経験から先に答えだけ書きます。

Skillの最大の違いは「使うときだけロードされる」こと。CLAUDE.mdに全プロジェクト共通の指示を200行書くと、毎ターン200行ぶんのトークンを払い続けます。一方Skillsはfrontmatterのdescription（公式仕様で最大1,024字）だけが常時ロードされ、本体は該当タスクのときだけbash経由で読み込まれます。Anthropicの公式ドキュメントでは「each Skill consumes around 100 tokens at startup」と表現されています（出典：Anthropic Agent Skills公式ドキュメント、2026年5月時点）。

これがいわゆるprogressive disclosure（段階的開示）で、Skillの本体が500行あろうが10MBの参照ファイルを抱えていようが、使うまでは0トークン。私の環境では「LP制作」「PR TIMES配信」「note記事執筆」など領域別に200個以上の手順書をSkill化していますが、Claude Codeの初期コンテキスト消費は許容範囲に収まっています。

本記事ではAnthropic公式ドキュメント・Claude Code公式ドキュメントの仕様に沿って、SKILL.md設計のコピペ可能なテンプレートと、200個運用してきた経験から得た「失敗パターン」を全公開します。

なぜ今Skillsを学ぶべきか：CLAUDE.mdとの本質的な違い

2025年10月のSkills GA以降、エンジニア界隈で「結局CLAUDE.mdと何が違うのか」という議論が続いています。私は当初「CLAUDE.mdに整理ルールを書けば十分では」と思っていた側だったので、その立場から実測比較してみた結果を共有します。

検証環境では、Uravationの主要プロジェクト（uravation.com / aigentlab.tech / hojokin-dx.comの3サイトを束ねるWPテーマリポ）で、CLAUDE.mdに約4,200字（実テキスト）の運用ルールを書いていました。これを「事実情報」と「手順情報」に切り分けて、手順側をSkillsに移したところ、起動時のシステムプロンプトサイズが約3,500トークン減りました（社内測定・Claude Code v2.1系・2026年4月実測）。1日30セッション回すアカウントだと、1日あたり10万トークン以上のセーブになります。

もっと本質的な違いは「アクセス頻度の違うコンテンツを分離できる」こと。CLAUDE.mdに書く内容は「毎セッション必ず必要な事実」（会社情報・ディレクトリ構造・絶対ルール）、Skillsに書く内容は「特定タスクで必要な手順」（PR TIMES入稿手順・PRDテンプレ生成・デプロイフロー）。この切り分けが効きます。Anthropic公式も「Create a skill when you keep pasting the same instructions, checklist, or multi-step procedure into chat, or when a section of CLAUDE.md has grown into a procedure rather than a fact」と明言しています（出典：Claude Code Skills公式、2026年5月時点）。

もう1つ意外と知られていないのがSkills は Agent Skills openスタンダード（agentskills.io）に準拠している点。Claude Code以外のAIツール（将来的に他社製品も含む）と互換性のある仕様なので、ベンダーロックインのリスクが相対的に低いです。CLAUDE.mdはClaude固有なので、ここでも分離する意味があります。

Claude Skillsの正式仕様（公式ドキュメントベース）

ディレクトリ構造（Claude Code版）

Claude Codeのskillは「ディレクトリベース」です。1 skill = 1 directory、その中にSKILL.mdを必ず置きます。公式ドキュメントが示す配置場所は次の4階層です（出典：Claude Code Skills公式ドキュメント、2026年5月時点）。

# 1. Personal（個人用・全プロジェクト共通）
~/.claude/skills/<skill-name>/SKILL.md

# 2. Project（このプロジェクトだけ）
.claude/skills/<skill-name>/SKILL.md

# 3. Plugin（pluginが有効な範囲）
<plugin-name>/skills/<skill-name>/SKILL.md

# 4. Enterprise（managed settings経由・組織全体）
# 詳細はAnthropic公式の Enterprise Managed Settings を参照

優先度はEnterprise > Personal > Project。同名skillが複数階層にあると上位が勝ちます。Plugin skillだけはplugin-name:skill-nameのnamespaceが付くので衝突しません。

1個のskillの内部はこういう構造を取れます（公式の標準例）。

my-skill/
├── SKILL.md           # 必須・主たる手順書
├── reference.md       # 詳細API仕様（必要時だけClaudeが読む）
├── examples.md        # 使用例
├── templates/
│   └── output.md.tmpl # 出力テンプレ
└── scripts/
    └── validate.py    # 実行スクリプト（中身はcontextに入らない）

ポイントはscriptsディレクトリの扱い。Claudeがpython3 scripts/validate.pyと実行したとき、スクリプトのソースコードはコンテキストに入らず、stdout/stderrだけが入ります。重い処理（OCR、画像生成、API呼び出し）はscriptに切り出すと、Claudeに毎回コードを書かせるよりはるかに高速かつ決定的（deterministic）に動作します。

SKILL.md frontmatterの全フィールド

公式仕様（Anthropic Agent Skills + Claude Code拡張）に基づき、Claude Codeで使えるfrontmatterフィールドをまとめます。

---
# === Agent Skills公式仕様 ===
name: my-skill                    # 任意。最大64文字、英小文字+数字+ハイフン、
                                  # "anthropic"/"claude"は予約語で使用不可
description: |                    # 推奨。何をして、いつ使うかを書く。
  社内Slackに日報を送るskill。「日報」「today's report」と言われたら起動。
                                  # description+when_to_useの合計が
                                  # 1,536字でtruncateされるので前半に要点を寄せる

# === Claude Code拡張 ===
when_to_use: |                    # descriptionへの追記。トリガーフレーズや例を書く
  Triggers: "日報書いて", "today's standup",
  "今日やったこと整理して"

argument-hint: "[date]"           # 入力ヒント（オートコンプリート用）
arguments: [date, channel]        # 名前付き引数。$date / $channel で参照可

disable-model-invocation: false   # trueにするとClaudeの自動発動を禁止し、
                                  # ユーザーが /my-skill と打ったときだけ動く
user-invocable: true              # falseにすると /メニューから隠れる（背景知識用）

allowed-tools: Read Grep Bash(git:*)
                                  # このskill発動中だけ権限プロンプトをスキップするツール
model: inherit                    # このskill中だけ使うモデル
effort: high                      # low/medium/high/xhigh/max
context: fork                     # 'fork'でsubagent contextに分岐させる
agent: code-reviewer              # context: fork のときのsubagent type
paths: ["src/**/*.py"]            # 自動発動を特定パスのファイル作業時だけに限定
hooks:                            # このskillライフサイクル限定のhook
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "scripts/audit.sh"
---

# Skill本体（markdown）
ここからClaudeが読む手順書本文。1セッション内で発動中はずっとcontextに残るので、
500行以内・要点だけ・「何をするか」を書く。理由や経緯は別ファイルへ。

必須なのは実は何もないのですが、公式ドキュメントは「descriptionを必ず書け」と強く推奨しています。なぜならClaudeはdescriptionだけを見て「今このskillを発動すべきか」を判断するからです。description=不在 → 自動発動しない → 結局CLAUDE.md相当の運用になり、Skillsの本来の価値が消えます。

Skill discovery：Claudeがどうやってskillを見つけて発動するか

公式ドキュメントが示すフローを、私の200個運用環境での実観測と合わせて整理します。

1. 起動時（startup）：Claude Codeが起動するとき、~/.claude/skills/と.claude/skills/（カレント→ルートまで遡って探索）の全SKILL.mdからfrontmatterだけを読み、system promptに「name + description」のリストを差し込みます。これが1 skillあたり約100トークン。
2. ユーザー入力：ユーザーが「日報書いて」と打つと、Claudeはまずsystem promptのskillリストとマッチング。description: 社内Slackに日報を送る...を見て該当と判断したら、bashで該当ディレクトリのSKILL.md本体をRead。ここでようやくcontext windowに本体が入ります。
3. 参照ファイル：本体に「詳細はreference.mdを参照」と書いてあれば、Claudeが必要に応じてbashでreference.mdをReadします。書いてなければ読まれません。
4. スクリプト実行：本体にscripts/validate.pyとあれば、Claudeがpython3 scripts/validate.pyを実行し、出力だけがcontextに入ります（コードは入らない）。
5. セッション継続中：一度読まれたSKILL.md本体は、そのセッション中はcontextに残り続けます。だから本体は500行以内に抑えるべき、と公式が推奨しているわけです。

もう1つ、Claude Codeにはlive change detectionがあります。~/.claude/skills/配下のSKILL.mdを編集すると、再起動なしで現在のセッションに反映される（v2.1系で確認）。ただし「新しい最上位skillsディレクトリ」を後から作った場合は再起動が必要です。私は最初これでハマって「skillが認識されない」と1時間悩みました。

即コピペ可能なSKILL.mdテンプレート集（Pattern別）

200個運用してきた中で、頻出パターンを5種類に分類できました。それぞれ最小構成のテンプレートを置いておきます。本番運用前に必ず検証環境でテストしてください。

テンプレ1：Reference型（コーディング規約・スタイルガイド）

「規約をClaudeに守らせる」用途。自動発動を期待するのでdescriptionを丁寧に書く。

---
name: api-design-conventions
description: |
  社内APIのRESTful命名・エラーフォーマット・バリデーション規約。
  「APIエンドポイント作って」「ルート追加」「OpenAPI書いて」と言われたら起動。
paths: ["src/api/**/*.py", "src/routes/**/*.ts"]
---

# 社内API設計規約

## 命名
- リソースは複数形（`/users` ✅ / `/user` ❌）
- ネストは2階層まで（`/users/{id}/posts` OK、3階層以上はクエリパラメータに）
- 動詞はパスに入れない（`/users/{id}/activate` ❌ → `PATCH /users/{id}` with `status: active` ✅）

## エラー形式
```json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "メールアドレスの形式が不正です",
    "details": [{"field": "email", "issue": "format"}]
  }
}
```

## バリデーション
- 必ずスキーマライブラリ（Pydantic/Zod）を介す
- 422を返す（400ではない）
- 詳細は `reference.md` を参照

テンプレ2：Task型（デプロイ・送信などの副作用あり）

絶対に勝手に発動させたくない処理。disable-model-invocation: trueでユーザー明示起動のみに。

---
name: deploy-staging
description: ステージング環境にデプロイする。/deploy-staging で明示起動のみ。
disable-model-invocation: true
allowed-tools: Bash(git:*) Bash(npm run *) Bash(vercel:*)
argument-hint: "[branch-name]"
arguments: [branch]
---

# Stagingデプロイ

> 注意: 本番環境ではない。stagingでも実行前にユーザー確認を取ること。

1. 現在のbranchが `$branch` と一致するか確認
2. `npm run test` がGREENか確認（失敗時は即停止）
3. `npm run build` を実行
4. `vercel deploy --target=preview` を実行
5. デプロイURLをユーザーに報告

実行前に必ずユーザーに「stagingに $branch をデプロイします、よろしいですか？」と確認。

テンプレ3：Generator型（コード/ドキュメント自動生成）

具体的な引数を受け取って成果物を生成するタイプ。Pattern A1（プロンプト集）の典型例です。

---
name: prd-writer
description: |
  PRD（プロダクト要求仕様書）を社内テンプレで生成。
  「PRD書いて」「要件定義」「仕様書ドラフト」と言われたら起動。
argument-hint: "[feature-name]"
arguments: [feature]
allowed-tools: Read Write
---

# PRD生成スキル

機能名: $feature

`${CLAUDE_SKILL_DIR}/templates/prd.md.tmpl` を読み込み、以下の項目を埋める：

1. **背景**: なぜ今この機能か（市場/ユーザー/競合の文脈）
2. **ユーザーストーリー**: As a / I want / So that 形式で3つ以上
3. **要件**: Must / Should / Could / Won't (MoSCoW)
4. **計測指標**: 北極星指標 + ガードレール指標（最低3つ）
5. **リスク**: 技術/UX/ビジネスの3観点

埋めたら `docs/prd/$feature.md` に保存。

## 注意
- 数字・期日は「（要確認）」とプレースホルダーで残す。AIが勝手に決めない
- 競合情報は WebSearch で当日取得（古い情報を書かない）

テンプレ4：Subagent fork型（重い処理を別文脈で）

大規模調査・コードレビューなど、メインセッションのcontextを汚したくない処理用。

---
name: codebase-audit
description: |
  コードベース全体のセキュリティ監査。3観点（権限/秘密情報/入力検証）で並列調査。
  「セキュリティ監査して」「全体レビューして」で起動。
context: fork
agent: code-reviewer
effort: high
allowed-tools: Read Grep Glob Bash(rg:*)
---

# 全体セキュリティ監査

forked subagent内で以下を実行：

1. `rg -n "password|secret|api_key" --type py --type ts` でハードコード検知
2. 全エンドポイントの入力バリデーション漏れチェック
3. SQL文字列連結（SQLi疑い）の検知

最後に `audit-report-$(date +%Y%m%d).md` に表形式でまとめる（severity: critical/high/medium/low）。
親セッションには「監査完了。critical N件、high N件、レポートはこのファイル」と1行報告のみ。

テンプレ5：Path-scoped型（特定ファイル群でだけ自動発動）

monorepo・大規模リポで「フロントエンドの規約」「データ層の規約」を分離したいとき。

---
name: react-conventions
description: Reactコンポーネント設計規約。.tsx/.jsxファイル編集時に自動参照。
paths: ["**/*.tsx", "**/*.jsx", "components/**"]
---

# Reactコンポーネント規約

- 1ファイル1コンポーネント
- propsはinterfaceで定義（typeではない）
- ロジックはhooksに分離。コンポーネント本体は60行以内
- styleはCSS Modules or Tailwind（emotion/styled-components禁止）
- テストファイルは同階層 `.test.tsx`

Claude Code / Agent SDK との連携

SkillsはClaude Code（CLI）だけのものではありません。Agent SDK（PythonとTypeScript）からも使えます。ここがエージェント開発実装で大きく効いてきます。

Claude Code側の動作

Claude Codeを起動すると、自動的に~/.claude/skills/と.claude/skills/を走査してskillリストをシステムプロンプトに注入します。CLI操作で/skill-nameと打てば明示起動。何も打たなくてもdescriptionに合致するリクエストが来れば自動発動します。

動作確認のためのコマンド：

# skill一覧（公式CLI機能。Claude Code v2.1+）
claude /skills list

# 特定skillを明示起動
claude
> /my-skill arg1 arg2

Agent SDK側の動作（API経由）

Anthropic公式のSkills APIでは、Pre-builtのpptx/xlsx/docx/pdf skillと、自分でアップロードしたCustom skillの両方を、containerパラメータのskill_idで指定して呼び出します。3つのbeta headerが必要です（公式記載のとおり）。

# Agent SDK / Claude API でskillを使う最小例
# 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。

from anthropic import Anthropic

client = Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    extra_headers={
        "anthropic-beta": "code-execution-2025-08-25,skills-2025-10-02,files-api-2025-04-14"
    },
    tools=[
        {"type": "code_execution_20250825", "name": "code_execution"}
    ],
    container={
        "skills": [
            {"type": "skill", "skill_id": "pptx"},          # Pre-built
            {"type": "skill", "skill_id": "skill_01ABC..."} # Custom uploaded
        ]
    },
    messages=[
        {"role": "user", "content": "添付の資料を10枚のスライドにまとめて"}
    ]
)
print(response.content)

Custom skillを使うフローはこうです：

1. ローカルのmy-skill/ディレクトリをzip化
2. POST /v1/skillsにアップロード → skill_idが返る
3. workspace内のメンバー全員がこのskill_idでリクエスト可

ここで意外と知られていない注意点。Claude API側のSkillsは「ネットワークアクセスなし」が標準です。Code Execution containerで動くため、外部API呼び出しはできません。一方Claude Code側のSkillsはユーザーのマシンで動くのでフルネットワークアクセス可能。同じskillをそのまま両方で使い回す場合、ネットワーク前提の処理（WebFetch、curl）はAPI側で動きません。私もここで一度ハマったので、APIで使う前提のskillは外部依存を持たない設計に分けるのが安全です（公式：Limitations and constraints セクション参照、2026年5月時点）。

社内チームへのskill配布運用：200個運用での学び

社内で20名規模のClaude Code利用者にskillを配布する場合、選択肢は4つです。経験ベースで比較します。

選択肢A: Git private repo + symlink方式（推奨）

# 社内private repoをclone
git clone git@github.com:my-company/claude-skills.git ~/work/claude-skills

# ~/.claude/skills を symlink で繋ぐ
ln -s ~/work/claude-skills/skills ~/.claude/skills

# 各メンバーは git pull で全社skillが更新される
cd ~/work/claude-skills && git pull

これが最も現実的。個人カスタマイズと組織共通の分離もできます（個人用は~/.claude/skills-personal/などに分離してパスを通す）。

選択肢B: Claude Code Plugin方式

Claude Code v2系で公式に追加された機能。plugin.jsonを持つディレクトリにskillsを束ねて配布します。Plugin有効化中だけskillが見える/見えないをON/OFFできるのが利点。Pluginの詳細は公式ドキュメント参照。

選択肢C: Enterprise Managed Settings

Anthropic公式の有償プラン経由。組織全体に強制配布できますが、設定の柔軟性が下がります。100名超の規模で「全員が同じskillセットで作業すべき」案件向け。

選択肢D: rsync/scpで配布

更新追跡が事実上できないので非推奨。一時的なpoc向けです。

配布運用で押さえるべき周辺ツール

200個運用するとskillメタ情報の管理が必要になります。私の手元で運用しているskill-stocktakeというinternal toolは以下をやっています：

1. 命名規則違反検知：「x--format」「koubun*」のような独立スキル新規作成パターンを定期grepで警告（私の運用上、Xポスト構文系の独立skill乱造を3回失敗した経験から導入）
2. 重複description検知：description類似度0.85以上のskillをアラート（Claudeの自動発動が誤る原因）
3. last-modified監査：90日触られてないskillを「死亡疑い」リストへ
4. frontmatter検証：nameのlowercase+hyphen規則・anthropic/claude予約語チェック

公開できる範囲のサンプルとして、最小限のfrontmatter検証スクリプトを置いておきます。

#!/usr/bin/env python3
# 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。
"""skill_lint.py — SKILL.md frontmatter検証"""
import sys, re, yaml
from pathlib import Path

RESERVED = {"anthropic", "claude"}
NAME_RE = re.compile(r"^[a-z0-9-]+$")

def lint(skill_md: Path) -> list[str]:
    errs = []
    text = skill_md.read_text(encoding="utf-8")
    m = re.match(r"^---n(.*?)n---n", text, re.DOTALL)
    if not m:
        return ["frontmatter (---) が存在しない"]
    meta = yaml.safe_load(m.group(1)) or {}

    name = meta.get("name") or skill_md.parent.name
    if not NAME_RE.match(name):
        errs.append(f"name '{name}' は英小文字+数字+ハイフンのみ可")
    if len(name) > 64:
        errs.append(f"name '{name}' が64文字を超える")
    if any(r in name.lower() for r in RESERVED):
        errs.append(f"name '{name}' に予約語(anthropic/claude)が含まれる")

    desc = meta.get("description", "")
    if not desc:
        errs.append("description が空。Claudeが自動発動の判断ができない")
    elif len(desc) > 1024:
        errs.append(f"description が1024字超 ({len(desc)}字)")

    return errs

if __name__ == "__main__":
    root = Path(sys.argv[1] if len(sys.argv) > 1 else "~/.claude/skills").expanduser()
    bad = 0
    for sm in root.rglob("SKILL.md"):
        errs = lint(sm)
        if errs:
            bad += 1
            print(f"n❌ {sm.relative_to(root)}")
            for e in errs:
                print(f"   - {e}")
    print(f"n検証完了。問題のあるskill: {bad}個")

ポイント：

• このスクリプトは公式仕様（name: lowercase+digits+hyphen, max 64; description: max 1024字, 予約語禁止）に準拠しています
• 200個運用環境で実行すると、私の場合は名前のキャメルケース違反・descriptionの空欄が初回で15個ほど出ました
• CIに組み込めば、配布前に弾けます

SKILL.md設計チェックリスト（公開前に必ず通す）

200個運用する中で出来上がった、私のチームで実際に使っているチェックリストです。新規skillをコミットする前に通します。

1. name：英小文字+数字+ハイフン、64字以内、anthropic/claude予約語不使用
2. description：1,024字以内、「何を」+「いつ使うか」+「トリガーフレーズ3個以上」を含む
3. 本体：500行以内、命令形で書く（経緯・背景は別ファイル）
4. 副作用ある場合：disable-model-invocation: true必須
5. allowed-tools：必要最小限のツールだけ。Bash(*)は基本NG、特定コマンド限定でBash(git:*)のように絞る
6. scripts/：重い処理・決定的処理はscriptに切り出してclaudeに毎回コードを書かせない
7. reference.md：500行超の詳細仕様は本体から分離してSKILL.mdから参照する
8. テスト：description文だけ読んで、第三者が「いつ起動するskillか」を10秒以内に判別できるか
9. 命名空間：プロジェクト固有ならuravation-*のように接頭辞を付けてpersonal側との衝突を回避
10. 更新追跡：日付・変更履歴を本体末尾のコメントに残す（Plug配布時の差分が分かる）

このチェックリスト自体もskill化すれば、Claude Codeで「新しいskill書きたい」と言ったときに自動でこの手順を踏ませることができます（meta-skill的な使い方）。

【要注意】よくある失敗パターンと回避策

失敗1：descriptionに「何をするか」しか書かない

❌ description: Slackに通知を送る

⭕ description: 社内Slack #dev チャンネルに障害通知を送る。「Slack通知」「障害連絡」「インシデント報告」と言われたら起動。

Claudeはdescriptionで「いつ発動すべきか」を判断します。「何をするか」だけだと類似機能が複数あるとき選べません。トリガーフレーズ（「〜と言われたら」）を3〜5個書くのが効きます。

失敗2：SKILL.md本体を1,000行で書く

本体は発動中ずっとcontextに残ります。1セッションで複数skillが発動するなら、それぞれ500行を超えるとあっという間に20,000トークンが死蔵されます。公式の推奨どおり500行以内に抑えて、詳細はreference.mdに逃がすこと。私は当初2,000行のskillを書いていて、Claude Codeの応答が明らかに遅くなりました。

失敗3：disable-model-invocationを使わずデプロイskillを作る

「コードがREADYな雰囲気」だけでClaudeが/deployを発動するリスクがあります。デプロイ・送信・課金が走るskillは必ずdisable-model-invocation: true。これは公式ドキュメントも明示的に推奨しています（「You don’t want Claude deciding to deploy because your code looks ready.」）。

失敗4：同名skillをproject/personal両方に作って挙動が分からなくなる

優先度は Enterprise > Personal > Project。Personal側が勝ちます。プロジェクト固有のオーバーライドのつもりが、Personal側が消費されて気付かないパターン。名前空間をプロジェクト名でprefix（例：uravation-deploy）すれば回避できます。Plugin skillに移行するのも有効です。

失敗5：scripts/内のスクリプトを毎回claudeにコードで書かせる

これは私が一番損をしていたパターン。たとえば「画像生成失敗時にPILで代替画像を作る」処理を毎回claudeにPythonコードを書かせると、1回50〜80行のコードがcontextに乗ります。これをscripts/fallback_image.pyとして固定スクリプト化すると、claudeはpython3 scripts/fallback_image.py "プロンプト" -o out.pngと打つだけで、出力1行しかcontextに入りません。決定的（deterministic）に同じ動きをすべき処理は必ずscript化。これだけで10セッション分のトークンを節約できます。

注意：scriptに外部API呼び出しを書く場合、Claude API経由のSkill実行ではネットワークアクセスが原則不可なので、Claude Code側専用と割り切るか、API側用に別skillを切るのが安全です。

実体験：4日で社内Skill運用を始めた話

個人エピソードを3つほど共有します。同じ規模感のチームで導入する方の参考になれば。

エピソード1：CLAUDE.mdが4,200字を超えた日

2026年初頭、uravation-newwebsiteのリポジトリでCLAUDE.mdが4,200字（フルテキスト）を超えました。ルール追加のたびに少しずつ膨らんだ結果です。あるとき「画像生成のルール」セクションが800字を超え、Claudeの応答に明らかな遅延が出始めました。そのタイミングでSkillsの存在を本格的に意識し、画像生成・PR TIMES入稿・記事執筆系を順次Skillsに切り出しました。結果、CLAUDE.mdは1,800字まで縮み、毎セッションの起動が体感1.5秒ほど早くなりました（測定値ではないですが、明らかな差を感じるレベル）。

エピソード2：Xポスト構文スキルを12個作って統合した失敗

これは私の明確な失敗事例です。Xポスト構文（march-koubun、yueki-koubun、sokuhou-koubun…）を独立skillとして12個作ったところ、Claudeのskill discovery精度が落ちて「どの構文を発動すべきか」を誤るようになりました。原因はdescription類似度が高すぎたこと。「march調のXポストを書く」「yueki調のXポストを書く」が判別できなくなったのです。結局すべてsuguru-x-voiceという1つのskillに統合し、構文選択は本体内のサブ手順として書く方式に変更。同じ失敗を午後にもう一度繰り返して、さらに6個独立skill化→統合、を経験しました。「同種類のタスクで複数バリアントがある場合は1 skillの中で分岐させる」のが原則です。

エピソード3：skill-stocktake内製ツールが救った命名規則違反

200個超えてから、上記のような独立skill乱造を機械検知するためにaudit_anti_pattern.pyを社内で書きました。x-*-format・*koubun*のような命名パターンを毎週検知してSlackに通知します。これを動かし始めてから、新規skillの命名段階で違反を弾けるようになりました。launchdで週次実行に登録しているので、増え続ける運用でも管理コストが線形に上がらない構成になっています。

Q&A：よくある質問

Q1. Skillsは本当にCLAUDE.mdより安いのか？

はい。CLAUDE.mdは全行が毎ターンcontextに乗ります。Skillsはfrontmatterだけが乗り、本体は発動時のみ。私の手元の計測では、200個のskillで起動時の追加トークンは約20,000（100 tokens × 200）でしたが、これは全skillの本体合計（概算50万トークン超）と比べれば1/25です。

Q2. 無料プランで使えますか？

Claude Code側のCustom Skillsはローカルファイルなので、Claude Codeが使えるプランであれば使えます（Pro/Max/Team/Enterprise）。Claude API経由のCustom Skill upload・claude.aiでのCustom skillはプランによって制約があるため、Anthropic公式の最新ページで確認してください。2026年5月時点の最新情報は公式の「Agent Skills概要」を参照。

Q3. Skills内のscriptsはどんな言語が動きますか？

Claude Code側はユーザーのマシン上で動くので、Pythonでも、Node.jsでも、シェルでもなんでも動きます。Claude API側はCode Execution containerに事前インストールされたパッケージのみ。新規パッケージのpip installは（記事執筆時点では）できません。詳細は公式のCode Executionツール仕様を参照。

Q4. Anthropicの予約語「anthropic」「claude」がnameに使えないのは知ってますが、descriptionに入れるのは？

公式ドキュメントは「name と description は XMLタグを含めてはならない」と明示。予約語チェックはnameのみが対象です。ただしdescriptionに「claudeに依頼するときは…」のような書き方は混乱を招くので避けたほうが無難です。

Q5. Plugin形式とPersonal形式、最終的にどちらに寄せるべき？

社内配布前提ならPlugin。個人運用はPersonal。混在もOK。Pluginはon/off切り替えができ、namespaceで衝突回避できるのが利点。社内配布前提でも、開発中の検証はPersonalで回して、固まったらPluginにmergeする2段階運用が現実的でした。

関連記事（合わせて読みたい）

Skillsを実装に活かす過程で、以下の3記事が前提知識として役立ちます。

• Claude Agent SDK (Python) で自律エージェントを組む実装ガイド2026 — Agent SDK経由でCustom Skillをworkflowに組み込む実装パターン。本記事のテンプレ4（Subagent fork型）はAgent SDK側でも応用可能
• MCP Tool Annotationsで安全な権限設計を作る方法 — Skillsのallowed-toolsと組み合わせる際のtool annotationの考え方。デプロイ系skillの設計で特に有用
• AIエージェント向けプロンプト設計パターン完全ガイド — SKILL.md本体に書くプロンプトの設計指針。本記事ではSkillsの「型」を扱ったが、中身のプロンプトはこちらが詳しい

まとめ：今日から始める3つのアクション

Claude Skillsは「使うときだけロードされる、ファイルシステムベースのモジュール拡張」です。CLAUDE.mdに溜まりすぎた手順をSkillsに移すと、context消費が劇的に減って、200個規模でも回ります。

今日できる3アクション：

1. 5分：~/.claude/skills/my-first-skill/SKILL.mdを1個作ってdescriptionに「いつ起動するか」を3個書く。Claude Codeを再起動して/my-first-skillで発動確認
2. 30分：CLAUDE.mdから「手順」っぽいセクションを2つSkillに切り出す。本体は500行以内、詳細はreference.mdに逃がす設計を試す
3. 1日：社内のClaude Code利用者が3人以上いるなら、private repoで共有skillリポを作り、symlinkで配布する仕組みを試す。skill_lint.pyを使って初回検証も実行

著者プロフィール

佐藤傑（さとう・すぐる）。株式会社Uravation代表取締役。Anthropic Claude / Claude Code を仕事の8割で運用し、手元には200個以上のCustom Skillsを実装。Xアカウント@SuguruKun_ai（フォロワー約10万人）。著書『AIエージェント仕事術』。AIエージェント導入支援はUravation公式まで。

参考出典

• Anthropic公式「Agent Skills 概要」 — platform.claude.com/docs/en/agents-and-tools/agent-skills/overview（2026年5月時点）
• Claude Code公式「Extend Claude with skills」 — code.claude.com/docs/en/skills（2026年5月時点）
• Anthropic公式「Use Skills with the Claude API」 — platform.claude.com/docs/en/build-with-claude/skills-guide（2026年5月時点）
• Anthropic Engineering Blog「Equipping agents for the real world with Agent Skills」 — anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills
• Anthropic公式「Skills authoring best practices」 — platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices