Claude Code Skillsで開発ワークフローを自動化する実践ガイド

AIコーディングアシスタントを使い始めたものの、毎回同じような指示を繰り返し入力していることに気づいた経験はないでしょうか。コードレビューの観点、コミットメッセージのフォーマット、テストの書き方——プロジェクトごとに決まったルールがあるのに、その都度プロンプトを書き直すのは非効率です。Claude Code Skillsは、こうした繰り返しの指示をテンプレート化し、スラッシュコマンドとして呼び出せる仕組みです。本記事では、Skillsの基本概念から実践的な活用方法までを、私たちaduceでの導入経験を交えてご紹介します。

Claude Code Skillsとは何か

Claude Code Skillsは、よく使うプロンプトや作業手順をMarkdownファイルとして定義し、/スキル名 というスラッシュコマンドで即座に呼び出せる機能です。Anthropicが2025年に正式リリースしたClaude Codeに組み込まれており、個人用・プロジェクト共有用の両方で運用できます。

仕組みはシンプルで、所定のディレクトリにMarkdownファイルを配置するだけです。ユーザー個人のスキルは ~/.claude/skills/ に、プロジェクト共有のスキルは .claude/skills/ に格納します。ファイル名がそのままコマンド名になるため、たとえば review.md を作成すれば /review で呼び出せるようになります。

最初にこの仕組みを知ったとき、正直なところ「CLAUDE.mdに書けば済むのでは」と思いました。しかし実際に運用してみると、CLAUDE.mdは常に読み込まれる「常駐ルール」であるのに対し、Skillsは必要なときだけ呼び出す「オンデマンドな指示」という明確な使い分けがあることに気づかされました。コンテキストウィンドウを無駄に消費しない点でも、この区別は重要です。

CLAUDE.mdとSkillsの使い分け

この違いをもう少し具体的に整理してみます。CLAUDE.mdには「このプロジェクトではTypeScriptを使う」「コミットメッセージは日本語で書く」といった、あらゆる作業に横断的に適用されるルールを記述します。一方、Skillsには「E2Eテストを書くときの手順」「APIドキュメントを生成するときのフォーマット」のように、特定のタスクでのみ必要な指示を記述します。

たとえば、私たちのプロジェクトではCLAUDE.mdに「Conventional Commits形式を使用する」と記載しています。これはすべてのコミットに適用されるルールだからです。しかし「リリースノートを生成する」という作業は月に数回しか発生しないため、スキルとして切り出しています。この粒度の判断が、運用を続けるうちに自然と洗練されていく感覚がありました。

実際に判断に迷ったときの目安として、「その指示がなくても大半の作業に支障がないか」を基準にすると分けやすいです。支障がある（＝常に必要）ならCLAUDE.md、支障がない（＝特定の場面でだけ必要）ならSkills、という考え方です。

もう一つ補足すると、CLAUDE.mdはプロジェクトルート以外にもサブディレクトリに配置でき、階層的にルールを適用できます。たとえば frontend/CLAUDE.md にはReact固有のルールを、backend/CLAUDE.md にはAPI固有のルールを記述する、といった使い方です。一方、Skillsにはこうした階層構造の概念はなく、すべてフラットに管理されます。この構造の違いを理解しておくと、どちらに何を書くべきかの判断がさらに明確になります。

Skillsの作成手順と基本構成

Skillsの作成は、Markdownファイルを1つ書くだけで完了します。特別なCLIコマンドやビルド手順は不要です。基本的な構成を見てみましょう。

まず、プロジェクトルートに .claude/skills/ ディレクトリを作成します。そこに、たとえば test-gen.md というファイルを以下のような内容で配置します。

フロントマターの description フィールドは、Claude Codeがスキルの用途を判断する際の手がかりになります。省略しても動作しますが、記述しておくことでスキルの一覧表示時にも内容が把握しやすくなるため、書いておくことをお勧めします。

私たちのチームでは当初、1つのスキルに多くの指示を詰め込みすぎてしまい、かえって出力が不安定になるという失敗がありました。振り返ると、1スキル1目的に絞り、必要に応じて複数のスキルを組み合わせるほうが結果的に安定した出力が得られます。同じように試行錯誤されている方も多いのではないでしょうか。

フロントマターで使える設定項目

フロントマターには description 以外にもいくつかの設定を記述できます。実用上とくに押さえておきたいのは以下の項目です。

description には、そのスキルが「いつ・何のために使われるか」を一文で記述します。Claude Codeはこの記述をもとにスキルの関連性を判断するため、曖昧な表現よりも具体的な動詞と対象を含めると精度が上がります。たとえば「レビューする」よりも「PRの差分を読み、セキュリティ・パフォーマンス・可読性の観点でレビューコメントを生成する」のほうが、意図どおりに呼び出されやすくなります。

スキルファイルの書き方のコツ

スキルの中身は通常のMarkdownですが、Claude Codeが正確に解釈できるよう、いくつかのポイントを意識すると出力の安定性が向上します。

箇条書きで条件を列挙する。 自然言語の長文よりも、箇条書きのほうがClaude Codeは正確に条件を拾います。「AかつBの場合はCする」のような複雑な条件も、箇条書きにして個別に記述するほうが確実です。

具体例を含める。 「適切なエラーメッセージを出力する」という抽象的な指示よりも、実際の出力例を添えたほうが期待どおりの結果になります。

スコープを明示する。 「このスキルはバックエンドのAPIルートハンドラにのみ適用する」のように、適用範囲を冒頭で宣言しておくと、関係のないファイルに対してスキルが誤適用されるのを防げます。

引数を活用する。 スキルはスラッシュコマンドとして呼び出す際に引数を渡すことができます。たとえば /test-gen src/utils/validation.ts のように対象ファイルを指定すれば、スキル内でその引数を参照して処理を行います。引数を前提としたスキル設計にしておくと、汎用性が格段に上がります。私たちのチームでは、引数なしで呼び出された場合の振る舞いもスキル内に記述しておくことで、使い勝手をさらに高めています。

実務で効果を発揮するユースケース

実際にどのような場面でSkillsが活きるのか、私たちが運用している例をいくつかご紹介します。

コードレビューの標準化

レビュー観点をスキルとして定義しておくと、チーム全員が同じ基準でレビューを依頼できるようになります。セキュリティチェック、パフォーマンス観点、アクセシビリティ対応など、見落としがちな観点を体系的に網羅できる点が大きな利点です。

私たちが実際に使っているレビュースキルの構成例をご紹介します。

導入前は、レビュアーによって指摘の粒度やフォーカスがばらつくことが課題でした。あるメンバーはセキュリティに詳しいためその観点が手厚い一方で、パフォーマンス面の指摘が薄い、ということが起きていました。スキルとして観点を明文化してからは、誰がレビューしても一定の網羅性が担保されるようになりました。もちろん、スキルの出力をそのまま鵜呑みにするのではなく、人間が最終判断する前提です。AIの指摘をたたき台にしてレビュー議論が始まる、という流れが自然にできています。

コミットメッセージの自動生成

Conventional Commits形式やIssue番号の付与ルールなど、プロジェクト固有のコミット規約をスキル化することで、フォーマットの揺れを防止できます。これは地味ながら、後からgit logを追う際の可読性に直結するため、チーム開発では特に重宝しています。

具体例として、私たちが使っているコミットスキルの一部をお見せします。

このスキルを導入してから、チーム内のコミットメッセージが統一されました。以前は「修正」「fix」「バグ直した」のように人によって書き方がばらついていたのですが、今では全員が同じ形式で記述しています。小さな変化に思えるかもしれませんが、半年分のgit logを遡ったときの読みやすさは格段に違います。

ブログ記事やドキュメントの生成

実はこの記事自体も、Skillsに近い仕組みを活用して生成のベースを作成しています。トーン、文字数、構成ルールといった条件をテンプレート化しておけば、テーマを変えるだけで一定品質のドラフトを効率的に作成できます。

たとえば、技術ブログの記事生成スキルでは、以下のような条件を定義しています。

ドキュメント生成においても同様の効果があります。APIドキュメント、設計書、議事録など、フォーマットが決まっているドキュメントほどスキル化の恩恵が大きいと感じています。

データベースマイグレーションの安全チェック

これは少しニッチなユースケースですが、開発現場では非常に重宝しています。マイグレーションファイルを作成した際に、本番環境で実行しても安全かをチェックするスキルです。

以前、本番環境でカラムの型変更を実行した際に長時間のテーブルロックが発生し、サービスに影響が出たことがありました。このスキルはその反省から生まれたもので、マイグレーション作成時に自動的に安全性を確認する習慣がチームに定着しました。

AとBのどちらのアプローチが良いか迷うケースもありますが、一概に正解があるわけではありません。まずは小さなスキルから始めて、チームのフィードバックを受けながら改善していくのが現実的な進め方でしょう。

スキルを効果的に設計するための原則

スキルをいくつか作っていくと、「うまく機能するスキル」と「期待どおりの出力が得られないスキル」の違いが見えてきます。私たちの試行錯誤から得た設計原則をまとめます。

原則1：1スキル1責務に絞る

前述のとおり、1つのスキルに複数の目的を詰め込むと出力が不安定になります。「レビューしてテストも書いてコミットメッセージも生成して」という全部入りスキルは魅力的に思えますが、実際にはそれぞれを独立したスキルにしたほうが、各出力の品質が高くなります。

悪い例と良い例を比較してみましょう。

分離したスキルは組み合わせて使えます。「/review を実行して、指摘事項を修正したあとに /test-gen でテストを追加する」という流れは、一見手間に感じるかもしれませんが、各ステップの出力を確認しながら進められる安心感があります。

原則2：出力形式を具体的に指定する

「適切にレビューしてください」のような曖昧な指示では、毎回異なる形式で出力が返ってきます。出力のフォーマット、含めるべき情報、分類基準などを明示的に指定することで、安定した結果が得られます。

このように出力形式を定義しておくと、レビュー結果をそのままGitHubのPRコメントに貼り付けられるようになります。形式が安定していると、後続の作業フローにも組み込みやすくなるのです。

原則3：否定形より肯定形で指示する

「マジックナンバーを使わないでください」よりも「定数として定義し、意図が伝わる名前をつけてください」のほうが、Claude Codeは正確に従います。人間への指示と同様に、「やるべきこと」を明確に伝えるほうが効果的です。

これは私たちがスキルを何度も書き直す中で実感した点です。否定形の指示はClaude Codeにとって解釈の余地が広すぎるのか、期待と異なる回避策が出力されることがありました。

原則4：段階的に詳細化する

スキルを最初から完璧に仕上げようとすると、かえって手が止まりがちです。私たちが効果的だと感じたのは、まず最小限の指示で動くスキルを作り、実際に使いながら条件を追加していくアプローチです。

たとえばレビュースキルの初版は、チェック観点を3つだけ箇条書きにしたシンプルなものでした。それを実際のPRで使ってみると、「型安全性の確認が抜けている」「エラーハンドリングについても言及してほしい」といった改善点が具体的に浮かび上がってきました。使いながら育てていくことで、チームの実情に即したスキルが出来上がっていきます。

プロジェクト共有とチーム運用のポイント

Skillsの真価は、チームで共有したときに発揮されます。.claude/skills/ ディレクトリをGitリポジトリにコミットすれば、チーム全員が同じスキルセットを使えるようになります。

運用上のポイントをいくつか挙げます。まず、スキルの命名規則を統一することが重要です。review、test-gen、doc-gen のように、動詞または動詞＋対象の形式で揃えると、一覧で見たときに用途がすぐに把握できます。

次に、スキルの更新履歴もGitで追跡できるため、「なぜこのルールを追加したのか」をコミットメッセージに残しておくと、後から経緯を確認しやすくなります。ドキュメントとコードの中間に位置するスキルだからこそ、変更理由の記録が大切だと感じました。

また、個人用スキル（~/.claude/skills/）とプロジェクト用スキル（.claude/skills/）の使い分けも意識すべき点です。個人の作業効率化に関するものは個人用に、チームの品質基準に関わるものはプロジェクト用に配置するのが自然な分け方かもしれません。

命名規則の具体例

私たちのチームで実際に採用している命名規則をご紹介します。

スキル名にプレフィックスを付けてカテゴリを表現するのも有効です。review-* はレビュー系、doc-* はドキュメント系、というようにグループ化しておくと、スキルが増えてきたときにも見通しが良くなります。

スキルの段階的な導入プロセス

チームにSkillsを導入する際、全員に一度に使ってもらおうとすると抵抗が生まれることがあります。私たちが実践した段階的なアプローチをご紹介します。

ステップ1：まず一人が使い始める。 チーム内のClaude Code利用者が個人スキルとして試作し、日常業務で使ってみます。この段階では完成度にこだわらず、「便利だな」と感じるものを見つけることが目的です。

ステップ2：チームに共有し、フィードバックをもらう。 効果が実感できたスキルをプロジェクト用ディレクトリに移し、チームメンバーに紹介します。この段階で「こういう観点も追加してほしい」「この指示は不要では」といったフィードバックが集まります。

ステップ3：PRでスキルの追加・変更を管理する。 スキルもコードと同じようにレビュープロセスを通します。「なぜこのルールが必要か」をPRの説明に記述することで、チーム全員がスキルの意図を理解した上で運用できます。

この段階的なアプローチにより、スキルがチームの共有知識として自然に定着しました。押しつけではなく、実利を見せて共感を得る、という進め方が結果的にうまくいったと感じています。

運用で注意すべき落とし穴

Skillsは便利な仕組みですが、運用を続ける中でいくつかの注意点も見えてきました。同じ失敗を繰り返さないために、私たちが経験した落とし穴を共有します。

スキルの肥大化

スキルは作りやすいがゆえに、気づけば数十個に膨れ上がることがあります。使われていないスキルが放置されると、一覧の見通しが悪くなり、どれを使えばよいかわからないという本末転倒な状態に陥ります。

対策として、私たちは四半期に一度、スキルの棚卸しを行っています。直近3ヶ月で使用されなかったスキルは、アーカイブするか統合するかを検討します。

過度な依存

スキルに頼りすぎて、指示がないと判断できないという状態も避けるべきです。スキルはあくまで「繰り返しの自動化」であり、「思考の代替」ではありません。たとえばレビュースキルを使う場合でも、出力を鵜呑みにせず、自分自身でもコードを読んで判断する姿勢が大切です。

コンテキストとの競合

スキルの内容がCLAUDE.mdの記述と矛盾している場合、Claude Codeの出力が不安定になることがあります。たとえば、CLAUDE.mdに「テストフレームワークはJest」と書いてあるのに、スキルで「Vitestを使う」と指示すると混乱が生じます。スキルを追加する際には、既存のCLAUDE.mdとの整合性を確認する習慣をつけることをお勧めします。

スキルのバージョン間の互換性

Claude Codeのアップデートに伴い、スキルの解釈が微妙に変わることがあります。私たちも過去に、アップデート後にそれまで問題なく動いていたスキルの出力が変化し、戸惑った経験があります。対策としては、スキルの指示をできるだけ明示的かつ構造的に書いておくことです。暗黙的な前提に依存した書き方は、バージョン変更の影響を受けやすい傾向があります。重要なスキルについては、アップデート直後に一度動作を確認する運用にしておくと安心です。

Hooksとの組み合わせでさらに自動化を進める

Claude CodeにはSkillsとは別に「Hooks」という仕組みがあります。Hooksは特定のイベント（ファイル保存、コミット前など）をトリガーにしてシェルコマンドを自動実行する機能で、Skillsと組み合わせることで、より高度な自動化ワークフローを構築できます。

たとえば、コミット前にリントとテストを自動実行するHookを設定しつつ、コミットメッセージの生成にはSkillsを使う、という組み合わせが考えられます。Hooksが「いつ実行するか」を制御し、Skillsが「何を実行するか」を定義する、という役割分担です。

具体的な設定例を見てみましょう。Hooksは .claude/settings.json に記述します。

Hooksには PreToolUse（ツール実行前）、PostToolUse（ツール実行後）、Notification（通知時）といったイベントタイプがあり、それぞれにシェルコマンドを紐づけることができます。たとえば、ファイル編集後に自動でリントを走らせる、テスト実行後に結果をSlackに通知する、といった自動化が実現できます。

SkillsとHooksの役割を整理すると、以下のようになります。

ただし、HooksとSkillsを一度に大量に導入すると、何がどのタイミングで動いているのか把握しづらくなります。まずはSkillsを整備し、その上で自動化したいポイントが見えてきたらHooksを追加する、という順序が無理のない導入パスではないでしょうか。

まとめ：小さく始めて、開発体験を積み上げる

Claude Code Skillsは、AIコーディングアシスタントの出力品質と作業効率を、再現可能な形で底上げする仕組みです。Markdownファイル1つから始められる手軽さと、Git管理によるチーム共有の容易さが、現場への導入ハードルを大きく下げています。

本記事でご紹介した内容を改めて整理します。

• 基本構成： .claude/skills/ にMarkdownファイルを配置するだけで、スラッシュコマンドとして呼び出せる
• CLAUDE.mdとの使い分け： 常に適用するルールはCLAUDE.md、特定タスク向けの指示はSkills
• 設計原則： 1スキル1責務、出力形式を具体的に指定、否定形より肯定形で指示、段階的に詳細化
• チーム運用： 命名規則の統一、Git管理によるレビューと履歴追跡、段階的な導入
• 注意点： スキルの肥大化を防ぐ棚卸し、過度な依存の回避、CLAUDE.mdとの整合性確認
• 発展的な活用： Hooksとの組み合わせで、手動の標準化と自動の品質ゲートを両立

大掛かりな導入計画を立てる必要はありません。まずは日常的に繰り返しているプロンプトを1つ選び、スキルとして切り出してみることをお勧めします。その小さな一歩が、チーム全体の開発ワークフロー改善につながるはずです。

私たち自身、最初のスキルは10行にも満たない簡素なものでした。それが今では、チームの開発プロセスに欠かせない存在になっています。完璧を目指すのではなく、日々の作業の中で「これ、またプロンプト書き直しているな」と感じた瞬間が、スキルを作るベストなタイミングです。

aduceでは、Claude Codeをはじめとする最新のAI技術を活用した開発支援を行っています。AI駆動の開発プロセス構築やDX推進にご関心がありましたら、aduceのお問い合わせはこちらからお気軽にご相談ください。