Claude Code Skills 2.0を実戦投入してわかった設計パターンと落とし穴

Claude Codeの設定ファイル、何が何だかわからなくなっていませんか。

CLAUDE.md、Rules、Commands、Skills、Agents、MCP、Plugins。公式ドキュメントを読んでも「で、結局どこに何を書けばいいの？」がはっきりしない。自分も最初はCLAUDE.mdにルールもワークフローも全部詰め込んで、コンテキストが溢れて前半の指示を忘れられる、という事故を繰り返していました。

2025年5月にClaude Codeへ導入された Skills 2.0 は、従来のカスタムスラッシュコマンドの大幅な拡張です。スキルを独立したコンテキストで実行する context: fork、使えるツールを制限する allowed-tools、モデルを指定する model といった設定が追加され、「AIへの指示をどう構造化するか」という設計の幅が広がりました。

この記事では、Skills 2.0を含む設定レイヤーの使い分けパターンと、運用で踏んだ落とし穴を共有します。

6つのレイヤーの役割整理

まず全体像。Claude Codeの設定は6つのレイヤーに分かれます。

各レイヤーの詳細は公式ドキュメントを参照してください。

• Skills（スラッシュコマンド）
• Subagents
• MCP連携

この整理にたどり着くまでに時間がかかりました。最初はRulesとSkillsの境界が曖昧で、「コーディング規約」も「PRレビューの手順」も、同じCLAUDE.mdに書いていたからです。

判断基準はシンプルで、実行を伴うかどうか。

• 実行を伴わない原則・判断基準 → Rules（「こう振る舞ってね」）
• 実行を伴うワークフロー → Commands or Skills（「これをやってね」）

実際にどう使っているか

抽象的な話だけだと伝わらないので、自分の運用を具体的に見せます。

メルマガ自動トリアージ

/digest-newsletter というコマンドで、Gmailの未読メルマガを一括処理しています。

1. Gmail連携で未読メールを取得
2. 件名と冒頭テキストで簡易トリアージ
3. 重要メールは本文精読 + リンク先の内容も取得
4. 🔴必読 / 🟡ネタストック / ⚪スキップ に分類
5. Obsidianにダイジェストノートを自動生成

20通のメルマガが、リンク先の深掘り含めて1回の実行でダイジェストになります。毎朝のメール処理が、コマンド1つで終わる世界です。

日次アナリティクス

運用中の複数サイトのGA4とGoogle Search Consoleのデータを毎日取得して、週次比較のトレンド分析をObsidianに保存しています。これも1コマンド。「先週と比べてどのページのアクセスが伸びたか」が、データを見に行かなくても手元に届きます。

Zettelkasten管理

Obsidian Vaultの知識管理をスキルに任せています。FleetingNote（走り書きメモ）→ LiteratureNote（要約）→ PermanentNote（自分の考え）という3段階の知識変換プロセスを、スキルが支援してくれます。

たとえば技術記事を読んで走り書きのメモを残したとします。そこからスキルを実行すると、まず記事の要点を構造化した要約ノートに変換します。さらに「この内容は、以前書いた〇〇のノートと関連がある」と既存の知識との接続を提案してくれます。自分で考えて書く部分は残しつつ、整理と発見の手間を減らせるわけです。

設計で工夫すべき3つのポイント

ここからが本題です。スキルを作ること自体は簡単ですが、「うまく動く設計」にするにはコツがあります。

1. CLAUDE.mdは目次に徹する

最初にやりがちなのが、CLAUDE.mdにコーディング規約もワークフローも判断基準も全部書くことです。

CLAUDE.mdはClaude Codeが会話の最初に毎回読み込むファイルです。人間でいえば、会議のたびに最初に読み上げる資料のようなもの。ここが大きいと、AIの「記憶容量」（コンテキストウィンドウ）を最初から圧迫して、長い会話の後半で前半の指示を忘れる原因になります。

対策は明確で、CLAUDE.mdには具体的な内容を書かないこと。ルールは .claude/rules/ に分離して、CLAUDE.mdには「詳しくはこちらを見て」というポインタだけ置きます。必要なときだけ参照される形にすれば、記憶容量を節約できます。

2. context: fork でコンテキストを分離する

Skills 2.0で追加された context: fork は、スキルをメインの会話とは別の記憶空間で実行する機能です。スキルの内容がサブエージェント（別働隊）へのプロンプトとなり、メインの会話の記憶容量を消費しません。処理が終わると、結果だけがメインに返ってきます。

これが効くのは、大量のデータを処理するスキルです。たとえばメルマガ20通を処理すると、メール本文やリンク先のコンテンツで記憶容量が膨大になります。context: fork なしだと、後半のメールを処理する頃には前半の指示を忘れている、ということが実際に起きます。

ただし注意点があります。context: fork はスキル内に具体的なタスク指示がある場合にのみ意味があります。「こういう方針で動いて」というガイドラインだけを書いたスキルをforkしても、別働隊は何をすべきかわからず空振りします。

3. allowed-tools でツールを制限する

スキルにはどのツールを使えるかを制限する allowed-tools という設定があります。

たとえば調査系のスキルにファイル編集やコマンド実行の権限まで与えると、意図しない変更をしてしまうリスクがあります。「読み取りと検索だけ」に制限すれば、安全に調査だけをさせられます。

---
name: seo-analyzer
description: サイトのSEO状態を分析する
allowed-tools: ["Read", "Grep", "WebFetch"]
---

目的に合わせて最小限の権限だけを許可する。これはAIに限らず、権限管理の基本原則と同じです。

まず何から始めるか

もしCLAUDE.mdに何でも書いている状態なら、最初の一歩はこれです。

CLAUDE.mdに書いているワークフローを1つ、Skillsに切り出す。

最小限のSKILL.mdはこれだけです。

---
name: my-first-skill
description: 何をするスキルかを具体的に書く
---

ここにワークフローの手順を書く

これを .claude/skills/my-first-skill/SKILL.md に置くだけで、/my-first-skill として呼び出せるようになります。

慣れてきたら context: fork を追加して記憶の分離を試す。allowed-tools で権限を制限する。段階的に育てていけばいいと思います。

AIエージェントの設計・運用についてのご相談は、お問い合わせフォームからお気軽にどうぞ。