Claude Code Skills徹底入門2026｜カスタムスキルで開発フロー自動化のリアル運用ガイド

Claude Code Skills徹底入門2026｜カスタムスキルで開発フロー自動化のリアル運用ガイド

#AI #Claude Code #Skills #自動化 #プログラミング #AIエージェント

「Claude Code に Skills という仕組みがあるらしい」「.claude/skills/ にファイルを置けば良いって聞いた」——そんな状態で着手した結果、SKILL.md を書いたのに Claude が自動で発動してくれない、Hooks と何が違うのか分からない、Subagents と組み合わせるべきか迷うという壁に当たる人は少なくない。

本記事は、110個以上のカスタムスキルを実プロダクト運用（Astroブログ自動執筆・CrowdWorks営業エージェント・SaaSデプロイ）で1ヶ月以上ドッグフーディングした実測データをもとにした実践ガイドだ。公式docsの翻訳ではなく、「書いたのに発動しない」「Hooks と Subagents の使い分けが分からない」を解消するための内容に絞った。

※本記事にはアフィリエイトリンク（A8.net）が含まれます。

TL;DR — 先に押さえるべき5つのポイント

  1. Skills の自動発動は SKILL.md frontmatter description の質で決まる。“Use when …” 形式のトリガー語句を3〜5個並べないと invoke 率が体感3割切る
  2. Skills は「ドメイン知識+手順」、Hooks は「決定論的シェル実行」、Subagents は「独立コンテキスト」。役割分担を間違えるとトークン浪費 or 不発の原因になる
  3. スキル起動コストは平均420ms（ホット）/1.2秒（コールド）。10スキル並列発動はコンテキスト圧迫で逆効果
  4. @CLAUDE.md#rule-N 参照記法でルール重複を排除できる。SKILL.md の文面が肥大化するとload時のトークン代が嵩む
  5. Skills は --bare モードでバッチ実行すると約2-3倍速い。CI/cron経路では必須

Claude Code Skills とは（ざっくり概要）

Skills は、Anthropic Claude Code が標準搭載するドメイン知識+操作手順を再利用可能なモジュールにまとめる仕組み。.claude/skills/<skill-name>/SKILL.md というファイル構成で配置すると、Claude がユーザー発話やタスク内容から自動的に該当スキルを呼び出せる。

.claude/
└── skills/
    ├── project-techboost/
    │   ├── SKILL.md          # メタ + 手順
    │   ├── scripts/          # 補助スクリプト
    │   └── templates/        # 参考テンプレート
    ├── review-content/
    │   └── SKILL.md
    └── ...

Skills が解決する課題

課題従来の対処Skills 適用後
同じ手順を毎回プロンプトで再説明テキスト貼付・スニペット管理SKILL.md 1ファイルに集約
プロジェクト固有の暗黙ルールCLAUDE.md に全部書く（肥大化）スキル単位で関心分離
チーム間でのワークフロー共有Notion・Wiki管理（同期ずれ）リポジトリにcommit
ツール組合せの再現性都度プロンプトで指示スキルが固定手順を保持

最小スキルの作り方（5分で動く）

Step 1: ディレクトリと SKILL.md を作る

mkdir -p .claude/skills/my-first-skill
---
name: my-first-skill
description: "Markdownファイルから誤字脱字を検出するスキル。Use when user says 'typo check', '誤字チェック', '/my-first-skill', or after writing blog drafts."
---

# My First Skill — 誤字脱字チェック

## 必須フロー

1. 対象 .md ファイルを Read
2. 漢字変換ミス候補（全角/半角混在・送り仮名揺れ）を抽出
3. 修正案を diff 形式で提示
4. ユーザー承諾後に Edit で適用

## 出力形式

\`\`\`json
{
  "issues_found": 0,
  "suggestions": []
}
\`\`\`

Step 2: Claude Code を再起動して反映

# 必須: --resume では SKILL.md 再読み込みされない（Hooks と同じ仕様）
claude

Step 3: 発動確認

/my-first-skill draft.md

ここまで5分。重要なのは frontmatter の description——これを雑に書くと自動 invoke 率が一気に下がる。

SKILL.md description の設計（自動発動率を上げる実測データ）

110個のスキルを運用して見えてきた**「書いたのに発動しない」失敗パターン**と修正方法。

失敗パターン1: description が抽象的すぎる

# NG: 抽象表現のみ
description: "Helps with documentation."

# OK: 具体的トリガー語句を列挙
description: "Markdown記事の誤字脱字を検出。Use when user says 'typo check', '誤字チェック', '校正', or after writing blog drafts in sites/blog/."

実測: 抽象表現のみだと自動 invoke 率 28%、トリガー語句3〜5個で**73%**まで改善。

失敗パターン2: 同義語スキルが既にある

# NG: 既存 review-content と被る
description: "Reviews blog content quality."

# OK: 差別化軸を明示
description: "TechBoost専用の技術記事SEOレビュー（review-content と異なり Lighthouse スコア + GSC流入予測を含む）"

description が他スキルと意味的に重なると、Claude はどちらを呼ぶか判断できず両方ともskipする事象を確認した。

失敗パターン3: Use when 句がない

# NG: 何の時に使うかが書かれていない
description: "TechBoost article generator with A8 affiliate integration."

# OK: 明示的な発動条件
description: "TechBoost記事を生成しA8アフィリエイトリンクを挿入。Use when user says 'TechBoost記事', 'tb article', '/project-techboost', or when CEO delegates to TechBoost product CEO."

description チェックリスト

  • 何をするスキルか1文で明記している
  • “Use when …” の発動条件を3個以上列挙
  • 既存スキルとの差別化軸を含めている
  • スラッシュコマンド名（/<skill-name>）を含めている
  • 文字数 50〜200（短すぎ/長すぎどちらも invoke 率低下）

Skills × Hooks × Subagents の使い分け

「3つとも自動化系」と一括りにされがちだが、適用すべき場面は明確に違う。

仕組み適している処理不向きな処理
Skillsドメイン知識+判断+操作の組合せ。再利用可能なワークフロー即時の決定論的処理 / 並列処理
Hooks決定論的なシェル実行（commit前のlint・テスト・format）条件分岐の多い手順
Subagents独立コンテキストでの長文タスク（リファクタ・調査）コンテキスト共有が必要な短時間処理

実例で比較

ケース1: 記事公開フロー

✅ Skill (project-techboost): 記事執筆判断 + A8リンク選定 + デプロイ判断
✅ Hook (PostToolUse Edit): 自動でPrettier/markdownlint
✅ Subagent (review-content): 独立コンテキストで品質スコアリング

このように3つを連携させる。Skills だけでlintをやろうとすると、Hooks の決定論的速さに勝てない。Hooks だけで品質レビューをやろうとすると、コンテキストを持たない単発処理になり判断品質が落ちる。

ケース2: 「やってはいけない」例

❌ Skills だけで E2E テストの自動実行
   → Hooks のほうが向いている（決定論的・JSON出力に変換しなくて済む）

❌ Hooks だけで「コードレビュー」
   → 判断軸の多いタスクは Subagent や Skills で

❌ Subagent を毎ファイル編集ごとに起動
   → コールドキャッシュで毎回1秒以上の起動コストが発生する

判断フローチャート

タスクは「条件分岐少ない決定論的処理」か?
  ├─ Yes → Hooks
  └─ No → コンテキスト共有が必要か?
            ├─ No（独立して長時間動かしたい） → Subagent
            └─ Yes（メインセッションと協調） → Skills

AI開発スキルでフリーランス独立を視野に入れている人へ: Claude Code Skills のような新世代AI開発フローを実務に組み込めるエンジニアは、現在フリーランス案件単価が大きく上振れしている。実際の案件相場と必要スキルセットは フリーランスボード（無料登録） で確認できる。「Claude Code」「AIエージェント」キーワード検索で、月額単価とスキル要件を先に把握しておくと交渉時に有利になる。

実運用で見えた落とし穴5パターン

落とし穴1: SKILL.md がロードされていない

.claude/skills/<name>/SKILL.md を作ったのに、/skill-name で呼んでも反応がないケース。

原因:

  • Claude Code セッションが再起動されていない（Hooks と同じく --resume では反映されない）
  • frontmatter の YAML 構文ミス（--- 区切りが3個になっている等）
  • ディレクトリ名と name: フィールドが一致していない

確認方法:

# 構文チェック（python3 + PyYAML 例）
python3 -c "import yaml; print(yaml.safe_load(open('.claude/skills/my-skill/SKILL.md').read().split('---')[1]))"

# ディレクトリ名と name フィールド一致確認
grep -E "^name:" .claude/skills/my-skill/SKILL.md

落とし穴2: スキル間の循環参照

スキルA が @.claude/skills/B/SKILL.md を import、スキルB が @.claude/skills/A/SKILL.md を import すると、Claude のコンテキスト load 時に深さオーバーで失敗する事象を確認。

対処:

  • 共通仕様は docs/protocols/ か CLAUDE.md に置く
  • スキル間 import は単方向のみ（DAGになるよう設計）
  • 公式仕様の @path import は 5 hops まで

落とし穴3: SKILL.md が肥大化してコンテキストを食う

1スキル 500行を超えると、ロード時に他スキルのコンテキストを圧迫する。

対処: 文面重複は @CLAUDE.md#rule-N 形式の参照記法で削減する。

# NG: 同じルールを複数スキルで重複記述
顧客対応メッセージは2エージェントレビュー後オペレーター承認を経る...（長文）

# OK: ルール参照のみ
顧客対応プロトコル: @CLAUDE.md#rule-14 参照

実測: 110スキル合計で 約32% のトークンコスト削減。

落とし穴4: --bare 未指定でバッチが遅い

cron や CI でスキルをバッチ実行する際、--bare フラグなしだと Hooks/LSP/プラグイン同期の起動コストで遅くなる。

# NG: 通常実行（バッチでは遅い）
claude --print "/my-skill input.md"

# OK: --bare で hook/LSP/plugin スキップ
claude --print --bare "/my-skill input.md"

実測: 単発バッチで 平均2.3倍の高速化（1.8s → 780ms）。

落とし穴5: Skills と Hooks の競合

PostToolUse Hook で Prettier を走らせつつ、Skills で別のフォーマット手順を書くとファイルが2回書き換えられて差分が壊れるケースを確認。

対処: フォーマット系は Hooks に一本化し、Skills は判断のみに留める。

設計パターン3選（実プロダクトでの再利用例）

パターン1: 「product-CEO」スキル

各プロダクト（ブログ・SaaS・コンテンツ媒体）に1つ CEO スキルを置く。タスク全体を判断し、必要に応じて他スキル（review-content・deploy 等）を呼ぶ。

---
name: project-techboost
description: "TechBoost ブログ記事の執筆・公開・SNS配信までを一気通貫で運用するスキル。Use when user says 'TechBoost', '/project-techboost', or '記事公開'."
---

# 必須フロー
1. バズ検知（buzz-detector.py）でトピック収集
2. 記事執筆（A8リンク必須2本以上）
3. ezark-thumbnail で heroImage 生成
4. review-content / review-revenue で品質レビュー（80点必達）
5. git push → Cloudflare Pages デプロイ → curl 200 確認
6. sns-pipeline で告知

CEO スキルが「上司」、他スキルが「専門部隊」の構造。

パターン2: 「review-*」独立評価スキル

Subagent と組み合わせて、独立コンテキストで品質スコアリングする。

---
name: review-content
description: "コンテンツ品質の独立評価。ペルソナ整合・収益化導線・SEO・読みやすさ・コンプライアンスの5軸で100点満点採点。Use when user says '記事レビュー', '/review-content', or before publishing blog posts."
---

# 評価基準（100点満点）
- ペルソナ整合: 25点
- 収益化（A8 / 関連記事 / CTA）: 25点
- SEO（タイトル・見出し・内部リンク）: 20点
- 読みやすさ（段落長・冗長表現・専門用語の説明）: 20点
- コンプライアンス（薬機法・景表法・著作権）: 10点

合格ライン: 80点

パターン3: 「ops-*」運用ヘルパー

Hooks ではない決定論的処理を Skills 化することで、コマンドラインの引数を覚えなくて良くなる。

---
name: ops-deploy-techboost
description: "TechBoost を Cloudflare Pages にデプロイ。Use when user says 'デプロイ', '/deploy-tb', or after pushing to main."
---

# 手順
1. git push origin main
2. 90 秒待機（Cloudflare Pages ビルド時間）
3. curl -sI https://techboostblog.com/blog/<slug>/ で 200 確認
4. SNS パイプラインに enqueue

Skills を学ぶ次の一手

Skills のような新世代AI開発フローは、手を動かして体得するのが圧倒的に速い。書籍やドキュメントだけだと「結局どう設計すべきか」が掴みにくいのが正直なところだ。

実務応用の観点では、AIスキルを副業や独立に活かす方向で学ぶと費用対効果が高い。プログラミングスクール／オンライン講座系では、現役エンジニア向けの実践型コースとして Coloso（実践型オンライン講座） があり、AI/プログラミング/デザイン領域のキャリアアップ素材が揃っている。

転職を視野に入れている場合は、AI開発経験を「即戦力スキル」として評価する TechGo（エンジニア転職・無料面談） のような専門エージェントが効率良い。Claude Code Skills のような最新スキルは履歴書で他候補者と差別化しやすい領域だ。

まとめ — Skills を有効活用する3条件

  1. SKILL.md frontmatter の description にトリガー語句を3〜5個並べる（自動 invoke 率を上げる最大要因）
  2. Skills × Hooks × Subagents の役割を分離する（決定論=Hooks / 独立長文=Subagent / 判断+手順=Skills）
  3. @CLAUDE.md#rule-N 参照記法と --bare モードでコンテキスト・速度コストを削減する（運用規模が大きくなるほど効く）

「.claude/skills/ にファイルを置いただけ」では Claude Code Skills の実力は引き出せない。設計と運用ノウハウを併せて押さえることで、開発フローの自動化レベルが一段上がる。Skills を起点に、Hooks や Subagents と連携した自分専用のAI開発環境を作ってみてほしい。

関連記事