Claude Code Skills設計の4原則：15件の実運用から見えた「スケールするSkills」の作り方

Claude Code Skillsの導入事例や基本的なチュートリアルは増えてきました。しかし、「どのような設計思想でSkillsを構築すべきか」という一歩踏み込んだ議論はまだ少ないのが現状です。

特に複数のSkillsを運用するようになると、こんな課題に直面します：

これらの問題を解決するための設計指針として、15以上のSkillsを実運用してきた知見から抽出された**4つの原則**が提示されています。

1. 段階的開示（Progressive Disclosure）

段階的開示とは、「必要な情報を必要なタイミングで展開する」という設計思想です。これはUI/UXデザインの基本原則ですが、Claude Code Skillsにおいても極めて有効です。

**具体的には：**

これにより、Claudeがどのスキルを使うべきか判断する際のノイズを減らせます。

2. コンテキスト2%ルール

最も定量的で実践的な指針が、この「2%ルール」です。これは**Skillsのdescriptionは、全体のコンテキストウィンドウの2%以内に収めるべき**という基準です。

Claude 3.5 Sonnetの場合、200Kトークンのコンテキストウィンドウを持つため、2%は約4,000トークン。10個のSkillsを運用するなら、1つあたり400トークン程度が目安となります。

この基準を設けることで：

3. 3層構造（SKILL.md / agents / references）

情報をどう分離するかの構造設計として、3層アーキテクチャが提唱されています：

**SKILL.md層：** Skillの概要と基本的な振る舞いを定義

**agents層：** 具体的な実行ロジックやワークフロー

**references層：** 参照資料、ドキュメント、サンプルコード

この分離により、コンテキストの粒度をコントロールでき、必要に応じて適切な情報だけをロードできます。

4. Iron Law + 合理化防止

Iron Law（鉄の掟）とは、**絶対に守るべき制約条件**をSkillsに組み込むことです。さらに重要なのが「合理化防止」のメカニズムです。

AIは指示を「解釈」して「最適化」しようとしますが、これが意図しない動作を引き起こすことがあります。そのため：

ChatGPTのGPTsと比較して見えるClaude Code Skillsの特性

ChatGPTのカスタムGPTs（GPTs）と比較すると、Claude Code Skillsには明確な違いがあります。

GPTsは「キャラクター設定」や「会話スタイル」に重きを置く傾向がありますが、Claude Code Skillsは**開発ワークフローへの統合**を前提としています。そのため、コンテキスト管理とトークン効率がより重要になります。

2%ルールのような定量的基準が生まれた背景には、こうした「実運用での効率性」への要求があります。GPTsでは「どれだけ詳しく指示するか」が重視されがちですが、Skillsでは「いかに無駄なく情報を提供するか」が成否を分けます。

メリットと注意点の両面分析

**メリット：**

**注意点：**

特に注意すべきは、**過度な最適化による可読性の低下**です。トークン削減に夢中になるあまり、人間が読んでも理解できないSkillsになっては本末転倒です。

どんな人・場面に向いているか

この設計思想が特に有効なのは：

逆に、単発の個人用Skillsや、試行錯誤段階のプロトタイプには、ここまで厳格な設計は不要かもしれません。ただし、将来的にスケールさせる予定があるなら、初期から意識しておくべき原則です。

アクション1：既存Skillsの「description監査」を実施する

今あるSkillsのdescriptionのトークン数を測定してみましょう。Claude APIのトークンカウンターや、簡易的には文字数÷2で概算できます。2%ルールに照らして、削れる部分がないか見直してください。

**チェックポイント：**

アクション2：3層構造のテンプレートを作る

新規Skillsを作る際のテンプレートを用意しましょう。

# SKILL.md
## 概要
[このSkillが何をするか、1〜2行]

## 使用タイミング
[いつ使うべきか]

---
# agents/
[具体的な実行手順]

---
# references/
[参考資料、サンプル]

このテンプレートに従うだけで、情報の分離が自然に進みます。

アクション3：「合理化防止チェックリスト」を導入する

Skillsの末尾に、こんなセクションを追加してみてください：

## 必須チェック項目（絶対に省略しないこと）
- [ ] ファイル保存前に構文チェックを実行したか
- [ ] テストケースを3件以上実行したか
- [ ] 変更内容をログに記録したか

## 禁止事項（理由付き）
- エラーを無視してはいけない（理由：データ整合性が崩れる）
- 既存のコメントを削除してはいけない（理由：意図が失われる）

AIに自己検証させることで、品質の底上げができます。

---

この情報は @ヨコタナオヤ｜correlate design さんの投稿を参考にしています。