はじめに
2026年3月現在、Claude Code Skillsに関するはてなブックマークが爆発的に伸びている。クラスメソッドの入門記事が783users、Anthropic公式講座の解説が763users、チーム展開の課題に関する記事が74users——Skillsは今週最も注目された開発トピックである。
本記事では、公式ドキュメントや公開されている実践記事に加え、筆者自身の運用経験をもとに「Skills設計パターン集」としてまとめる。入門レベルの紹介は既に良い記事が揃っているため、本記事では設計と運用にフォーカスする。
Skillsの基本概念
Skillsとは何か
Skillsは、Claude Codeに「特定の仕事の進め方」を教えるための仕組みである。ポータブルな専門知識のバンドルと考えるとわかりやすい。
構造はシンプルで、フォルダ1つに必要なファイルをまとめるだけである。
my-skill/
├── SKILL.md # 必須: 指示とメタデータ
├── scripts/ # 任意: 自動化スクリプト
├── references/ # 任意: 参考資料
└── assets/ # 任意: テンプレート等
Progressive Disclosure — コンテキスト効率の要
Skillsの設計で最も重要な概念が**Progressive Disclosure（段階的開示）**である。
Claude Codeは以下の順序でSkillの情報を読み込む。
- Skill名と
descriptionだけを確認する（トリガー判定） - 関連するSKILL.mdの本文をロードする（実行指示）
- 必要なときだけ
references/内のファイルにアクセスする（補足情報）
この設計により、コンテキストウィンドウを無駄に消費しない。20個のSkillがインストールされていても、実際にロードされるのは1〜2個だけで済む。
CLAUDE.mdとの使い分け
| 観点 | Skills | CLAUDE.md |
|---|---|---|
| 目的 | 特定タスクの実行手順 | プロジェクト全体の文脈・規約 |
| スコープ | 必要なときだけロード | 常にロードされる |
| 可搬性 | プロジェクト横断で再利用可能 | リポジトリ固有 |
| 適した内容 | ワークフロー、テンプレート、自動化 | コーディング規約、環境設定、チーム方針 |
判断基準は単純で、「常に適用すべきルール」はCLAUDE.md、「特定の作業のときだけ必要な手順」はSkillsに書く。
Skills設計パターン集
実務で効果の高かったパターンを紹介する。
パターン1: ワークフロー自動化型
定型作業の手順をSkillにまとめるパターン。最も基本的で、効果も実感しやすい。
---
name: write-draft
description: 記事の下書きを生成する必要があるとき。「記事を書いて」「下書きして」で発火
---
descriptionの書き方がトリガー精度を決める。「プロフェッショナルなドキュメントを作成する」のような曖昧な記述ではなく、「記事の下書きを生成する必要があるとき」のように具体的な状況を書く。
パターン2: テンプレート駆動型
テンプレートをreferences/に格納し、SKILL.mdでその使い方を指示するパターン。
proposal-creation-toolkit/
├── SKILL.md
└── templates/
├── how-to/template.md
├── concept/template.md
└── troubleshooting/template.md
SKILL.mdには「どのテンプレートをいつ使うか」の判断基準を書く。テンプレート自体はtemplates/に分離することで、SKILL.mdを短く保てる。
パターン3: パイプライン型
複数のステップを順番に実行するパターン。リサーチ→分析→出力のような流れに向いている。
ポイントは、各ステップの完了条件を明確にすることである。「調査する」ではなく「3つ以上のソースから情報を取得し、比較表を作成する」のように書く。途中成果をファイルに保存する指示も入れておくと、長時間タスクで途中結果が失われない。
パターン4: サブエージェント分離型
context: forkを指定して、メインのコンテキストウィンドウとは別の空間で実行するパターン。
---
name: deep-research
description: 深い調査が必要なとき。「調べて」「リサーチして」で発火
context: fork
---
調査やレビューなど、大量の情報を読み込む必要があるが、その詳細をメインの会話に持ち込みたくない場合に有効である。結果の要約だけがメインコンテキストに返される。
パターン5: マルチエージェント協調型
複数のサブエージェントを並行起動し、それぞれに異なる役割を持たせるパターン。記事執筆であれば、リサーチ担当・構成担当・レビュー担当を分ける、といった使い方ができる。
注意点として、エージェント間の依存関係を明確にする必要がある。「リサーチが終わってから構成を考える」なのか「並行して進めて後で統合する」のかで、SKILL.mdの書き方が変わる。
パターン6: ガードレール型
特定の操作を行う前に、チェックリストや検証を実行するパターン。PRレビュー、デプロイ前チェック、セキュリティスキャンなどに向いている。
---
name: pr-review
description: PRレビューを実行するとき。コード変更後に自動的に発火
---
「コードを変更したあとに自動的にレビューする」という使い方は、CI/CDパイプラインのローカル版として機能する。
チーム展開の3つの課題と解決策
個人で使う分にはSkillsは自由に設計できる。しかし、チームで共有しようとした瞬間に固有の課題が発生する。Henryのエンジニアブログで報告された課題と、それに対する解決策を整理する。
課題1: 変更の評価が難しい
Skillの設計パターンが未確立のため、PRレビューが主観的な判断に依存する。「このdescriptionは適切か」「このステップ数は妥当か」という問いに対して、客観的な基準がない。
解決策: Skillに対するテストケースを定義する。「このSkillに○○という入力を与えたとき、期待される出力は△△」という形式で検証可能にする。完全な自動テストは難しいが、チェックリストレベルでも効果がある。
課題2: 利用者間のニーズ相違
同じSkillに対して、メンバーAは「もっと詳細な指示がほしい」、メンバーBは「シンプルにしてほしい」と要求する。経験レベルや作業スタイルの違いが表面化する。
解決策: チームSkillを「必須ツール」ではなく「スターターキット」として位置づける。チームSkillをフォークして個人的にカスタマイズすることを推奨し、改善があればチームにフィードバックする。「個人で試す→検証する→チームに共有する」というサイクルを回す。
課題3: ポータビリティの喪失
チーム管理のSkillに依存すると、異動・転職時に再利用可能な資産を持ち出せない。特に、会社固有のAPI仕様やビジネスロジックがSkillに混入していると、分離が困難になる。
解決策: 個人SkillとチームSkillを別リポジトリで管理する。個人Skillには汎用的なプロンプトパターンと思考フレームワークのみを含め、会社固有情報はチームSkillに閉じ込める。
Skills設計のアンチパターン
1. SKILL.mdの肥大化
SKILL.mdに500行以上の指示を詰め込むパターン。コンテキストウィンドウを圧迫し、他のSkillとの同時利用が困難になる。
SKILL.mdは「いつ・何を・どの順序で」の骨格だけにとどめ、詳細な参考資料はreferences/に分離する。
2. descriptionの曖昧さ
「便利なユーティリティ」「開発を効率化する」のような抽象的なdescriptionは、自動トリガーの精度を著しく低下させる。
「TypeScriptのユニットテストを作成する必要があるとき」のように、具体的な状況と対象を明記する。
3. 手動呼び出しへの依存
/skill-nameでの手動起動ばかりになっている状態は、descriptionの改善が必要なサインである。適切なdescriptionが設定されていれば、自然な会話の中でSkillが自動的に発火する。
4. 状態管理の欠如
長時間タスクで途中成果をファイルに保存しないパターン。コンテキストウィンドウがいっぱいになったり、セッションが切れたりしたときにすべてが失われる。
重要な中間成果は必ずファイルに保存する指示をSKILL.mdに含める。
5. 権限の野放し
Skillが任意のBashコマンドを実行できる状態のまま運用するパターン。allowed-toolsでSkillが使えるツールを制限し、意図しない操作を防ぐ。
セキュリティ考慮事項
Skillsはプレーンテキストのファイルであり、任意の指示を含められる。これは柔軟性の源泉であると同時に、セキュリティリスクでもある。
第三者Skillのリスク
GitHubやnpmで公開されているSkillをそのままインストールすることは、見知らぬ人のシェルスクリプトをsudoで実行するのと本質的に変わらない。
必ず確認すべき項目:
- SKILL.mdの内容（悪意のある指示が含まれていないか）
-
scripts/内のスクリプト（外部通信や破壊的操作がないか） -
references/内のファイル（プロンプトインジェクションの仕込みがないか）
信頼できるソースの判断基準
- 自作のSkill（最も安全）
- チーム内でレビュー済みのSkill
- Anthropic公式リポジトリのSkill
- 著名なOSSプロジェクトが公開しているSkill
上記以外のソースからのSkillは、全ファイルを監査してから導入する。
context: forkによるリスク緩和
信頼度が低いSkillを使わざるを得ない場合、context: forkでサブエージェントとして隔離実行することで、メインのコンテキストへの影響を最小限に抑えられる。
まとめ
Claude Code Skillsは、AIコーディングアシスタントの活用を「受動的なコード補完」から「能動的なワークフロー設計」へと引き上げる仕組みである。
設計の勘所は以下の3点に集約される。
- descriptionが全て: 自動トリガーの精度はdescriptionの具体性で決まる
-
Progressive Disclosureを意識する: SKILL.mdは短く、詳細は
references/に分離 - 個人とチームの境界を明確にする: ポータビリティを維持しつつ、チームの知識を循環させる
Skillsはまだ成熟した技術ではない。設計パターンも確立途上にある。だからこそ、今の時点で自分なりのパターンを構築しておくことに価値がある。