Skill Creator

このスキルは、効果的なスキルを作成するためのガイダンスを提供します。

スキルについて

スキルは、特殊化された知識、ワークフロー、ツールを提供することでClaudeの機能を拡張する、モジュラーで自己完結型のパッケージです。特定のドメインやタスクのための「オンボーディングガイド」として考えてください—汎用エージェントであるClaudeを、どのモデルも完全に持つことができない手続き的知識を備えた特殊化エージェントに変換します。

スキルが提供するもの

特殊化されたワークフロー - 特定ドメイン向けのマルチステップ手順
ツール統合 - 特定のファイル形式やAPIとの作業方法
ドメイン専門知識 - 企業固有の知識、スキーマ、ビジネスロジック
バンドルリソース - 複雑で反復的なタスクのためのスクリプト、リファレンス、アセット

コア原則

簡潔さが重要

コンテキストウィンドウは公共財。スキルは、システムプロンプト、会話履歴、他のスキルのメタデータ、実際のユーザーリクエストなど、Claudeが必要とする他のすべてとコンテキストウィンドウを共有する。

デフォルトの前提：Claudeはすでに非常に賢い。 Claudeがまだ持っていないコンテキストのみを追加。各情報を「Claudeは本当にこの説明が必要か？」「この段落はトークンコストを正当化するか？」と問い直す。

冗長な説明より簡潔な例を優先。

適切な自由度の設定

タスクの脆弱性と可変性に具体性のレベルを合わせる：

高い自由度（テキストベースの指示）：複数のアプローチが有効、決定がコンテキストに依存、またはヒューリスティックがアプローチを導く場合に使用。

中程度の自由度（パラメータ付きの擬似コードやスクリプト）：好ましいパターンが存在、ある程度の変動が許容される、または設定が動作に影響する場合に使用。

低い自由度（特定のスクリプト、少ないパラメータ）：操作が脆弱でエラーが起きやすい、一貫性が重要、または特定のシーケンスに従う必要がある場合に使用。

Claudeがパスを探索していると考える：崖のある狭い橋には特定のガードレール（低い自由度）が必要で、開けた野原では多くのルートが可能（高い自由度）。

スキルの構造

すべてのスキルは必須のSKILL.mdファイルとオプションのバンドルリソースで構成：

skill-name/
├── SKILL.md（必須）
│   ├── YAMLフロントマターメタデータ（必須）
│   │   ├── name:（必須）
│   │   └── description:（必須）
│   └── Markdown指示（必須）
└── バンドルリソース（オプション）
    ├── scripts/          - 実行可能コード（Python/Bash等）
    ├── references/       - 必要に応じてコンテキストに読み込むドキュメント
    └── assets/           - 出力で使用するファイル（テンプレート、アイコン、フォント等）

SKILL.md（必須）

すべてのSKILL.mdは以下で構成：

フロントマター（YAML）：nameとdescriptionフィールドを含む。これらはClaudeがスキルをいつ使用するかを決定するために読み取る唯一のフィールドであるため、スキルが何であるか、いつ使用すべきかを明確かつ包括的に記述することが非常に重要。
本文（Markdown）：スキルの使用方法と指示。スキルがトリガーされた後にのみ読み込まれる（トリガーされた場合）。

バンドルリソース（オプション）

スクリプト（`scripts/`）

決定論的な信頼性が必要なタスクや繰り返し書き直されるタスクのための実行可能コード（Python/Bash等）。

含めるタイミング：同じコードが繰り返し書き直される場合や決定論的な信頼性が必要な場合
例：PDF回転タスク用のscripts/rotate_pdf.py
利点：トークン効率が良い、決定論的、コンテキストに読み込まずに実行可能
注意：スクリプトはパッチや環境固有の調整のためにClaudeが読む必要がある場合がある

リファレンス（`references/`）

Claudeのプロセスと思考を支援するために必要に応じてコンテキストに読み込むドキュメントと参考資料。

含めるタイミング：作業中にClaudeが参照すべきドキュメント用
例：財務スキーマ用のreferences/finance.md、会社のNDAテンプレート用のreferences/mnda.md、会社ポリシー用のreferences/policies.md、API仕様用のreferences/api_docs.md
ユースケース：データベーススキーマ、APIドキュメント、ドメイン知識、会社ポリシー、詳細なワークフローガイド
利点：SKILL.mdをスリムに保ち、Claudeが必要と判断したときのみ読み込まれる
ベストプラクティス：ファイルが大きい場合（>10k語）、SKILL.mdにgrep検索パターンを含める
重複を避ける：情報はSKILL.mdまたはリファレンスファイルのどちらかに存在すべきで、両方には存在しない。スキルの真のコアでない限り、詳細情報にはリファレンスファイルを優先—これによりSKILL.mdがスリムになり、コンテキストウィンドウを占有せずに情報が発見可能になる。本質的な手順指示とワークフローガイダンスのみをSKILL.mdに保持；詳細なリファレンス資料、スキーマ、例はリファレンスファイルに移動。

アセット（`assets/`）

コンテキストに読み込むことを意図せず、Claudeが生成する出力内で使用するファイル。

含めるタイミング：スキルが最終出力で使用するファイルが必要な場合
例：ブランドアセット用のassets/logo.png、PowerPointテンプレート用のassets/slides.pptx、HTML/Reactボイラープレート用のassets/frontend-template/、タイポグラフィ用のassets/font.ttf
ユースケース：テンプレート、画像、アイコン、ボイラープレートコード、フォント、コピーまたは変更されるサンプルドキュメント
利点：出力リソースをドキュメントから分離、Claudeがコンテキストに読み込まずにファイルを使用可能

スキルに含めないもの

スキルには、その機能を直接サポートする本質的なファイルのみを含めるべき。以下を含む余分なドキュメントや補助ファイルを作成しない：

README.md
INSTALLATION_GUIDE.md
QUICK_REFERENCE.md
CHANGELOG.md
等

スキルには、AIエージェントが目の前の仕事を行うために必要な情報のみを含めるべき。作成過程に関する補助的なコンテキスト、セットアップとテスト手順、ユーザー向けドキュメント等は含めない。追加のドキュメントファイルを作成することは、混乱を招くだけ。

プログレッシブディスクロージャ設計原則

スキルは、コンテキストを効率的に管理するために3レベルの読み込みシステムを使用：

メタデータ（name + description） - 常にコンテキスト内（約100語）
SKILL.md本文 - スキルがトリガーされたとき（<5k語）
バンドルリソース - Claudeが必要とするとき（スクリプトはコンテキストウィンドウに読み込まずに実行できるため無制限）

プログレッシブディスクロージャパターン

コンテキストの肥大化を最小限に抑えるため、SKILL.md本文を本質的なものに保ち、500行以下にする。この制限に近づいたら、コンテンツを別のファイルに分割。他のファイルにコンテンツを分割する場合、SKILL.mdから参照し、いつ読むべきかを明確に記述することが非常に重要で、スキルの読者がそれらの存在といつ使用すべきかを知ることができる。

重要な原則： スキルが複数のバリエーション、フレームワーク、またはオプションをサポートする場合、コアワークフローと選択ガイダンスのみをSKILL.mdに保持。バリアント固有の詳細（パターン、例、設定）は別のリファレンスファイルに移動。

パターン1：リファレンス付きハイレベルガイド

# PDF処理

## クイックスタート

pdfplumberでテキストを抽出：
[コード例]

## 高度な機能

- **フォーム入力**：完全なガイドは[FORMS.md](FORMS.md)を参照
- **APIリファレンス**：すべてのメソッドは[REFERENCE.md](REFERENCE.md)を参照
- **例**：一般的なパターンは[EXAMPLES.md](EXAMPLES.md)を参照

ClaudeはFORMS.md、REFERENCE.md、またはEXAMPLES.mdを必要なときのみ読み込む。

パターン2：ドメイン固有の組織

複数ドメインを持つスキルの場合、関係のないコンテキストの読み込みを避けるためにドメインごとにコンテンツを整理：

bigquery-skill/
├── SKILL.md（概要とナビゲーション）
└── reference/
    ├── finance.md（収益、請求メトリクス）
    ├── sales.md（商談、パイプライン）
    ├── product.md（API使用状況、機能）
    └── marketing.md（キャンペーン、アトリビューション）

ユーザーが販売メトリクスについて質問すると、Claudeはsales.mdのみを読む。

同様に、複数のフレームワークやバリアントをサポートするスキルの場合、バリアントごとに整理：

cloud-deploy/
├── SKILL.md（ワークフロー + プロバイダー選択）
└── references/
    ├── aws.md（AWSデプロイパターン）
    ├── gcp.md（GCPデプロイパターン）
    └── azure.md（Azureデプロイパターン）

ユーザーがAWSを選択すると、Claudeはaws.mdのみを読む。

パターン3：条件付き詳細

基本コンテンツを表示し、高度なコンテンツへリンク：

# DOCX処理

## ドキュメントの作成

新規ドキュメントにはdocx-jsを使用。[DOCX-JS.md](DOCX-JS.md)を参照。

## ドキュメントの編集

単純な編集の場合、XMLを直接変更。

**変更履歴の場合**：[REDLINING.md](REDLINING.md)を参照
**OOXMLの詳細**：[OOXML.md](OOXML.md)を参照

Claudeはユーザーがそれらの機能を必要とするときのみREDLINING.mdまたはOOXML.mdを読む。

重要なガイドライン：

深くネストされたリファレンスを避ける - リファレンスはSKILL.mdから1レベル深くに保つ。すべてのリファレンスファイルはSKILL.mdから直接リンクする。
長いリファレンスファイルを構造化 - 100行以上のファイルには、Claudeがプレビュー時に全体のスコープを確認できるように、上部に目次を含める。

スキル作成プロセス

スキル作成は以下のステップを含む：

具体的な例でスキルを理解
再利用可能なスキルコンテンツを計画（スクリプト、リファレンス、アセット）
スキルを初期化（init_skill.pyを実行）
スキルを編集（リソースを実装しSKILL.mdを記述）
スキルをパッケージ（package_skill.pyを実行）
実際の使用に基づいてイテレーション

これらのステップを順番に従い、適用されない明確な理由がある場合のみスキップ。

ステップ1：具体的な例でスキルを理解

スキルの使用パターンがすでに明確に理解されている場合のみこのステップをスキップ。既存のスキルで作業している場合でも価値がある。

効果的なスキルを作成するには、スキルがどのように使用されるかの具体的な例を明確に理解。この理解は、直接的なユーザー例またはユーザーフィードバックで検証された生成例のいずれかから得られる。

例えば、image-editorスキルを構築する場合、関連する質問には以下が含まれる：

「image-editorスキルはどのような機能をサポートすべきですか？編集、回転、他には？」
「このスキルがどのように使用されるかの例を教えてもらえますか？」
「ユーザーが『この画像から赤目を除去して』や『この画像を回転して』のようなことを求めると想像できます。このスキルが使用される他の方法を想像できますか？」
「このスキルをトリガーするためにユーザーは何と言うでしょうか？」

ユーザーを圧倒しないように、単一のメッセージで多くの質問をしない。最も重要な質問から始め、より効果的にするために必要に応じてフォローアップ。

スキルがサポートすべき機能の明確な感覚を得たときにこのステップを終了。

ステップ2：再利用可能なスキルコンテンツの計画

具体的な例を効果的なスキルに変えるには、各例を以下で分析：

例をゼロから実行する方法を検討
これらのワークフローを繰り返し実行する際に役立つスクリプト、リファレンス、アセットを特定

例：「このPDFを回転させて」のようなクエリを処理するpdf-editorスキルを構築する場合、分析は以下を示す：

PDFを回転するには毎回同じコードを書き直す必要がある
scripts/rotate_pdf.pyスクリプトをスキルに保存すると役立つ

例：「todoアプリを作って」や「歩数を追跡するダッシュボードを作って」のようなクエリのためのfrontend-webapp-builderスキルを設計する場合、分析は以下を示す：

フロントエンドwebappを書くには毎回同じボイラープレートHTML/Reactが必要
ボイラープレートHTML/Reactプロジェクトファイルを含むassets/hello-world/テンプレートをスキルに保存すると役立つ

例：「今日ログインしたユーザー数は？」のようなクエリを処理するbig-queryスキルを構築する場合、分析は以下を示す：

BigQueryをクエリするには毎回テーブルスキーマと関係を再発見する必要がある
テーブルスキーマを文書化したreferences/schema.mdファイルをスキルに保存すると役立つ

スキルのコンテンツを確立するには、各具体的な例を分析して、含める再利用可能なリソースのリストを作成：スクリプト、リファレンス、アセット。

ステップ3：スキルの初期化

この時点で、実際にスキルを作成する時。

開発中のスキルがすでに存在し、イテレーションやパッケージングが必要な場合のみこのステップをスキップ。その場合は次のステップに進む。

新しいスキルをゼロから作成する場合、常にinit_skill.pyスクリプトを実行。このスクリプトは、スキルが必要とするすべてを自動的に含む新しいテンプレートスキルディレクトリを便利に生成し、スキル作成プロセスをより効率的で信頼性の高いものにする。

使用方法：

scripts/init_skill.py <skill-name> --path <output-directory>

このスクリプトは：

指定されたパスにスキルディレクトリを作成
適切なフロントマターとTODOプレースホルダーを持つSKILL.mdテンプレートを生成
サンプルリソースディレクトリを作成：scripts/、references/、assets/
カスタマイズまたは削除できるサンプルファイルを各ディレクトリに追加

初期化後、生成されたSKILL.mdとサンプルファイルを必要に応じてカスタマイズまたは削除。

ステップ4：スキルの編集

（新しく生成された、または既存の）スキルを編集する際、スキルは別のClaudeインスタンスが使用するために作成されていることを忘れない。Claudeにとって有益で自明でない情報を含める。別のClaudeインスタンスがこれらのタスクをより効果的に実行するのに役立つ手続き的知識、ドメイン固有の詳細、または再利用可能なアセットを検討。

実証済みのデザインパターンを学ぶ

スキルのニーズに基づいてこれらの役立つガイドを参照：

マルチステッププロセス：シーケンシャルワークフローと条件付きロジックについてはreferences/workflows.mdを参照
特定の出力形式や品質基準：テンプレートとサンプルパターンについてはreferences/output-patterns.mdを参照

これらのファイルには、効果的なスキル設計のための確立されたベストプラクティスが含まれている。

再利用可能なスキルコンテンツから始める

実装を開始するには、上記で特定した再利用可能なリソース（scripts/、references/、assets/ファイル）から始める。このステップにはユーザー入力が必要な場合がある。例えば、brand-guidelinesスキルを実装する場合、ユーザーはassets/に保存するブランドアセットやテンプレート、またはreferences/に保存するドキュメントを提供する必要があるかもしれない。

追加されたスクリプトは、バグがなく出力が期待通りであることを確認するために実際に実行してテストする必要がある。多くの類似したスクリプトがある場合、完了までの時間とバランスを取りながら、すべてが機能することを確信するために代表的なサンプルのみをテストすれば十分。

スキルに不要なサンプルファイルとディレクトリは削除すべき。初期化スクリプトは構造を示すためにscripts/、references/、assets/にサンプルファイルを作成するが、ほとんどのスキルはそれらすべてを必要としない。

SKILL.mdの更新

記述ガイドライン： 常に命令形/不定形を使用。

フロントマター

nameとdescriptionを持つYAMLフロントマターを記述：

name：スキル名
description：これはスキルの主要なトリガーメカニズムであり、Claudeがいつスキルを使用するかを理解するのに役立つ。
- スキルが何をするかと、いつ使用するかの具体的なトリガー/コンテキストの両方を含める。
- すべての「いつ使用するか」情報をここに含める - 本文には含めない。本文はトリガー後にのみ読み込まれるため、本文の「このスキルを使用するタイミング」セクションはClaudeにとって役に立たない。
- docxスキルの説明例：「変更履歴、コメント、フォーマット保持、テキスト抽出をサポートした包括的なドキュメント作成、編集、分析。Claudeが以下のためにプロフェッショナルドキュメント（.docxファイル）を扱う必要がある場合に使用：(1) 新規ドキュメントの作成、(2) コンテンツの変更または編集、(3) 変更履歴での作業、(4) コメントの追加、またはその他のドキュメントタスク」

YAMLフロントマターに他のフィールドを含めない。

本文

スキルとそのバンドルリソースの使用方法を記述。

ステップ5：スキルのパッケージング

スキルの開発が完了したら、ユーザーと共有する配布可能な.skillファイルにパッケージする必要がある。パッケージングプロセスは、すべての要件を満たしていることを確認するために最初に自動的にスキルを検証：

scripts/package_skill.py <path/to/skill-folder>

オプションの出力ディレクトリ指定：

scripts/package_skill.py <path/to/skill-folder> ./dist

パッケージングスクリプトは：

スキルを自動検証し、以下をチェック：
- YAMLフロントマターの形式と必須フィールド
- スキルの命名規則とディレクトリ構造
- 説明の完全性と品質
- ファイル構成とリソース参照
検証が成功した場合、スキルをパッケージし、スキル名にちなんだ.skillファイル（例：my-skill.skill）を作成。すべてのファイルを含み、配布用の適切なディレクトリ構造を維持。.skillファイルは.skill拡張子を持つzipファイル。

検証が失敗した場合、スクリプトはエラーを報告し、パッケージを作成せずに終了。検証エラーを修正し、パッケージングコマンドを再度実行。

ステップ6：イテレーション

スキルのテスト後、ユーザーが改善を要求する場合がある。これは多くの場合、スキルのパフォーマンスについての新鮮なコンテキストを持って、スキルを使用した直後に発生する。

イテレーションワークフロー：

実際のタスクでスキルを使用
苦労や非効率に気づく
SKILL.mdまたはバンドルリソースをどのように更新すべきか特定
変更を実装し、再度テスト

skill-creator