skill-creator

スキル作成ツール

契約

入力：

• 要求されたスキル名、保存先、動作、既存の例

出力：

• スキルの指示、任意のリソース、検証結果

作成／変更対象：

• 要求されたスキルとそのパッケージ化成果物のみ

外部への副作用：

• 明示的に要求されない限り、他の環境への公開やインストールは行いません

確認が必要な操作：

• 無関係な既存スキルを置き換える前、外部依存関係をインストールする前、または許可された保存先以外に公開する前
• スキルを読み込んでも追加の権限は付与されません。既存の明示的な承認は、同じ対象と操作にのみ適用されます。報告のみの制限を維持してください。

委任先：

• なし

スキルについて

スキルは、タスク固有のワークフロー、ツールの使い方、ドメイン知識、スクリプト、参照資料、アセットを追加するモジュール式のパッケージです。

スキルが提供するもの

1. 専門的なワークフロー — 特定のドメインに対応した複数ステップの手順
2. ツール連携 — 特定のファイル形式や API を扱うための指示
3. ドメインの専門知識 — 企業固有の知識、スキーマ、ビジネスロジック
4. 同梱リソース — 複雑で反復的なタスクのためのスクリプト、参照資料、アセット

スキルの構成

すべてのスキルは必須の SKILL.md ファイルと、任意の同梱リソースで構成されます。

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter metadata (required)
│   │   ├── name: (required)
│   │   └── description: (required)
│   └── Markdown instructions (required)
└── Bundled Resources (optional)
    ├── scripts/          - Executable code (Python/Bash/etc.)
    ├── references/       - Documentation intended to be loaded into context as needed
    └── assets/           - Files used in output (templates, icons, fonts, etc.)

SKILL.md（必須）

メタデータ： YAML フロントマターの name と description によって、スキルが有効化されるタイミングが決まります。description にはタスク、トリガーとなるフレーズ、適用範囲を含めてください。クライアント固有の説明は避けてください。

同梱リソース（任意）

スクリプト（scripts/）

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

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

参照資料（references/）

現在のタスクで必要な場合にのみ読み込むドキュメントや参考資料です。

• 含めるタイミング：エージェントが作業中に参照するドキュメントが必要な場合
• 例：財務スキーマ用の references/finance.md、企業の NDA テンプレート用の references/mnda.md、企業ポリシー用の references/policies.md、API 仕様用の references/api_docs.md
• 用途：データベーススキーマ、API ドキュメント、ドメイン知識、企業ポリシー、詳細なワークフローガイド
• 利点：SKILL.md を簡潔に保ち、エージェントが必要だと判断した場合にのみ読み込めます
• ベストプラクティス：ファイルが大きい場合（>10k words）は、SKILL.md に grep 検索パターンを含めてください
• 重複を避ける：各情報は必ず1か所だけに記載してください。トリガー、ワークフローの手順、ゲート、必須の出力は SKILL.md に記載します。詳細な参照資料、スキーマ、長い例、ソース抜粋は references/ に移します。

アセット（assets/）

コンテキストへの読み込みを目的とせず、エージェントが生成する出力内で使用するファイルです。

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

段階的開示の設計原則

スキルでは、コンテキストを効率的に管理するために、3段階の読み込みシステムを使用します。

1. メタデータ（名前＋説明） - 常にコンテキストに含まれます（約100語）
2. SKILL.md 本文 - スキルが呼び出されたときに読み込まれます（5,000語未満）
3. 同梱リソース - エージェントが必要に応じて読み込みます（無制限*）

*スクリプトはコンテキストウィンドウに読み込まずに実行できるため、無制限です。

スキルの作成プロセス

「スキルの作成プロセス」に沿って順番に進めてください。前提条件がすでに満たされている場合に限り、その手順を省略し、理由を記録してください。

ステップ 1：具体例を使ってスキルを理解する

スキルの使用パターンがすでに明確に理解できている場合に限り、このステップを省略してください。既存のスキルを扱う場合でも、このステップには価値があります。

効果的なスキルを作成するには、スキルがどのように使われるのかを具体例を通じて明確に理解する必要があります。こうした理解は、ユーザーから直接提供される例から得られる場合も、生成した例をユーザーのフィードバックで検証して得られる場合もあります。

たとえば、画像エディターのスキルを作成する場合は、次のような質問が関連します。

• 「画像エディターのスキルでは、どのような機能に対応する必要がありますか？編集、回転、その他の機能でしょうか？」
• 「このスキルの使用例をいくつか教えていただけますか？」
• 「『この画像の赤目を除去して』や『この画像を回転して』といった依頼が考えられます。他にどのような使い方が考えられますか？」
• 「どのような依頼があったときに、このスキルを呼び出すべきですか？」

スキルの作成が安全でない、または不可能になるほどの情報不足がない限り、確認の質問は最大1つにしてください。不確かな前提は草案に記載してください。

呼び出しフレーズ、対応するタスク、対象外のタスクが分かったら、このステップを完了します。

ステップ 2：再利用可能なスキルの内容を計画する

具体例を効果的なスキルにするには、各例について次の点を分析してください。

1. その例をゼロからどのように実行するかを検討する
2. こうしたワークフローを繰り返し実行する際に役立つスクリプト、リファレンス、アセットを特定する

例：pdf-editor スキルで「この PDF を回転するのを手伝って」といった依頼に対応する場合、分析から次のことが分かります。

1. PDF を回転するには、毎回同じコードを書き直す必要がある
2. scripts/rotate_pdf.py スクリプトをスキルに保存しておくと便利である

例：frontend-webapp-builder スキルで「ToDo アプリを作って」や「歩数を記録するダッシュボードを作って」といった依頼に対応する場合、分析から次のことが分かります。

1. フロントエンドの Web アプリを作成するには、毎回同じ定型の HTML／React コードを書く必要がある
2. 定型の HTML／React プロジェクトファイルを含む assets/hello-world/ テンプレートをスキルに保存しておくと便利である

例：big-query スキルで「今日ログインしたユーザー数は？」といった依頼に対応する場合、分析から次のことが分かります。

1. BigQuery へのクエリを実行するには、毎回テーブルのスキーマと関連性を再確認する必要がある
2. テーブルのスキーマを記録した references/schema.md ファイルをスキルに保存しておくと便利である

スキルの内容を決めるには、具体例をそれぞれ分析し、含める再利用可能なリソース（スクリプト、リファレンス、アセット）の一覧を作成してください。

ステップ 3：スキルを初期化する

開発するスキルがすでに存在し、反復作業やパッケージ化が必要な場合に限り、このステップを省略してください。その場合は次のステップに進みます。

新しいスキルをゼロから作成するときは、必ず init_skill.py スクリプトを実行してください。このスクリプトは、必要なディレクトリ、フロントマター、リソース用フォルダーを生成します。

使用方法：

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

このスクリプトは次の処理を行います。

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

初期化後、生成された SKILL.md のプレースホルダーを置き換え、使用しないサンプルファイルを削除してください。

Step 4：スキルを編集する

スキルを編集するときは、別のエージェントの観察可能な動作を変える指示だけを含めてください。対象となるのは、トリガー、必須アクション、禁止アクション、順序のゲート、ツールの選択、出力フィールド、制限、フォールバック、証拠要件です。

再利用可能なスキルの内容から始める

まず、上記で特定した再利用可能なリソースである scripts/、references/、assets/ を使って実装を始めてください。必要なアセットやソースドキュメントが欠けている場合は、その項目を求めるか、該当するワークフローを未対応として明記してください。

また、スキルに不要なサンプルファイルやディレクトリは削除してください。初期化スクリプトは構造を示すために scripts/、references/、assets/ にサンプルファイルを作成しますが、ほとんどのスキルではすべてが必要なわけではありません。

SKILL.md を更新する

文体： スキル全体を二人称ではなく、命令形／不定詞形（動詞から始まる指示）で記述してください。客観的で指示的な表現を使ってください（例：「X を達成するには、Y を実行する」。「X を実行してください」や「X を実行する必要がある場合は」ではなく）。これにより、AI が一貫して明確に解釈できます。

SKILL.md を完成させるため、以下の質問に答えてください。

1. スキルの目的は何ですか。数文で説明してください。
2. スキルはいつ使用すべきですか。
3. 実際には、エージェントはどのようにスキルを使うべきですか。上記で作成した再利用可能なスキルの内容を参照し、ワークフローを明確にしてください。

ハウススタイルの技法

このカタログの基準は .agents/memory/system/skill-standards.md にあります。SKILL.md の編集時に適用してください。

• 呼び出し。 明示的なエントリーポイントと助言用マップは disable-model-invocation: true にして、ユーザーのみが呼び出せるようにしてください。再利用可能なエンジンではこれを省略し、選択されたワークフローから到達できるようにしてください。エンジンを読み込んでも、アクションの権限は付与されません。要求された範囲、既存の承認、レポートのみという制限を引き継いでください。変更のゲートは本文に記載し、権限が不足している場合や範囲を広げる場合にのみ承認を求めてください。呼び出し可能なエンジンには直接実行ルートを設け、明示的な呼び出しのみのワークフローには推奨事項を記載してください。リソースは、想定上のリポジトリのチェックアウトではなく、選択されたインストール済みスキルのディレクトリから解決してください。
• 先頭語。 言い換えられた考えを、事前学習済みの単一トークン（frontier、seam、tight、red）にまとめてください。そのトークンを繰り返し使い、文を再説明しないでください。
• 完了基準。 各ステップの終わりに、確認可能な境界を設けてください。「理解に達した」を観察可能な状態（「frontier が空である」「不足している動作に対する限定的なテストが失敗する」など）に明確化してください。
• 無意味な記述を削る。 モデルのデフォルトの動作を変えない文は削除してください。
• 肯定形で指示する。 目標とする動作を明示してください。強い禁止事項には、代わりに取るべき動作を組み合わせてください。
• 契約。 アクション、オーケストレーション、副作用に関するスキルには、入出力、作成／変更するもの、副作用、確認、委譲を含む ## Contract ブロックを設けてください。
• 出典情報。 上流プロジェクトから派生したスキルには、source／upstream_repo／last_synced を記載し、README に ## Upstream セクションを設けてください。

スキルまたはステアリングファイルが長い場合、環境の説明を繰り返している場合、あるいは記述の配置場所を決める必要がある場合は、references/writing-for-agents.md を読んでください。内容は、2 回の読み込み、同じ場所への配置、肥大化、シーケンス別の分割、キャッシュとしての環境、堆積です。

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

スキルの準備ができたら、配布可能な zip ファイルにパッケージ化して、ユーザーと共有します。パッケージ化の処理では、すべての要件を満たしていることを確認するため、最初にスキルが自動検証されます。

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

出力先ディレクトリの指定（任意）：

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

パッケージ化スクリプトは次の処理を行います。

1. 検証：スキルを自動的に検証し、次の項目を確認します。

   • YAML フロントマターの形式と必須フィールド
   • スキルの命名規則とディレクトリ構造
   • 説明の完全性と品質
   • ファイルの整理状況とリソース参照

2. パッケージ化：検証に合格した場合、スキル名（例：my-skill.zip）を付けた zip ファイルを作成します。すべてのファイルが含まれ、配布に適したディレクトリ構造が維持されます。

検証に失敗した場合、スクリプトはエラーを報告して終了し、パッケージは作成されません。検証エラーを修正して、パッケージ化コマンドを再度実行してください。

ステップ 6：反復

スキルをテストした後、確認された失敗や繰り返し発生する問題をもとに、 SKILL.md またはバンドルされたリソースを更新します。

反復ワークフロー：

1. 実際のタスクでスキルを使用する
2. 問題や非効率な点に気づく
3. SKILL.md またはバンドルされたリソースの更新内容を特定する
4. 変更を実施し、再度テストする