Claude Code Skills入門｜SKILL.mdでチームの手順を再利用する方法

Claude Codeを使い続けると、毎回同じ前提や手順を説明していることに気付きます。「このリポジトリでは先にテストをする」「PRではこの観点を確認する」「画像を作ったらこの形式で検証する」といった繰り返しです。これを会話のたびに貼り付ける代わりに、再利用できる手順としてまとめる仕組みが Claude Code Skills です。

Skillsは単なる長いプロンプト置き場ではありません。必要な場面で読み込まれる知識・手順・補助ファイルを、目的ごとに小さくパッケージ化します。うまく使うと、プロジェクト固有の作法を保ちながら、日常の調査、実装、レビュー、リリース準備を安定させられます。一方で、万能ルールを1つのSkillに詰め込みすぎると、かえって判断が固くなり、実行してはいけない操作まで自動化しかねません。

この記事では、既存の「Claude Codeのスラッシュコマンド一覧」とは別に、Skillsを設計・配置・運用する考え方を解説します。スラッシュコマンドを覚える記事ではなく、チームの再利用可能な仕事の型をどう作るかがテーマです。

この記事の結論

• SkillはSKILL.mdを入口にした、必要なときだけ読み込む知識・手順のパッケージ
• 常に守る事実はCLAUDE.md、外部ツール接続はMCP、特定手順はSkillに分ける
• 最初は読み取り・検証中心の1手順から作り、書き込みや公開は明示確認を残す
• Skillの成功は「長さ」ではなく、同じ作業で迷いと手戻りが減ったかで測る

本文図1：常時コンテキスト、必要時に読み込むSkill、外部接続、実行担当を役割ごとに分ける。

Claude Code Skillsとは

Claude Code Skillsは、SKILL.mdを中心にした再利用可能な能力の単位です。Skillには説明文と手順を書き、必要ならテンプレート、詳細な参照資料、検証スクリプト、例も同じディレクトリへ置けます。Claudeは依頼内容と説明文が合うとSkillを利用でき、利用者が/skill-nameの形で明示的に呼び出すこともできます。

ここで重要なのは、Skill本文が常に会話へ読み込まれるわけではないことです。常時必要な事実をすべて詰め込むより、特定の作業でだけ必要になる長いチェックリストや手順をSkillへ分ける方が、普段の会話を軽く保てます。たとえば「このプロジェクトの言語はTypeScript」のような常識は常時設定へ、「デプロイ前に行う8項目」はrelease-check Skillへ置く、といった分け方です。

まず整理したい4つの置き場所

Claude Codeには似た役割に見える設定がいくつかあります。選び方を間違えると、毎回不要なルールが読み込まれたり、逆に重要な手順が抜けたりします。

CLAUDE.mdは「毎回の前提」

リポジトリ構成、テストコマンド、命名規則、絶対に変更してはいけないディレクトリのように、ほぼすべての作業で必要な情報はCLAUDE.md向きです。ここへ「週次レポートを作る方法」まで入れると、バグ修正をしているだけなのに長い運用手順を毎回読むことになります。

Skillは「必要なときの仕事の型」

Skillは、たとえば次のような反復作業に向いています。

• リリース前の差分確認とチェックリスト作成
• API変更時の互換性調査とテスト追加
• 記事の下書き、画像、プレビュー検証
• データ分析の再現可能な初期化
• 障害報告を事実・仮説・次の検証に分ける

重要なのは、Skillを「答えを固定するもの」ではなく「確認順序を固定するもの」として使うことです。技術選定や製品仕様が毎回変わるなら、結論をSkillへ埋め込まず、公式資料を調べる順番と判断条件を入れます。

MCPは接続、Skillは運用

MCPを使うと、検索、チケット作成、データ取得などのツールをClaude Codeへ接続できます。しかし、MCPサーバーは「何を、どの順番で、どこまで実行してよいか」を決めません。そこを決めるのがSkillやプロジェクトの運用ルールです。

たとえばGitHubのMCPがあっても、どのブランチへPRを出すか、レビュー前に何を検証するか、マージを誰が決めるかは別問題です。MCPを増やす前に、読取り、下書き、外部書込み、公開のどこまでを自動で進めるかを決めましょう。

SKILL.mdの最小構成

最小のSkillは、名前・説明・実行時の指示だけで始められます。ディレクトリ名が、利用者が呼ぶコマンド名の基本になります。

---
name: review-api-change
description: APIの変更が依頼されたときに、利用箇所・互換性・テストを確認する。
---

# API変更レビュー

1. 変更対象の公開APIと利用箇所を検索する。
2. 互換性が崩れる入力・出力・例外を列挙する。
3. 既存テストと不足ケースを分ける。
4. 実装前に、変更しない範囲と検証方法を短く示す。

この例の価値は、API変更の「正解」を決めていることではありません。毎回忘れがちな利用箇所と互換性を、実装の前に確認する順番を持たせていることです。プロジェクトに合わせて、参照すべきディレクトリ、必須テスト、レビュー観点を足します。

Pythonのコードを生成・実行するSkillなら、実行前に構文チェック、依存関係の確認、外部書込みの有無を入れます。Pythonの最小コード例は次のようにASTで検証できます。

from __future__ import annotations

import ast

def validate_python(source: str) -> None:
    """実行前に構文エラーを早く見つける。"""
    ast.parse(source)

構文が通ることは安全な実行を保証しませんが、Markdownのコードブロックをそのまま使う場面では、最低限の早期検査になります。

Skillを置く3つの場所

公式ドキュメントでは、Skillは個人、プロジェクト、Pluginという単位で置けます。どこへ置くかは、誰と共有するかで決めます。

個人Skill：自分の反復作業を速くする

個人用の~/.claude/skills/<skill-name>/SKILL.mdは、複数リポジトリで使う自分の作業習慣に向いています。たとえば「調査メモを一次資料と仮説に分ける」「変更前にgit statusとテストを確認する」といった、特定チームの判断を含まない手順です。

ただし、会社固有のURL、顧客名、秘密のAPI仕様を個人Skillへ混ぜないようにします。持ち運べるSkillほど、環境固有の情報は薄くします。

プロジェクトSkill：チームで再現する

.claude/skills/<skill-name>/SKILL.mdは、リポジトリと一緒にレビュー・バージョン管理できるため、チームの手順に向いています。デプロイ前チェック、データ移行の手順、テスト方針、コンテンツ制作フローなどは、コードの変更と同じPRで見直せます。

プロジェクトSkillは「ドキュメントだからレビュー不要」ではありません。むしろ実行手順であるため、権限を広げる命令、削除コマンド、外部送信先、秘密情報の扱いをコードと同じようにレビューします。

Plugin Skill：配布可能な部品にする

複数チームや複数プロジェクトへ配る場合は、Pluginにまとめる方法があります。PluginはSkillだけでなく、MCP設定、エージェント、Hookなども同梱できます。Skill名がPlugin名で名前空間化されるため、別のSkillと衝突しにくいのも利点です。

一方で、Plugin化は最初から必要ではありません。まだ一つのリポジトリでしか使っていない手順は、まずプロジェクトSkillとして育てます。3つ以上の場所で同じ構成を保ちたくなった段階で、Plugin化を検討すると過剰設計を避けられます。

本文図2：共有範囲と変更頻度で、個人Skill、プロジェクトSkill、Plugin Skillを選ぶ。

良いSkillを作る5つの原則

1. 入口の説明を具体的にする

Skillの説明は、いつ使うかを伝える入口です。「便利な開発支援」では広すぎます。「公開APIの変更、SDKの更新、互換性調査を依頼されたときに使う」のように、対象と目的を具体的にします。説明が曖昧だと、必要なときに選ばれず、不要なときに読み込まれます。

2. 手順は短く、詳細は参照ファイルへ逃がす

SKILL.mdへ全仕様を貼り込むと、利用時の理解コストが上がります。入口には判断順序と完了条件を書き、細かなAPI一覧、長いスタイルガイド、事例集はreferences/のような別ファイルへ置きます。どの状況で読むかも明記すると、必要な情報だけを使えます。

3. 成果物の形を先に決める

「調査する」だけでは終わり方が人によって変わります。たとえば調査Skillなら、結論、根拠URL、未確認点、次の検証を返すと決めます。実装Skillなら、変更ファイル、検証コマンド、残るリスクを返すと決めます。

成果物の形式を決めても、内容の結論まで固定する必要はありません。むしろ変動する仕様については、確認日と一次資料を必須にし、古いSkill本文を現在仕様として扱わないようにします。

4. 危険な操作はSkillに自動実行させない

外部公開、削除、購入、権限変更、秘密情報の送信は、便利なSkillであっても別の確認境界に残します。Skillの中にgit push --forceや本番データ削除のような操作を含めるなら、対象・影響・復旧方法を確認する段階を明示し、通常の依頼から自動で通らない設計にします。

特に「失敗したら再試行する」という指示は注意が必要です。外部APIの作成操作では、一度成功したのに応答だけ失われることがあります。再試行前に作成済みかを検索し、リクエストIDや実行履歴で重複を防ぐ手順を置きます。

5. 例外と停止条件を書く

良いSkillは、進め方だけでなく、止まる場所も書いています。認証が切れた、前提データが不足した、既存成果と重複する、費用が発生する、目的が途中で変わった、といったときは停止して確認へ戻します。

停止条件は多すぎると何も進まなくなります。日常的な下調べ・整形・検証は自動で進め、外部への影響や目的変更だけを止める、といった粒度が実用的です。

実例：レビューSkillを育てる流れ

最初の版では、git diffを読み、危険な変更と不足テストを3点以内で返すだけにします。これでチームが毎回同じ観点を必要としているか確認できます。

次に、認証、入力検証、DBクエリ、外部HTTP、ファイル操作が変わった場合だけ、追加の確認項目を出すようにします。すべてのPRへ長大なセキュリティ質問票を出すのではなく、変更の種類に応じて深さを変えるのがポイントです。

最後に、CI結果や差分統計を参照する補助スクリプトを追加します。ただし、Skillが自動でマージ・デプロイまで行う必要はありません。レビューで得た事実を整理し、誰が判断すべきかを明確にするところまでで十分に価値があります。

Skillを保守するためのレビュー観点

Skillもコードと同じように古くなります。使い始めは有効だったコマンドやパスが、リポジトリ構成の変更後には誤った対象を指すことがあります。半年に一度の大掃除を待つより、関連するコードや運用が変わるPRの中で、近いSkillを一緒に見直す方が現実的です。

まず、Skillの説明が実際の利用場面と一致しているかを確認します。説明が「デプロイを安全に行う」なのに、本文がローカルのビルドしか扱わないなら、利用者はどこまで実行されるのか判断できません。目的、非対象、停止条件を短く揃えます。

次に、参照するファイルやコマンドを実際に検証します。存在しないパス、古いテスト名、廃止済みの環境変数を放置すると、Skillは誤った自信を与えます。実行するコマンドがある場合は、読み取りだけか、ローカル変更を伴うか、外部書込みを伴うかを区別します。後者は特に、通常の流れで暗黙実行されないようにします。

最後に、Skillを使った結果を1件だけ振り返ります。想定より長い出力になった、必要な確認が抜けた、毎回同じ例外が起きた、といった事実から、本文を増やすのではなく順序や完了条件を直します。Skillは規約集ではなく、実行から学習して少しずつ整える運用資産です。

ありがちな設計ミスと直し方

一つの巨大Skillに全業務を入れる。 入口が広すぎると、調査だけの依頼にもデプロイ手順や公開判断が混ざります。目的別に分け、共通部分は短い参照資料へ出します。

特定のモデルやツールの現在仕様を本文へ固定する。 CLIのオプションや製品機能は変わります。Skillには「公式ドキュメントを確認する」を書き、本文に書く具体例には確認日を残します。

安全のために停止条件を増やしすぎる。 ファイル検索やテスト実行まで毎回確認すると、Skillを使う意味が薄れます。日常の内部作業は進め、公開、課金、削除、権限、秘密情報、目的変更だけを明確な境界にします。

実行結果を残さない。 Skillが何を調べ、どのテストを実行し、何を人間へ返したかを短く残すと、次回の改善材料になります。完璧な監査システムを最初から作る必要はありませんが、成果物と次の一手が追えることは大切です。

最初の1本を選ぶヒント

初めてのSkillには、週に何度も行い、結果を見れば正誤を判断しやすい作業を選びます。たとえば「変更したPythonファイルをASTで検証し、関連テスト候補を一覧化する」「記事原稿の画像プレースホルダーと作業用語を検索する」といった作業です。こうしたSkillは、外部サービスを変更せずに効果を測れます。

逆に、組織の優先順位を決める、顧客へ送る、売買する、公開する、といった作業を最初のSkillにするのはおすすめしません。判断材料を集めるSkillから始め、実行部分は人間の確認を挟む別工程として残します。小さな成功を一つ積むと、次にどこまで自動化してよいかを実際の手戻りから決められます。

Skillを導入した直後は、利用回数よりも「同じ説明を何回省けたか」「確認漏れが減ったか」を観察します。使われないSkillは、名前が悪い、入口の説明が曖昧、手順が重すぎる、または本当に反復作業ではない可能性があります。理由を分けて、小さく修正します。

定期的な見直しでは、使われなかった項目を削る勇気も必要です。短く、正確で、次の判断を助けるSkillほど長く残ります。

最初の版を完成品と見なさず、実行ログと利用者のフィードバックを材料に、次の一手だけを改善していきましょう。

その積み重ねが、チームの知識を会話の中で安全に再利用できる形へ変えていきます。

導入前チェックリスト

• □ Skillの目的を1文で説明できる
• □ CLAUDE.mdへ置く常時ルールと分けている
• □ 入力、出力、完了条件が分かる
• □ 変動する仕様は公式資料を確認する手順がある
• □ 長い資料を必要時だけ読む構成にしている
• □ 外部書込み・公開・削除を自動通過させない
• □ 認証切れ、重複、目的変更の停止条件がある
• □ 生成コードは実行前に検証する
• □ Skillの変更もPRでレビューできる
• □ 利用後に手戻りが減ったかを振り返る

まとめ：Skillは「AIに任せる範囲」を小さく、繰り返し可能にする

Claude Code Skillsの狙いは、長い指示を保存することではありません。毎回の作業で迷う場所を減らし、調査・実装・検証・人間判断の境界を再利用できる形にすることです。

まずは一つの反復作業を選び、入力、確認順序、成果物、停止条件を短いSKILL.mdへ書いてください。個人だけで使うなら個人Skill、チームで守るならプロジェクトSkill、複数の環境へ配るならPluginへ進めます。使うたびに長くなるSkillではなく、参照先を整理して判断が速くなるSkillを目指すと、AIコーディングの品質を安定させやすくなります。

Claude Codeのコマンド自体を確認したい場合は「Claude Codeのスラッシュコマンド一覧」、イベントに応じた自動化は「Claude Code Hooks入門｜イベント別の自動化と安全な運用」も参照してください。

参考資料

• Extend Claude with skills（Anthropic）
• Features overview（Anthropic）
• CLI reference（Anthropic）