🥷

Claude Code Skills 構築完全ガイドとその先へ

に公開
AI
Model Context Protocol
Claude
Skills
Agent Skills
tech

1. Claude Skillsとは何か？（Projects, MCPとの違い）

https://zenn.dev/dragon1208/articles/1731ae05f032de

Claudeを活用する際、用途に応じて以下の3つのツールを使い分ける必要があります。

  • Projects: あなたのナレッジベースです。ブランドガイドラインや仕様書などをアップロードし、「これを知っておいて」と伝える静的なライブラリです。
  • Skills: 今回の主題となる手順化された自動化マニュアルです。「このタスクをステップバイステップでこのように実行して」と指示を与え、特定の分野に特化した「従業員」を作り上げます。
  • MCP (Model Context Protocol): カレンダー、データベース、受信トレイなどのライブデータソースとClaudeを接続するレイヤーです。Skillsは、このMCPが取得したデータを「どう扱うか」を指示する役割を持ちます。

過去に3回以上同じ指示をプロンプトに入力したことがあるなら、 それはSkill化すべきタスクです。

2. Skillの基本構造と配置場所

Skillの実態は、特定のルールに従って作成された 「フォルダとテキストファイル」 にすぎません。

実行環境と配置場所

  • Claude Code（開発者向けCLIツール）: ファイルシステムやBashコマンドにアクセスし、コードを実行できます。Skillはプロジェクトルートの .claude/skills/ またはグローバルの ~/.claude/skills/ に配置します。
  • Claude Desktop / CoWork（非開発者向けエージェント）: 画面やアプリケーションを操作します。

ディレクトリ構成

ルートフォルダ名は必ず**kebab-case（小文字、ハイフン区切り）**にする必要があります（例: csv-cleaner）。スペース、アンダースコア、大文字は使用不可です。

最も重要なファイルは SKILL.md です。大文字・小文字は厳密に区別され、すべての指示はこのファイルに記述します。

3. Skillの構築ステップ

Step 1: タスクの解像度を上げる

「データを助けて」のような曖昧な定義は役に立ちません。「乱雑なCSVをクリーンなスプレッドシートに変換し、日付をYYYY-MM-DDに強制し、空行を削除する」といったように、入力と出力の具体的な状態 と、起動条件となるトリガー を極めて具体的に定義します。

Step 2: YAMLトリガーの記述（フロントマター）

SKILL.md の最上部には、Skillを発火させるタイミングをClaudeに伝えるYAMLフロントマターを --- で囲んで記述します。

【重要ルール】

  1. 三人称で書く: "I can help you..." ではなく "Processes files..." と記述します。
  2. 具体的なトリガーフレーズを列挙する: ClaudeはSkillの起動に対して保守的です。「ユーザーがXやYと言った時に起動せよ」とより詳細に 記述する必要があります。
  3. ネガティブバウンダリ（非起動条件）を設定する: 「PDFやWordファイルには使用しないこと」など、関係ないタスクで誤発火するのを防ぎます。
---
name: csv-cleaner
description: Transforms messy CSV files into clean spreadsheets. Use this skill whenever the user says 'clean up this CSV', 'fix the headers', 'format this data', or 'organise this spreadsheet'. Do NOT use for PDFs, Word documents, or image files.
---

(実際のYAMLフロントマターの記述例)

Step 3: インストラクション（命令）の記述

YAMLの下に、ワークフローを平易な英語（または日本語）で記述します。全体で500行以内に収めます。

  • ステップ化と命令形: 「ファイルが読み込まれるべき」ではなく「ファイルを読め」と明確な命令形（Imperative command）で、単一のアクションごとにステップを分けます。
  • 具体例（Examples）の提示: 抽象的な説明より、具体的なInputとExpected Outputの例を「正常系」と「エッジケース」で最低2つ記述します。

Step 4: 参照ファイル（References）の「1階層ルール」

巨大なコーディング規約やテンプレートは SKILL.md に直接書かず、references/ フォルダに切り出して「作業開始前に references/style-guide.md を読め」と指示します。
ここで絶対に守るべきなのが 「One Level Deep Rule」 です。参照ファイルの中から別の参照ファイルへリンクしてはいけません。これを破ると、Claudeは読み込みを途中で打ち切り、重要な情報を欠落させます。

また、これと合わせて迎合性の逆利用を組み込むテクニックも、使い慣れてきたらでいいと思いますが、かなり効果的で使えるテクニックですので是非取り入れて欲しいところです。

https://zenn.dev/dragon1208/articles/92473507755e78

4. エンジニア向け高度なアーキテクチャ

言語モデルとスクリプトの役割分担

LLMは言語の処理、フォーマット変換、判断には優れていますが、正確な計算やファイル操作には不向きです。そのため、判定・言語処理はSkillの指示で、計算・データ変換はPythonスクリプト等で行うハイブリッド構成が推奨されます。

【実践コード例】SKILL.md でのスクリプト呼び出し
スクリプトはハードコードされたパスではなく、引数を受け取るように設計し、エラーが発生した場合はClaudeがパースできる明確なエラーメッセージを出力するようにします。

## Workflow
1. アップロードされたCSVファイルの構造を読み取る。
2. データをクリーンにするため、以下のスクリプトを実行する:
   * Command: `python scripts/parse-csv.py [input_file] [output_file]`
   * これにより空行が削除され、データ型が強制される。
3. クリーンなデータに対して統計を計算する:
   * Command: `python scripts/calculate-stats.py [cleaned_file]`
   * 出力: 各数値カラムの平均、中央値、標準偏差、外れ値。
4. 統計出力を読み取り、`references/analysis-template.md` のテンプレートに従って人間が読めるサマリーを作成する。非技術者が懸念するような外れ値があれば強調すること。

(指示とスクリプトが連携するワークフローの実例)

複数Skillのオーケストレーションと競合回避

複数のSkillを作成すると、「コードのフォーマットだけをしてほしいのに、コードレビューのSkillが発火してしまった」といった競合が発生します。これを防ぐための3原則です：

  1. 領域の非重複: 各Skillの担当ドメインを明確に分ける。
  2. 攻撃的なネガティブバウンダリ: メール作成Skillには「ブランドボイスのチェックには使用しないこと」と他Skillの領域を明示的に除外する記述をYAMLに加えます。
  3. 固有のトリガー言語: 各Skillの発火フレーズが他と被らないように設計します。

5. テストとデバッグ：5つの「Failure Modes」

作成したSkillがうまく動かない場合、原因は以下の5つのいずれかです。特定して修正します。

症状（Failure Mode） 原因 対策
1. The Silent Skill
（全く発火しない）		 YAMLの定義が弱く、発火の閾値を超えていない。 description にユーザーが入力した正確なフレーズを追加し、より「押しつけがましく」する。
2. The Hijacker
（無関係な指示で発火する）		 YAMLの定義が広すぎる。またはネガティブバウンダリがない。 「〜の用途には使用しないこと（Do NOT use for...）」という除外条件を追記する。
3. The Drifter
（出力結果が微妙に間違っている）		 指示文に解釈の余地があり、曖昧。 「いい感じにフォーマットして」を「各セクションにH2タグを使用し、段落は3行以内」等、テスト可能な明確な指示に書き換える。
4. The Fragile Skill
（エッジケースで壊れる）		 不完全なデータなどの異常系に対する条件分岐が欠如している。 「もし[条件]の場合は、[特定のアクション]を実行せよ」と明示的なエッジケース指示を追加する。
5. The Overachiever
（頼んでいない解説やコードまで足す）		 Claudeに「何をすべきか」は伝えたが、「何をすべきでないか」を伝えていない。 「ユーザーに求められない限り、解説や提案を追加しないこと。指定されたフォーマットのみを出力せよ」とスコープの制約を追加する。

EvalsやBenchmarks、A/B Comparatorなどのテストフレームワークを活用し、これらの改修が実際に通過率の向上やトークン消費（コスト）の削減に繋がっているかをデータで証明します。

6. 本番環境での運用：セッションをまたぐ「状態管理」

数週間にわたる複雑なアプリ開発などを行う際、Claudeのコンテキストウィンドウはいずれ上限に達し、過去の出来事を忘れてしまいます。

慣れてきたら SKILL.md に以下の指示を1文追加し、「シフトの引き継ぎ」 システムを構築などするといいでしょう。

"毎回のセッション開始時に context-log.md を読み込み、前回どこまで完了したかを確認すること。また、毎回のセッション終了時には、完了した作業と保留中のタスクのサマリーを同ファイルに書き込むこと。"

これにより、Claudeは自身が残したカルテを読んで、前回のセッションの続きから正確に作業を再開できるようになります。

日々のプロンプト入力をSkill化することで、Claudeは単なるチャットボットから、あなた専用にチューニングされたシステムへと進化します。まずは最も繰り返しているタスクを一つ選び、構築を始めてみてください。

Discussion