Claude Code を使い始めると、わりと早い段階で「同じ指示を毎回書くのが面倒だ」という壁にぶつかります。
コードレビューのたびに「まず差分を確認して、次にセキュリティ観点でチェックして…」と打ち込むのは、エンジニアとしてあまりスマートじゃないですよね。
そこで登場するのが .claude/ ディレクトリの スキルファイル です。
mattpocock/skills の設計思想を読み解きながら、自分のプロジェクトに何をどう追加するかの判断軸を持てることを目指します。
.claude/ ディレクトリの役割分担——CLAUDE.md・commands・skills は何が違うのか
.claude/ の中には複数の仕組みが共存しています。
「どれも Claude への指示でしょ」と思いがちですが、選び分けの軸はシンプルで、 「いつコンテキストに読み込まれるか」 の一点です。
手段は3つのゾーンに分かれます。
- CLAUDE.md（常時）：プロジェクトの憲法。毎セッション必ず読み込まれる。「TypeScript を使う」「テストカバレッジ80%以上を維持する」のような常時適用ルールを書く場所。
- commands（手動呼び出し）：ターミナルのスラッシュコマンドで手動実行するショートカット。単一ファイルで完結し、/review のように呼ぶ。
- skills（オンデマンド）：業務マニュアル。Claude が「このタスクに使えそうだ」と判断したとき、あるいは明示的に呼ばれたときだけ読み込まれる。ディレクトリ構成で自動発見される。
- hooks（自動発火）：Claude のコンテキスト外で動くスクリプト。「ファイルを書き換えるたびにリンターを走らせる」のような機械的な強制に使う。
commands と skills の違いは、主に UX とパッケージングの差 です。
commands はターミナルの補完が効く単一ファイルのショートカット。
skills はディレクトリ構成で自動発見される、支援スクリプトやテンプレートを伴うことも多い構造体です。
ここで重要なのが、CLAUDE.md に全手順を詰め込んだときの弊害です。
CLAUDE.md は毎回全文が読み込まれるので、コードレビューの詳細手順をそこに書いてしまうと、ただのファイル編集タスクでも毎回その手順がコンテキストを占有します。
トークンの無駄遣いになるだけでなく、モデルの注意が本当に必要な情報から散漫になる、という具体的な弊害があります。
skills に切り出すことで「必要なときだけ読む」が実現できる——これが分ける理由の核心です。
スキルファイルとは何か——「プロンプト」ではなく「ワークフロー定義」として読む
「プロンプトを保存したもの」と思うと、スキルファイルの本質を見誤ります。
プロンプトは1回の対話に閉じています。
「このコードをレビューして」と書けばレビューしてくれますが、次回また同じ品質で動かすには、また同じ文脈を与え直す必要があります。
スキルは違います。
トリガー条件・ステップ・完了条件を持つ、再現可能なワークフロー定義 です。
Anthropic の公式ブログの言葉を借りると「新入社員向けのオンボーディングガイドを作るようなもの」——つまり、Claude の専門知識そのものを拡張する発想です。
実際の SKILL.md は、こんな骨格で成り立っています。
---
name: code-review
description: PRのコードレビューを実施する。差分取得からコメント投稿まで一貫して行う。
---
## トリガー条件
- ユーザーが「コードレビューして」「PRをレビューして」と依頼したとき
- /review コマンドが呼ばれたとき
## 前提チェック
- gh CLI がインストール・認証済みであることを確認する
- 対象ブランチまたはPR番号が特定できることを確認する
## ステップ
1. PR の差分を取得する
2. セキュリティ・パフォーマンス・可読性の観点でレビューコメントを準備する
3. ユーザーに投稿内容をプレビューとして見せる
4. 承認を得てからコメントを投稿する
## 完了条件
- すべてのレビューコメントが投稿されている
- ユーザーに次のアクションを提示している
frontmatter の name と description だけが初期ロード時に読まれ、Claude が「このスキルが使えそうだ」と判断した瞬間に本体を読み込む。
さらに必要なら参照ファイルやヘルパースクリプトを追加ロードする——という3段階構造です。
Anthropic がこれを Progressive Disclosure（段階的開示） と呼んでいるのは、まさにこの設計を指しています。
「全部最初から読ませる」のではなく「必要な分だけ引き出す」。
この発想の転換が、スキルファイルを理解するうえでいちばん大切なポイントです。
mattpocock/skills を読み解く——「workflow enforcement」という設計思想
mattpocock/skills が面白いのは、狙いが他のスキルパックと明確に違う点です。
多くのスキルパックは capability extension（できることを増やす） を目指します。
ブラウザ操作、データ取得、API 呼び出し——Claude に新しい手足を生やす方向性です。
Pocock のコレクションは違います。
AgentConn の分析が端的に表現していて、「Claude Code をチームの開発プロセスの参加者にする」——つまり workflow enforcement（ワークフローの強制） を狙っています。
「一発コマンドの実行者」ではなく「チームのメソドロジーに沿って動く開発者」として Claude を位置づける、という発想の転換です。
その設計思想が最もよく出ているのが tdd スキルです。
---
name: tdd
description: テスト駆動開発のワークフローを強制する。Red-Green-Refactor サイクルを一貫して実行する。
---
## 前提チェック
- テストランナー（vitest / jest 等）が設定済みであることを確認する
- 対象の機能・モジュールが特定されていることを確認する
- テストが現在 failing（Red）状態であることを確認する
passing なら先にテストを壊すか、新しいテストを書く
## ステップ（Red → Green → Refactor）
### Red フェーズ
1. 実装より先に、失敗するテストを書く
2. テストを実行して Red を確認する
3. エラーメッセージが「正しい理由で失敗している」ことを確認する
### Green フェーズ
4. テストを通過させる最小限の実装を書く
5. テストを実行して Green を確認する
6. この時点では「きれいさ」より「通過すること」を優先する
### Refactor フェーズ
7. テストが Green のまま、コードを整理する
8. 重複を除去し、命名を改善する
9. テストを再実行して Green が維持されていることを確認する
## 完了条件
- すべてのテストが passing である
- 実装コードにテストのない公開インターフェースが残っていない
- リファクタリング後もテストが Green である
このスキルの構造で注目したいのは、各ステップが 「次に何をすべきか」を Claude に迷わせない 設計になっている点です。
「Red を確認する」「最小限の実装を書く」——判断の余地を意図的に狭めることで、TDD の手順を逸脱させない。
これが「workflow enforcement」の実体です。
一方、obra/superpowers は別の哲学を持っています。
superpowers は brainstorm → plan → implement のループ全体を配線する、いわば 「自律的な長距離走を支えるメソドロジーエンジン」 です。
スキルの呼び出し自体をエージェントに強制する仕組みを持ち、サブエージェントや git worktree との連携も視野に入れた、より大きな自律性を狙っています。
mattpocock/skills が「エンジニアリングタスクの手順標準化」に特化したシャープなツールキットだとすれば、superpowers は開発ライフサイクル全体を包む方法論です。
どちらが優れているかではなく、「今の自分のチームに何が必要か」で選ぶべき、という話です。
自分のプロジェクトに何をスキル化すべきか——判断の3軸と書き始めの注意点
スキルファイルを知ると「全部スキル化したい」という気持ちになりがちです。
ただ、スキル化にもコストがかかるので、優先順位を付けて考えるのが現実的です。
判断の軸は3つあります。 繰り返し頻度（週に何度も発生するか）、 手順の複雑さ（ステップが多く順序を間違えると問題になるか）、 属人化リスク（特定のメンバーしか手順を知らない状態になっていないか）。
この3軸すべてが高いタスクが、スキル化の最優先候補です。
コードレビュー・TDD・デプロイ前チェック・PR 作成——こういったタスクは3軸が揃いやすいです。
逆に、スキル化に向かないタスクもあります。
一度きりのセットアップ作業や、手順が毎回状況によって変わるタスクは、スキルとして固めてもすぐ陳腐化します。
そういうものは CLAUDE.md のコンテキストとして渡すか、その都度プロンプトで対応する方が合理的です。
もう一つよく迷うのが「CLAUDE.md に書くべきか skills に書くべきか」です。
判断基準はシンプルで、「毎回読ませたいか、呼ばれたときだけでよいか」という問いに落とし込めます。
プロジェクトの技術スタックや命名規則は毎回必要なので CLAUDE.md。
コードレビューの詳細手順は呼ばれたときだけでよいので skills。
書き始めるときのよくある失敗パターンも共有しておきます。
手順を詰め込みすぎることです。
「完璧なスキル」を最初から作ろうとすると、ステップが膨大になって Claude が迷子になります。
最初は「前提チェック3つ・ステップ5つ・完了条件2つ」くらいの粒度で十分です。
CLAUDE.md との重複も要注意です。
CLAUDE.md に書いたルールをスキルにも書くと、矛盾が生じたときにどちらが優先されるか分からなくなります。
スキルには「手順」を書き、「ルール」は CLAUDE.md に一元化する分担を守るのが安全です。
トリガー条件が曖昧すぎることも失敗しやすいポイントです。
「コードを触るとき」のような広すぎるトリガーを書くと、Claude が意図しない場面でスキルを呼び出します。
「PR のレビューを依頼されたとき」「/review コマンドが呼ばれたとき」のように、具体的な条件を書くのが基本です。
最後に、実際に書き始めるときの最小構成を示します。
「動く最小構成を作って育てる」——この姿勢が長続きのコツです。
---
name: requesting-code-review
description: コードレビューを依頼する。差分の確認からレビューコメントの投稿まで一貫して行う。
---
## トリガー条件
- 「コードレビューして」「PRをレビューして」と依頼されたとき
## 前提チェック
- gh CLI がインストール・認証済みであることを確認する
- レビュー対象の PR 番号またはブランチが特定できることを確認する
## ステップ
1. PR の差分を取得する（gh pr diff）
2. 以下の観点でレビューコメントを準備する
- セキュリティ上の問題がないか
- パフォーマンス上の懸念がないか
- 可読性・命名に改善余地がないか
3. 投稿予定のコメントをユーザーにプレビューとして提示する
4. ユーザーの承認を得てからコメントを投稿する
## 完了条件
- レビューコメントが投稿されている
- ユーザーに次のアクションを案内している
この骨格さえあれば、Claude はレビューのたびに同じ品質で動いてくれます。
スキルファイルは、チームの暗黙知をコードと同じように管理する手段です。
まず1つ、自分が毎週やっているタスクをスキルに落とし込んでみると、その効果がすぐ実感できるはずです。
株式会社ホコサキは、山口県宇部を拠点に Web 制作・業務システム開発・AI 活用支援を手がけています。
Claude Code のような AI コーディングエージェントの実務導入や、チームへの展開支援にも対応しています。
気になることがあれば、お気軽に お問い合わせ ください。