日々のコーディングで「この作業、毎回同じことを指示しているな」と感じる場面はないでしょうか。Claude Code Skillsは、まさにそうした繰り返しの指示をカスタムコマンドとして定義し、開発ワークフローを劇的に改善する仕組みです。
本記事では、Claude Code Skillsの基本的な仕組みから、実際のプロジェクトで活用するための具体的な手順、そして導入時に押さえておきたいポイントまでを、筆者自身の実体験を交えながら詳しく解説していきます。
Claude Code Skillsの基本概念と仕組み
Claude Code Skillsとは、Claudeのコーディングエージェント「Claude Code」に対して、再利用可能なプロンプトテンプレートをスラッシュコマンドとして登録できる機能です。たとえば /commit や /review-pr のように、プロジェクト固有の操作を短いコマンドで呼び出せるようになります。
Skillsの実体は、.claude/skills ディレクトリ配下に配置されたMarkdownファイルです。ファイル名がそのままコマンド名となり、ファイル内にはClaude Codeへの詳細な指示をMarkdownで記述します。フロントマターでメタ情報を定義し、本文にプロンプトの内容を書くというシンプルな構造になっています。
私自身、最初はこの仕組みの存在を見落としていたのですが、一度使い始めると手放せなくなりました。特にチーム開発において、コードレビューやコミットメッセージの規約をSkillとして統一できる点は大きな価値があると感じています。
Skillsが解決する「暗黙知」の問題
開発チームには、ドキュメントとして明文化されていない「暗黙知」が数多く存在します。「コミットメッセージにはissue番号を含める」「テストファイルは対象ファイルと同じディレクトリ構造で配置する」「PRのdescriptionにはスクリーンショットを添付する」──こうしたルールは、口頭やチャットで共有されることが多く、新しいメンバーが加わるたびに同じ説明を繰り返す必要がありました。
Skillsを使えば、こうした暗黙知をコマンドとしてコード化し、リポジトリに格納できます。新メンバーがプロジェクトに参加した初日から、チームの規約に沿った作業を行えるようになるわけです。筆者のチームでも、オンボーディングにかかる時間が目に見えて短くなりました。
Skillsのファイル構造を理解する
Skillsファイルの構造をもう少し詳しく見てみましょう。フロントマターには以下のようなメタ情報を記述できます。
--- name: skill-name description: このSkillが何をするかの簡潔な説明 ---
name はスラッシュコマンドとして表示される名前です。省略した場合はファイル名が使用されます。description はSkillの一覧表示時に参照される説明文で、他のチームメンバーがSkillの目的を理解するために重要な役割を果たします。
本文部分には、Claude Codeに対する指示をMarkdownの自由な形式で記述します。番号付きリストでステップを示す方法が最も一般的ですが、箇条書きや自然文を組み合わせることも可能です。重要なのは、Claude Codeが指示を正確に解釈できる明確さを保つことです。
実際に運用してみると、指示が曖昧なSkillほど実行結果にブレが生じやすいことに気づきました。「適切にリファクタリングしてください」よりも「関数の行数が30行を超えている場合は責務を分離してください」のように、具体的な基準を含めた記述のほうが安定した結果を得られます。
カスタムコマンドの作成手順
実際にSkillを作成する手順を見ていきましょう。まず、プロジェクトルートに .claude/skills ディレクトリを作成します。次に、その中にMarkdownファイルを配置します。
--- name: test-and-fix description: テスト実行後、失敗があれば自動修正する --- 1. テストスイートを実行してください 2. 失敗したテストがあれば原因を分析してください 3. 修正案を提示し、承認後にコードを修正してください
これだけで /test-and-fix というコマンドが使えるようになります。AとBのどちらの粒度で定義すべきか悩む方も多いかもしれませんが、最初は「週に3回以上同じ指示を出している作業」を目安にSkill化するのがおすすめです。
引数を受け取ることも可能で、$ARGUMENTS プレースホルダーを使えば /my-skill some-args のように動的な値を渡せます。振り返ると、引数を活用せずに似たSkillを量産していた時期は遠回りでした。
ステップ・バイ・ステップで作る初めてのSkill
ここでは、より実践的な例として「新機能の実装開始時に必要な一連の準備を自動化するSkill」を作成してみます。
まず、ターミナルでディレクトリを作成します。
mkdir -p .claude/skills
次に、.claude/skills/start-feature.md というファイルを作成します。
--- name: start-feature description: 新機能の実装に必要なファイル群を生成する --- 新機能「$ARGUMENTS」の実装を開始します。以下の手順で進めてください。 1. `git switch -c feature/$ARGUMENTS` でフィーチャーブランチを作成してください 2. 機能に必要なコンポーネントファイルを `src/components/$ARGUMENTS/` 配下に作成してください 3. 対応するテストファイルを `__tests__/components/$ARGUMENTS/` 配下に作成してください 4. 必要に応じて型定義ファイルを `src/types/` 配下に追加してください ※ 既存のコンポーネントを参考にして、プロジェクトのコーディング規約に沿った形式で作成してください。
これで /start-feature user-profile と入力するだけで、ブランチの作成からファイルの雛形生成までを一貫して実行できるようになります。
筆者がこのSkillを初めてチームに導入した際、「ブランチ名の命名規則を毎回確認しなくて済むようになった」という声が真っ先に上がりました。小さなことのように思えますが、こうした認知負荷の軽減が積み重なることで、開発者が本来集中すべきロジックの設計や実装に時間を使えるようになります。
引数を活用した柔軟なSkill設計
$ARGUMENTS の活用方法をもう少し掘り下げてみましょう。引数は単一の文字列として渡されますが、Skill本文の書き方次第で複数の情報を受け取ることも可能です。
--- name: add-api description: APIエンドポイントの雛形を生成する --- 以下の仕様に基づいてAPIエンドポイントを作成してください。 対象: $ARGUMENTS - エンドポイントのパス、HTTPメソッド、概要を上記の指定から読み取ってください - `app/api/` 配下にNext.js App Routerの規約に従ってRoute Handlerを作成してください - リクエスト・レスポンスの型定義を作成してください - バリデーション処理を含めてください - 対応するAPIテストファイルを作成してください
この例では /add-api GET /users ユーザー一覧取得 のように呼び出すことで、Claude Codeが引数の内容を解釈し、適切なファイル群を生成してくれます。引数の解釈はClaude Codeの自然言語理解に委ねられるため、厳密なフォーマットを強制する必要はありません。ただし、Skill本文内で「引数の形式はこうです」と明記しておくと、より安定した結果が得られるでしょう。
開発現場で効果を発揮する実践的なSkills例
実務で特に効果が高いと感じたSkillsをいくつか紹介します。
コミット規約の自動適用: プロジェクト固有のコミットメッセージフォーマットをSkillに定義しておけば、チーム全員が統一されたコミット履歴を維持できます。Conventional Commitsの導入で苦労した経験がある方には、特に響くのではないでしょうか。
PRレビューの標準化: レビュー観点をSkillとして定義することで、セキュリティチェックやパフォーマンス確認の抜け漏れを防げます。一概には言えない部分もありますが、レビューの品質が安定したことは間違いありません。
テスト生成の効率化: 対象ファイルを指定するだけで、プロジェクトの既存テストパターンに沿ったテストコードを生成するSkillも有効です。テストカバレッジの向上に直結しました。
コミットSkillの具体的な実装例
コミット規約の自動適用について、もう少し具体的に見てみましょう。以下は筆者のプロジェクトで実際に運用しているSkillを簡略化したものです。
--- name: commit description: プロジェクト規約に沿ったコミットを作成する --- 以下のルールに従ってコミットを作成してください。 ## コミットメッセージのフォーマット - 形式: `<type>(<scope>): <subject>` - type: feat, fix, docs, style, refactor, test, chore のいずれか - scope: 変更対象のモジュール名（省略可） - subject: 変更内容の要約（日本語可、50文字以内） ## 手順 1. `git diff --staged` で変更内容を確認してください 2. 変更内容に最も適した type を選択してください 3. 上記フォーマットに従ってコミットメッセージを作成してください 4. ユーザーにメッセージを提示し、承認を得てからコミットしてください ## 注意事項 - 一つのコミットに複数の関心事を含めないでください - 変更が大きい場合は分割コミットを提案してください
このSkillの導入前は、チーム内で「feat」と「feature」が混在したり、日本語と英語のメッセージが入り混じったりしていました。導入後はコミット履歴の一覧性が格段に向上し、git log からの情報検索が効率的になりました。些細な変化ですが、日々の開発体験を確実に底上げしてくれる改善だと実感しています。
PRレビューSkillで品質の底上げを実現する
PRレビューのSkillは、チーム全体のコード品質を安定させるうえで非常に有効です。特に、レビュー観点の属人化を防ぐ効果が大きいと感じています。
--- name: review-pr description: PRをプロジェクト基準でレビューする --- 以下の観点でプルリクエストの変更内容をレビューしてください。 ## セキュリティ - SQLインジェクション、XSS、CSRFの脆弱性がないか - 認証・認可の処理が適切か - 機密情報がハードコードされていないか ## パフォーマンス - N+1クエリが発生していないか - 不要な再レンダリングを引き起こす実装がないか - 大量データ処理時のメモリ使用量に問題がないか ## 保守性 - 命名は意図を適切に表現しているか - 関数やコンポーネントの責務が単一か - テストが追加または更新されているか ## 出力形式 - 問題の深刻度を「Critical」「Warning」「Info」の3段階で分類してください - 各指摘に対して改善案を具体的に提示してください
レビュー観点を明文化することで、経験の浅いメンバーでも一定水準のレビューが可能になります。もちろん、Skillによるレビューは人間によるレビューの代替ではなく、補完として位置づけるのが適切です。機械的にチェックできる観点をSkillに任せることで、人間のレビューアーはビジネスロジックの妥当性や設計判断の評価に集中できるようになります。
テスト生成Skillで開発速度とカバレッジを両立する
テストを書く作業は重要であると分かっていても、後回しにしてしまいがちなものです。テスト生成Skillは、そのハードルを大幅に下げてくれます。
--- name: gen-test description: 指定ファイルに対するテストを生成する --- 「$ARGUMENTS」に対するテストコードを生成してください。 ## テスト方針 - 既存テストのディレクトリ構造と命名規則に従ってください - 正常系・異常系・境界値の3カテゴリでテストケースを作成してください - モックは必要最小限にとどめ、実際の挙動に近い形でテストしてください - テスト名は「何を」「どのような条件で」「どうなるか」が分かるように記述してください ## 実行確認 - テストファイル作成後、テストを実行して全件パスすることを確認してください - 失敗するテストがあれば原因を分析し、テストコードまたは本体コードの修正を提案してください
このSkillのポイントは「既存テストのパターンに従う」という指示を含めている点です。プロジェクトごとにテストの書き方には独自の慣習があります。Claude Codeはリポジトリ内の既存コードを参照できるため、この指示を入れるだけで既存のテストと一貫性のあるコードが生成されます。
筆者のプロジェクトでは、このSkillの導入後3か月でテストカバレッジが約20ポイント向上しました。テストを書くこと自体のコストが下がったことで、「ついでにテストも書いておこう」という文化がチームに根付いたのだと思います。
Skillsをチームで運用するための実践ガイド
個人で使い始めたSkillsをチーム全体に展開する際には、いくつかの工夫が必要です。筆者が実際に経験した試行錯誤を踏まえて、効果的な運用方法をお伝えします。
命名規則を統一する
Skillsの数が増えてくると、命名の一貫性が重要になります。筆者のチームでは以下のような規則を採用しています。
- 動詞-名詞形式:
gen-test、review-pr、start-featureのように、「何をするか」が一目で分かる名前にする - 略語の統一:
generateはgen、checkはchkのように、チーム内で略語のルールを決めておく - プレフィックスによる分類: 必要に応じて
db-migrate、db-seedのようにカテゴリを示すプレフィックスを付ける
命名規則が曖昧なままSkillsを増やしてしまうと、似たような名前のSkillが乱立し、どれを使えばよいか分からなくなるという事態を招きます。最初に規則を決めておくことで、この問題を未然に防げます。
Skillsの改善サイクルを回す
Skillsは一度作って終わりではありません。実際に使ってみると「この指示では意図した結果が得られない」「もう一手順追加したほうがよい」といった気づきが出てきます。
筆者のチームでは、Skillsの改善をプルリクエストベースで行っています。「このSkillの出力結果がイマイチだった」という報告があれば、プロンプトの記述を修正するPRを作成し、チームでレビューするという流れです。プロンプトエンジニアリングの知見がチーム全体に共有される副次的な効果もありました。
また、月に一度「Skillsの棚卸し」を行い、使われていないSkillの削除や統合を検討する時間を設けています。Skillsの数が多すぎると選択に迷うため、定期的な整理は思いのほか重要です。
グローバルSkillsとプロジェクトSkillsの使い分け
Claude Codeでは、プロジェクト単位のSkills（.claude/skills/）に加えて、ユーザーのホームディレクトリに配置するグローバルSkills（~/.claude/skills/）も利用できます。
グローバルSkillsには、プロジェクトを問わず共通で使いたい汎用的なコマンドを配置するとよいでしょう。たとえば、一般的なGitの操作やドキュメント作成の補助など、特定のプロジェクトに依存しない作業が該当します。
一方で、プロジェクト固有の規約や技術スタックに関わるSkillsは、プロジェクトディレクトリ配下に置いてリポジトリで管理するのが適切です。この使い分けを明確にしておくことで、Skillsの管理がシンプルになります。
Skills導入時の注意点とベストプラクティス
Skillsは強力な仕組みですが、導入にあたっていくつか意識しておきたい点があります。
第一に、Skillの粒度設計です。あまりに大きな単位でSkillを定義すると、汎用性が下がり使われなくなります。逆に細かすぎると管理が煩雑になるため、「一つの明確な目的」を持つ単位が適切でしょう。同じ悩みを抱えている方も多いのではないでしょうか。
第二に、バージョン管理との統合です。.claude/skills ディレクトリをリポジトリに含めることで、チーム全体でSkillsを共有できます。プルリクエストを通じてSkillsの改善を議論できる点も見逃せません。
第三に、CLAUDE.mdとの使い分けです。プロジェクト全体に常時適用したいルールはCLAUDE.mdに、特定のタイミングで明示的に呼び出したい操作はSkillsに定義するのが適切だと感じました。
CLAUDE.mdとSkillsの境界線を見極める
この使い分けは、運用してみると思いのほか悩ましい部分です。筆者なりの判断基準を整理してみます。
CLAUDE.mdに書くべきものは、Claude Codeが「常に」意識すべきルールです。たとえば、プロジェクトのディレクトリ構成の説明、使用している技術スタックの一覧、コーディングスタイルの基本方針などが該当します。これらは個別のコマンドとして呼び出す性質のものではなく、あらゆる操作の前提となる知識です。
Skillsに書くべきものは、「特定のアクションを起こすための手順書」です。コミット、レビュー、テスト生成、デプロイ前チェックなど、明確な開始と終了がある作業が適しています。
判断に迷ったときは、「これは毎回の会話で読み込まれる必要があるか？」と自問してみてください。答えがNoであれば、Skillsとして定義するのが適切です。CLAUDE.mdの内容は毎回のコンテキストに含まれるため、肥大化すると他の重要な情報が埋もれるリスクがあります。
プロンプト記述のコツ
Skillsの本文に記述するプロンプトの品質は、出力の品質に直結します。筆者がこれまでの運用で得た知見をいくつか共有します。
ステップを明確に分ける: 「分析して修正してください」ではなく、「1. 分析してください 2. 結果を報告してください 3. 修正案を提示してください」のように分解すると、Claude Codeが各段階で適切な出力を行いやすくなります。
期待する出力形式を示す: レビュー結果をどのような形式で出力してほしいのか、テストコードをどのフレームワークで書いてほしいのかなど、出力のイメージを具体的に記述しておくと結果が安定します。
否定形よりも肯定形で指示する: 「長すぎる関数を書かないでください」よりも「関数は30行以内を目安にしてください」のほうが、具体的な行動指針として機能します。何をしてほしいかを明確に伝えることが大切です。
コンテキストを与える: なぜそのルールが存在するのかを補足情報として記載しておくと、Claude Codeがエッジケースにおいても適切な判断を行いやすくなります。たとえば「コミットは小さく分割してください（理由：レビューの負担軽減とrevertの容易さのため）」のように書くと、分割の粒度をClaude Code自身が判断できるようになります。
段階的な導入のすすめ
Skillsの導入は、一度にすべてを整備しようとせず、段階的に進めることをおすすめします。筆者のチームでは以下の順序で導入を進めました。
第1段階: まず個人で2〜3個のSkillを作成し、1〜2週間ほど日常的に使ってみます。この段階で「Skillにすべき作業」と「都度指示したほうがよい作業」の感覚が掴めてきます。
第2段階: チーム内で特に反復頻度の高い作業（コミット、テスト生成など）をSkill化し、リポジトリにコミットします。チームメンバーから使用感のフィードバックを集め、プロンプトを改善します。
第3段階: Skillsの一覧と使い方をチームの開発ガイドに追記し、新メンバーのオンボーディングフローに組み込みます。定期的な棚卸しの習慣もこの段階で確立します。
焦って大量のSkillsを一度に作成しても、チームに浸透しなければ意味がありません。小さく始めて成功体験を積み、徐々に拡大していくアプローチが結果的には近道でした。
よくある疑問とトラブルシューティング
Skillsを使い始めると、いくつかの疑問やつまずきに遭遇することがあります。筆者やチームメンバーが実際に経験した事例をもとに、対処法をまとめます。
Skillが認識されない場合
/skill-name と入力してもSkillが見つからない場合は、まずファイルの配置場所を確認してください。Skillsファイルは .claude/skills/ ディレクトリの直下に配置する必要があります。サブディレクトリに入れた場合にも認識されますが、コマンド名にディレクトリ構造が反映されるため注意が必要です。
また、ファイルの拡張子が .md であることも確認してください。Markdown以外の形式は認識されません。
Skillの実行結果が期待と異なる場合
プロンプトの記述が曖昧な場合、Claude Codeが意図と異なる解釈をすることがあります。このような場合は、まず指示の各ステップが十分に具体的かどうかを見直しましょう。
たとえば「適切にテストを書いてください」という指示は、Claude Codeにとって解釈の幅が広すぎます。「Jestを使用して、describe/itブロックで構造化し、各テストケースにはArrange-Act-Assertパターンを適用してください」のように、具体的な技術要素や構造を明示することで改善が見込めます。
プロンプトの改善は一度で完璧にする必要はありません。実際の出力結果を見ながら少しずつ調整していくのが現実的なアプローチです。
複数のSkillsを組み合わせたい場合
「テストを生成してから、その結果に基づいてコミットする」のように、複数のSkillsを連続で実行したいケースがあります。現時点では、Skill内から別のSkillを直接呼び出す仕組みは提供されていませんが、一つのSkillに複数のフェーズをまとめて記述することで同等の効果を得られます。
ただし、一つのSkillに詰め込みすぎると可読性や保守性が低下するため、あくまで関連性の高い作業の範囲に留めることを意識してみてください。
まとめ：Skillsで開発チームの生産性を次のステージへ
Claude Code Skillsは、AIコーディングエージェントの活用を「個人の工夫」から「チームの資産」へと昇華させる機能です。繰り返しの指示をSkillとして体系化することで、開発プロセス全体の品質と速度が向上します。
本記事で紹介したように、Skillsの導入は小さなところから始められます。まずは日常的に繰り返している作業を一つ選び、Skillとして定義してみてください。その便利さを実感できれば、自然とSkillsの数は増えていくはずです。
重要なのは、Skillsを「作って終わり」にしないことです。チームのフィードバックを受けてプロンプトを改善し、不要になったSkillは整理し、常にチームの現在の開発フローに合った状態を維持する。この継続的な改善のサイクルが、Skillsの真価を最大限に引き出す鍵だと筆者は考えています。
私たちaduce株式会社でも、AI技術を活用した開発効率化に日々取り組んでいます。Claude Codeをはじめとするツールの導入支援や、開発プロセスの最適化についてご相談があれば、ぜひaduceのお問い合わせはこちらからお気軽にご連絡ください。