creating-skill

スキルの作成

さまざまなコンテキストで Claude の機能を拡張する、移植可能で再利用できる専門知識を作成します。

スキルを作成するタイミング

次の場合にスキルが適しています。

• 複数のプロジェクトや会話で必要となる機能
• 広く適用できる手続き的な知識（特定のプロジェクトに依存しないもの）
• トリガーパターンに応じて指示を自動的に適用する必要がある場合
• 必要に応じて段階的に読み込まれる、移植可能な専門知識が必要な場合

次の場合には適していません。

• コンテキストがプロジェクト固有の場合（代わりにプロジェクトの指示を使用してください）
• 1回限りのタスクの場合（代わりに単独のプロンプトを使用してください）
• 詳しい判断基準については crafting-instructions スキルを参照してください

スキルの構成

各スキルは、次の内容を含むディレクトリです。

• SKILL.md（必須）：フロントマターと命令形の指示
• scripts/（任意）：決定的な操作を行う実行可能コード
• references/（任意）：必要に応じて読み込む詳細ドキュメント
• assets/（任意）：出力に使用するテンプレートやファイル

この構成を直接作成します。

mkdir -p skill-name/{scripts,references,assets}

パッケージ化する前に、使用しないディレクトリを削除します。

命名規則

動名詞の形（動詞 + -ing）を使用します。

• ✅ processing-pdfs、analyzing-data、creating-reports
• ❌ pdf-helper、data-tool、report-maker

要件：

• 小文字、数字、ハイフンのみを使用
• 64 文字以内
• 予約語（anthropic、claude）は使用しない

フロントマターの要件

---
name: skill-name
description: What it does. Use when [trigger patterns].
---

name： 上記の命名規則に従います

description：（最大 1024 文字）

• 三人称で記述します。「I process files」ではなく「Processes files」
• 何を行うか、いつ使用するか（トリガーパターン）を記述します
• このスキルを有効にするファイルの種類、キーワード、タスクの種類を明記します
• XML タグは使用しません

良い例：

• 「PowerPoint プレゼンテーションを作成します。ユーザーがスライド、.pptx ファイル、またはプレゼンテーションに言及したときに使用します。」
• 「SQL クエリのパフォーマンスを分析します。遅いクエリのデバッグ、最適化の依頼、または EXPLAIN の出力を扱うときに使用します。」

効果のない例：

• 「プレゼンテーションの作成をお手伝いできます」（一人称で、トリガーがありません）
• 「プレゼンテーション作成ツール」（トリガーがなく、何をするか曖昧です）
• 「アニメーション付きの高度なプレゼンテーション作成」（実装の詳細が多すぎます）

description は重要です。Claude がこのスキルをいつ有効にするかを決定します。

効果的な SKILL.md の作成

crafting-instructions の原則を適用します。

命令形で記述する

直接的な命令として記述します。

• ✅ 「pdfplumber でテキストを抽出する」／「スクリプトで出力を検証する」
• ❌ 「テキストの抽出を検討する……」／「出力を検証するとよいかもしれません……」

手順よりも方針を重視する

手順を逐一示すのではなく、目標と判断基準を指定します。

• ✅ 「スキルのディレクトリ構成を作成する。使用しないリソースディレクトリを削除する。」
• ❌ 「手順 1：mkdir skill-name。手順 2：mkdir scripts。手順 3：mkdir references……」

順序が自明でない場合や、手順を誤ると問題が起きやすい場合に限り、手順を示します。

基本動作を信頼する

Claude はすでに次のことを理解しています。

• 基本的なプログラミングパターン、一般的なツール、ファイル操作
• 明確な出力の構成方法、Markdown の書式設定
• コード品質に関する一般的なベストプラクティス

スキル固有の例外や、Claude が持ち合わせていないドメイン知識のみを指定してください。

肯定的な指示で記述する

避けるべきことではなく、行うことを述べます。

• ✅ 「直接的な指示を使い、命令形で記述する」
• ❌ 「提案的な表現や、ためらいがちな言い回しを使わない」

要件は肯定的に記述すると、より明確で実行しやすくなります。

コンテキストを示す

自明でない要件について、その理由を説明します。

• ✅ 「段階的な読み込みを可能にするため、SKILL.md は 500 行未満に保ちます。詳細な内容は references/ に移します。」
• ❌ 「SKILL.md は 500 行未満に保ちます」

コンテキストがあると、例外的な状況でも Claude が適切に自律判断できます。

例の品質

例は、意図しないパターンも含め、あらゆるパターンを教えます。すべての要素が望ましい動作を示すようにしてください。異なるメッセージが混在する例を載せるより、例を省くほうが適切です。

包括的なプロンプト作成の指針については、 crafting-instructions スキルを呼び出してください。

同梱リソースのパターン

scripts/

Claude が同様のコードを繰り返し記述する場合に追加します。

• 検証ロジック（スキーマチェック、形式の確認）
• 複雑な変換（データの正規化、形式の変換）
• 厳密な一貫性が求められる決定論的な操作

スクリプトには、明示的なエラー処理とわかりやすい変数名を使用します。

references/

次の場合に追加します。

• SKILL.md が 500 行に近づいている
• 詳細なドメイン知識（API ドキュメント、スキーマ、仕様）
• コンテンツがコアワークフローではなく、特定のユースケースにのみ適用される

参照先は 1 階層に保ちます（file1 → file2 → file3 のような連鎖は避けてください）。

assets/

次のものを追加します。

• ユーザーが出力として受け取るテンプレート
• コンテキストに読み込まずにコピーまたは参照するファイル
• 画像、フォント、静的リソース

アセットを使うとトークンを節約できます。使用されますが、コンテキストには読み込まれません。

判断基準： Claude が同様のコードを繰り返し生成しますか？ → scripts/。ドメイン知識が大量にありますか？ → references/。出力テンプレートがありますか？ → assets/。それ以外は SKILL.md のみとします。

段階的な開示

スキルは次の 3 段階で読み込まれます。

1. メタデータ（名前＋説明）：すべてのスキルについて常に読み込まれます
2. SKILL.md 本文：スキルが有効になると読み込まれます
3. 同梱リソース：Claude が読み進めると読み込まれます

SKILL.md はコアワークフローに絞り込みます（最大約 500 行）。詳細な内容は references/ に移し、必要に応じて読み込めるようにします。これにより、コンテキスト効率の高いスキルエコシステムを実現できます。

トークン効率

各行を吟味してください。Claude に本当にこの説明が必要ですか？ Claude が知っていると想定できますか？ トークンを使うだけの価値がありますか？

簡潔なパターンを優先します。

• 冗長な説明よりコード例
• 網羅的なリストより判断基準
• 手順より戦略的な目標

パッケージ化と配布

ZIP アーカイブを作成します。

cd /home/claude
zip -r /mnt/user-data/outputs/skill-name.zip skill-name/

内容を確認します。

unzip -l /mnt/user-data/outputs/skill-name.zip

パッケージ化した構成をユーザーに示します。

tree skill-name/
# or
ls -lhR skill-name/

ダウンロードリンクを提供します。

[Download skill-name.zip](computer:///mnt/user-data/outputs/skill-name.zip)

バージョン管理（任意）

開発中のスキルでは、変更を追跡します。

cd /home/claude/skill-name
git init && git add . && git commit -m "Initial: skill structure"

変更後：

git add . && git commit -m "Update: description of change"

高度なパターン（ロールバック、ブランチ分岐、比較）については、versioning-skills を参照してください。

ベストプラクティス

構成：

• スキルで何ができるかを明確に概説することから始めます
• 関連する指示をまとめます
• 手順ではなく目標を表す見出しを使います
• 適切な場合は、他のスキルやリソースを参照します

指示：

• Claude について説明するのではなく、Claude に指示するように書きます（命令形のコマンド）
• Claude の知能を前提とし、基本事項を過度に説明しないようにします
• 複雑なパターンにはコード例を示します
• 成功基準を指定し、アプローチは Claude に判断させます

コンテンツ：

• 頻繁に使うガイダンスは SKILL.md に記載します
• 詳細または専門的な内容は references/ に移します
• 自明でない要件には、その理由を含めます
• 一貫した用語を全体で使用します

リソース：

• 実際の問題を解決する同梱リソースのみを追加します
• スクリプトにはエラー処理と明確な出力を含めます
• 参照資料は焦点を絞り、トピックを限定します
• パッケージ化する前に、使っていないディレクトリを削除します

テスト：

• 実際のシナリオを 3 件以上（単純、複雑、エッジケース）使ってテストします
• 想定されるトリガーパターンでスキルが有効になることを確認します
• 同梱リソースにアクセスでき、正常に機能することを確認します
• 思い込みではなく、実際の使用状況に基づいて改善します

品質チェックリスト

スキルをユーザーに提供する前に、次の項目を確認します。

メタデータ：

• 名前：小文字、ハイフン区切り、動名詞形、最大 64 文字
• 説明：三人称で、WHAT + WHEN のトリガーを含み、最大 1024 文字、XML を含まない

構造：

• SKILL.md は 500 行未満（余分な内容は references/ に移動）
• 未使用のディレクトリを削除
• 参照先は 1 階層の深さ（長い連鎖を作らない）

内容：

• 全体を通して命令形を使用
• 肯定的な指示（否定的な制限ではなく）
• 可能な限り、手順よりも戦略的な目標を優先
• ひと目では分かりにくい要件には背景情報を提示
• 例で望ましいパターンを正確に示す
• 用語を統一

リソース：

• スクリプトは実際の問題を解決する（Claude に丸投げしない）
• スクリプトにエラー処理と明確な出力がある
• 参照資料は焦点が明確で、特定のトピックに特化している
• アセットは出力用のテンプレート／ファイルである

テスト：

• 3 件以上の実際のシナリオでテスト済み
• 想定されるトリガーで起動する
• 同梱リソースにアクセスできる
• パッケージ構造を検証済み

高度なトピック

複雑なスキルパターンについては、次を参照してください。

• crafting-instructions スキル — プロンプト作成の包括的な原則
• versioning-skills スキル — Git ベースの開発ワークフロー
• references/advanced-patterns.md — 検証ワークフロー、複数段階のパターン
• references/optimization-techniques.md — トークン予算の管理
• references/bundled-resources.md — リソースパターンと例の詳細
• references/environment-reference.md — 環境固有のパターン