Claudeスキル作成の実践ガイド：構造、トリガー、スクリプト

Claude Skillsとは何か、そしてその仕組み

Claude Skillsは、特定のタスクを自動化する手順書であり、プロジェクト（知識ベース）やModel Context Protocol（ライブデータ用の接続層）とは異なります。3回以上の会話の冒頭で同じ指示を入力したことがあるなら、それは構築すべきスキルです。

スキルの構造とセットアップ

スキルは、SKILL.mdという1つのファイルを含むフォルダです。基本的な構造は以下の通りです：

your-skill-name/
├── SKILL.md
└── references/
    └── your-ref.md

このフォルダをマシンの~/.claude/skills/に配置します。Claudeは自動的に見つけます。

YAMLトリガー：アクティベーション機構

SKILL.mdの先頭に、Claudeにいつアクティブにするかを指示するメタデータを---行の間に記述します。例：

---
name: csv-cleaner
description: 乱雑なCSVファイルをきれいなスプレッドシートに変換します。ユーザーが「このCSVをクリーンアップして」「ヘッダーを修正して」「このデータをフォーマットして」「このスプレッドシートを整理して」と言ったときにこのスキルを使用します。PDF、Word文書、画像ファイルには使用しないでください。
---

3つのルールに従います：三人称で記述し、正確なトリガーフレーズをリストアップし、否定的な境界を設定します。descriptionフィールドはスキル全体で最も重要な行です—弱い説明ではスキルは発動しません。

指示だけでは不十分な場合：スクリプトディレクトリ

平易な英語の指示は、判断、言語、フォーマット、決定を扱います。実際の計算が必要なタスクには、scripts/フォルダを追加します。

指示を使用する例：「これを私たちのブランドボイスで書き直して」または「これらの会議メモを分類して」

スクリプトを使用する例：「これらの数値の移動平均を計算して」「このXMLを解析して特定のフィールドを抽出して」「このフォルダ内のすべての画像を800x600にリサイズして」

両方を使用するスキルのフォルダ構造：

data-analyser/
├── SKILL.md
├── references/
│   └── analysis-template.md
└── scripts/
    ├── parse-csv.py
    └── calculate-stats.py

SKILL.md内で、スクリプトを以下のように参照します：

## ワークフロー
1. アップロードされたCSVファイルを読み、構造を理解します。
2. scripts/parse-csv.pyを実行してデータをクリーンアップします：
   - コマンド：`python scripts/parse-csv.py [input_file] [output_file]`
   - これにより、空の行の削除、ヘッダーの正規化、データ型の強制が行われます。
3. クリーンアップされたデータに対してscripts/calculate-stats.pyを実行します：
   - コマンド：`python scripts/calculate-stats.py [cleaned_file]`
   - これにより、各数値列の平均、中央値、標準偏差、外れ値が出力されます。
4. 統計出力を読み、references/analysis-template.mdのテンプレートに従って人間が読める要約を作成します。非技術的な読者が懸念する可能性のある異常や外れ値を強調します。

スクリプトは計算を扱い、指示は判断を扱います。スクリプトのための1つのルール：1つのスクリプト、1つの仕事。parse-csv.pyは統計も計算すべきではありません。焦点を絞り、引数としてファイルパスを受け取り、パスをハードコードせず、常にエラーハンドリングを含めて、Claudeが失敗を読み取り、きれいに伝えられるようにします。

リファレンス：1レベル深さのルール

スキルにブランドガイドやテンプレートが必要な場合は、references/に配置し、SKILL.mdからリンクします。リファレンスファイルが他のリファレンスファイルにリンクすることは絶対にありません—Claudeは読み取りを切り詰め、見逃します。1レベル深さのみです。

your-skill-name/
├── SKILL.md
└── references/
    └── brand-voice-guide.md ← SKILL.mdからこれにリンク ← ここから他のファイルにリンクしない

SKILL.md内：タスクを開始する前に、references/brand-voice-guide.mdのブランドボイスガイドを読んでください

複数スキルのオーケストレーション：競合の防止

5つ以上のスキルをデプロイすると、競合が始まります—例えば、ブランドボイス強化スキルが、メール作成スキルを望んでいたときに発動するなど。これを防ぐ3つのルール：

• ルール1：重複しない領域。すべてのスキルは明確に定義されたドメインを所有します（例：ブランドボイス強化スキルはボイス準拠を扱い、メール作成スキルは構成を扱い、コンテンツ再利用スキルはフォーマット変換を扱います）。重複なし。
• ルール2：積極的な否定的境界。