Claude Code のスキル：作り方と例、ベストプラクティス

Claude Code のスキルとは

同じ指示やチェックリスト、複数ステップの手順を何度もチャットに貼り付けているとき、あるいは CLAUDE.md の一部が事実の記述から手順へと膨らんできたときが、スキルを作るタイミングです。スキルはオープンな Agent Skills 標準（agentskills.io）に準拠しており、ほかの AI ツールも読み込めます。Claude Code はそこに、起動の制御、サブエージェントでの実行、プロンプトへのシェル出力の埋め込みといった機能を加えています。

• 実行方法は2つあります。依頼内容が description と一致したときに Claude が読み込むか、自分で /skill-name と入力します。
• 使うまではほとんどコストがかかりません。コンテキストに入るのは名前と説明だけで、本文はスキルの実行時に読み込まれます。手動でのみ実行するよう設定したスキルは、説明すら一覧に載りません。
• カスタムスラッシュコマンドはスキルになりました。.claude/commands/<name>.md も引き続き動きますが、スキルのフォルダには補助ファイルも置けます。詳しくは Claude Code のスラッシュコマンドをご覧ください。
• Claude Code には /simplify、/loop、/batch、/debug などのバンドルスキルも同梱されています。

スキル、CLAUDE.md、サブエージェント、プラグイン、MCP の違い

Claude Code のスキルの作り方

1. 置き場所を決める

   自分がすべてのプロジェクトで使うなら ~/.claude/skills/<name>/、そのリポジトリで作業する全員で使うなら、リポジトリの .claude/skills/<name>/ に置いてコミットします。フォルダ名がそのままコマンドになり、summarize-changes なら /summarize-changes です。

2. SKILL.md を書く：まず説明、次に指示

   frontmatter はファイルの一番上、--- の行で囲んだ中に書きます。推奨されている項目は description だけです。用途と、ユーザーが実際に口にしそうな言葉を先頭に書きましょう。その下に、指示を Markdown で書きます。` !command ` で始まる行は、そのコマンドを先に実行して出力を貼り込むので、スキルが実際の状態をもとに動けます。

   ---
   description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
   ---
   
   ## 現在の変更
   
   !`git diff HEAD`
   
   ## 指示
   
   上の変更を2〜3個の箇条書きでまとめ、エラー処理の漏れ、ハードコードされた値、
   更新が必要なテストなど、リスクになりそうな点を挙げてください。

3. 両方の方法で試す

   未コミットの変更がある git プロジェクトで claude を起動します。「何を変更した？」と聞いて Claude が自分でスキルを使うかを確かめ、次に /summarize-changes と入力して直接実行します。セッション中に追加したスキルは自動で読み込まれます。表示されない場合は /reload-skills を実行してください。

4. 誰が実行できるかを決める

   デプロイやメッセージ送信など副作用のあるものには disable-model-invocation: true を追加し、自分だけが起動できるようにします。Claude だけが読み込むべき背景知識には user-invocable: false を追加します。入力を渡すには、スラッシュコマンドのガイドで紹介したとおり $ARGUMENTS を使います。

5. 共有する

   .claude/skills/ をリポジトリにコミットするか、複数のリポジトリやチームで使うならスキルをプラグインとしてパッケージします。

出典：Claude Code ドキュメント、Extend Claude with skills

Claude Code のスキルの例

1. 一致するファイルのときだけ読み込まれる参照スキル

   参照スキルには、Claude が作業中に適用する規約を書きます。paths を指定すると、自動で読み込まれるのは glob に一致するファイルを扱うときだけになります。

   ---
   description: API design conventions for this codebase. Use when writing or reviewing HTTP endpoints.
   paths: ["src/api/**"]
   ---
   
   API エンドポイントを書くとき：
   - RESTful な名前と複数形のリソース名を使う
   - エラーは { error: { code, message } } の形で返す
   - リクエストボディは src/api/schemas/ のスキーマで検証する

2. 補助ファイルを持つタスクスキル

   SKILL.md は短くまとめ、残りはほかのファイルを指し示します。Claude は SKILL.md の指示があったときだけ checklist.md を読み、bump.sh は読まずに実行するので、詳細は必要になるまでコストがかかりません。

   release/
   ├── SKILL.md          # 手順と、ほかのファイルを読むタイミング
   ├── checklist.md      # SKILL.md が指示したときだけ読み込まれる
   └── scripts/
       └── bump.sh       # 実行されるだけで、コンテキストには読み込まれない

3. 専用のサブエージェントで動くスキル

   context: fork は、スキルをプロンプトとしてサブエージェント（ここでは読み取り専用の Explore タイプ）を起動します。サブエージェントはあなたの会話を見られないので、指示はそれだけで完結している必要があります。background: false を設定しない限り、バックグラウンドで実行されます。

   ---
   description: Audit dependencies for known vulnerabilities and outdated majors
   context: fork
   agent: Explore
   disable-model-invocation: true
   ---
   
   パッケージマネージャーの audit を実行し、high または critical の指摘をすべて
   修正バージョンとともに挙げ、遅れているメジャーバージョンを報告してください。ファイルは変更しないこと。

プラグインとマーケットプレイスからスキルをインストールする

他人が書いたスキルは、たいていプラグインに入って届きます。Claude Code は初めて対話セッションを起動したときに Anthropic の公式マーケットプレイス（claude-plugins-official）を登録します。/plugin で一覧を見るか、/plugin install skill-creator@claude-plugins-official のように直接インストールできます。チームやコミュニティのマーケットプレイスは、先に /plugin marketplace add owner/repo で追加します。

• プラグインのスキルは /plugin-name:skill-name という名前になります。
• 公式マーケットプレイスでは、各プラグインのターンごとのコンテキストコストと、呼び出したときのコストが表示されます。
• skill-creator プラグインはスキルの作成を手伝い、スキルがある場合とない場合の結果を比べる評価も実行します。
• リポジトリやプラグインのスキルは、信頼する前に中身を読みましょう。allowed-tools は、スキルが実行されるターンのツールを事前承認できます。

ベストプラクティスと、Claude がスキルを使わないとき

• 説明はマッチングのために書きます。仕事の内容とユーザーが使う言い回しを先頭に置きましょう。一覧では、説明と when_to_use を合わせて1,536文字で切り詰められます。
• 最も重要な指示は上のほうに書きます。会話が圧縮されると、Claude Code は呼び出したスキルの冒頭だけを残すことがあります。その場合はもう一度呼び出せば元に戻ります。
• スキルのファイルは後のターンで読み直されないので、タスク全体に関わる指示（「編集のたびにテストを実行する」など）として書きましょう。絶対に省略してはいけないルールはフックに置きます。
• トークン使用量を減らすには、手順を CLAUDE.md からスキルに移し、手動で実行するスキルには disable-model-invocation: true を設定し、/skill-doctor でコンテキストを使うわりにあまり使われていないスキルを確認します。
• 起動しない場合は、説明に適切なキーワードがあるかを確認し、「使えるスキルは？」と聞き、claude plugin validate .claude/skills を実行して解析できない frontmatter を探します。
• 起動しすぎる場合は、説明を絞り込むか、disable-model-invocation: true で手動実行に切り替えます。

スキルは Claude Code にやり方を教え、Crewmark は毎時間やるべき仕事を与えます。

スキルのライブラリがあれば各セッションは有能になりますが、それでもあなたの依頼を待っています。Crewmark は、Claude Code、Codex、DeepSeek Harness、OpenCode のセッションを、職種・目標・勤務時間を持つ AI 社員に変え、ハートビートで起こしてボードから次の issue を取らせます。プロジェクトのスキルも読み込まれた状態です。

1. スキルはリポジトリに置いておく

   社員のセッションは、あなたのセッションと同じように .claude/skills/ と CLAUDE.md を読み込むので、リリース用のスキルやレビューのチェックリストもそのまま引き継がれます。

2. ハートビートで仕事を始めさせる

   勤務時間中、社員は15分、30分、60分ごとに同じ会話の中で起き、次の issue を取ります。Claude Code を能動的にする方法もご覧ください。

3. issue を割り当て、メッセージに答える

   ボードに仕事を置くと、社員は進捗をコメントし、判断が必要なときはメッセージを送ってきます。AI 社員とはもご覧ください。

Claude Code のスキルのよくある質問