fusion-skill-authoring

スキルの作成または刷新

使用するタイミング

skills/ に新しいスキルを作成する場合、または既存のスキルを大幅に見直す必要がある場合に有効化します。

よくあるきっかけ：

• 「…用のスキルを作成して」
• 「skills/<name>/SKILL.md のひな形を作って」
• 「このワークフローを再利用可能なスキルにして」
• 「このスキルのメタデータと有効化の手がかりを改善して」
• 「このスキルを見つけやすくして」
• 「スキル用の参照資料／アセット／ヘルパーエージェントを設定して」

暗黙のきっかけ：

• 同じ指示や安全上の制約が、繰り返し発生するタスクで必要になっている
• 既存のスキルが曖昧すぎる、長すぎる、適切に振り分けられない、または構成が不足している
• ユーザーが単発のプロンプトではなく、再利用可能なワークフローパッケージを求めている

使用しないタイミング

• skills/ の外にある製品コードやアプリケーションコードの編集
• オーサリングワークフローの支援を必要としない、些細な誤字だけの修正
• インストール可能なスキルではなく、ドキュメント、テンプレート、スクリプトで解決するほうが適切な依頼
• 無関係な大規模リポジトリのリファクタリング
• 破壊的なコマンドや、隠れたネットワーク自動化

必要な入力

必要な入力が不足している場合は、まず簡潔で的を絞った質問をします。 既定の質問集として assets/follow-up-questions.md を使用してください。

必須

草案の作成前に確認します：

• 新しいスキルの作成、更新、またはスキルではない依頼のいずれか
• 対象リポジトリのパスと、スキルを配置するディレクトリ
• プレフィックス／名前空間を付ける前の、kebab-case の基本スキル名
• kebab-case の最終的なスキル名。リポジトリに別の慣例がなければ、custom-<base-skill-name> を既定とします
• 目的とユーザーが得られる成果を一文で
• 具体的な有効化の手がかり：トリガーフレーズ、分野のキーワード、対象外とする条件
• 想定される出力：スキルが生成するファイル、コマンド、判断
• 安全上の制約と承認要件

条件付き

関連する場合に確認します：

• 命名プレフィックス、名前空間、カタログの慣例
• スキルのカテゴリ：能力の向上、またはワークフロー／エンコードされた設定
• 構成：単独、オーケストレーター、またはサブスキル
• リポジトリ固有の所有権、ライフサイクル、リリースポリシー
• オーケストレーターとの関係：サブスキルには metadata.orchestrator、オーケストレーターには metadata.skills
• 対象ステータス（active、experimental、deprecated、archived）
• スキルに実際の環境上の制約がある場合の compatibility テキスト
• MCP 要件（metadata.mcp.required ／ metadata.mcp.suggested）
• スコープの明確化、レビュー、またはトリガーの調整に役立つ agents/ 内のヘルパーエージェントがあるか
• 決定的な自動化のために scripts/ ディレクトリを設けるべきか

任意

有用な場合に記録します：

• カタログで使用されている場合の、予備の説明責任担当としての metadata.sponsor
• スターターアセット、チェックリスト、例、テンプレート
• ほぼ一致するものが存在し、重複させる代わりに改善すべき場合の、関連するイシューのフォローアップ

メタデータと構造に関する制約

ファイルを書き込む前に検証します。

• name：1～64文字で、小文字の英字／数字／ハイフンのみを使用し、フォルダー名と一致していること。先頭または末尾にハイフンを置かず、ハイフンを連続させず、XML タグや予約語を含めないこと
• 対象リポジトリにプレフィックスまたは名前空間の規則がない場合、新しいスキルには custom-<base-skill-name> をデフォルトで使用します
• description：空ではなく、1024文字以下の三人称で、スキルが何をするか、いつ使うかの両方を記載すること
  • USE FOR: と DO NOT USE FOR: の手掛かりをインラインで含む、単一引用符で囲んだ YAML 文字列を推奨します
  • 例：description: '検証済みのリポジトリ情報からリリースノートを作成します。USE FOR: リリース概要、変更履歴の準備。DO NOT USE FOR: リリースの公開、製品コードの編集。'
• metadata.version：対象カタログの初期バージョン規則に従います。ローカルの規則がない場合、新しいスキルには "0.0.0" が安全なデフォルトです
• metadata.owner：対象カタログで明示的な所有者が必須の場合にのみ記載し、安定した GitHub の ID または同等のチームハンドルを使用します
• metadata.status：対象カタログでライフサイクル状態を管理している場合にのみ記載します。使用する場合は active、experimental、deprecated、archived のいずれかにします
• metadata.tags：関連性のあるタグを、小文字のケバブケースで記載します
• metadata：関係フィールドでリストまたはマップが明示的に必要な場合を除き、単純なキーと値のメタデータを使用します
• license：トップレベルフィールドとして任意で記載できます
• compatibility：トップレベルフィールドとして任意で記載できます。スキルに実際のランタイム、ネットワーク、ツール、または製品上の制約がある場合にのみ記載します

リポジトリ固有のプレフィックス規則、所有者／ライフサイクル要件、リリースポリシー、検証コマンドは、ポータブルなスキルパッケージではなく、リポジトリ内の指示またはカタログのドキュメントに記載してください。

指示

ステップ 1 — 編集前にインストール済みコピーの由来を確認する

既存の SKILL.md（またはその references/、assets/、agents/）を編集する前に、リポジトリの apm.yml と apm.lock.yaml を調べます。ロックファイルの依存関係の由来とデプロイ済みファイルの所有情報を使って、対象が外部 APM 依存関係に由来するかどうかを判断します。該当する場合、対象は正規のソースではなく、インストール済みコピーです。

インストール済みコピーの場合：

• その場で編集しないでください。次回の apm install または apm update でローカルの編集が上書きされ、ほかの利用者に反映されない可能性があります。
• ファイルが <source> からインストールされていることをユーザーに伝えてください。変更はその場所に加える必要があります。
• <source> に切り替えてそこで変更するか、代わりに不具合／改善の Issue を起票することを提案してください。
• ユーザーが一時的な上書きを明示的に了承し、変更が保持されないことに同意した場合に限り、ローカルで編集してください。

どちらの APM ファイルも存在しない場合、対象に一致するデプロイ済みファイルの所有情報がない場合、またはソースが現在のリポジトリと一致する場合は、通常どおり進めてください。

ステップ 2 — そもそもスキルにすべきか判断する

1. まず既存のカタログを確認します。
   • 既存のスキルで依頼に対応できる場合は、重複を作るのではなく、再利用または更新を推奨します
   • ほぼ一致するスキルがある場合は、その改善または Issue の起票を推奨します
2. 次のような形で対応するほうが適切な場合は、スキルを作成しないでください。
   • リポジトリの通常のドキュメント
   • 再利用可能なエージェントの振る舞いを伴わないテンプレート／チェックリスト
   • スキルとして振り分ける価値のない単独のスクリプト
   • 既存のスキルへの小さな文言修正

ステップ 3 — 作成前に代表的な依頼を定義する

長い指示を書く前に、少なくとも3つの代表的な依頼をまとめます。

• ユーザーからの依頼または起動フレーズ
• スキルが実行すべき振る舞い
• スキルが防ぐべき誤りまたは不足

これらを受け入れ基準として使用します。現実的な依頼を定義できない場合、スコープが不明確であるか、再利用可能なスキルにするには適していません。

Step 4 — スキルの種類を分類し、最小限の有効な構成を選ぶ

スキルの種類を決めます。

• capability uplift：ドメイン知識、ツール、または参考資料をまとめます
• workflow / encoded preference：手順、レビューゲート、スタイル規則、または変更順序をまとめます

構成を決めます。

• standalone：調整役となるスキルは不要です
• orchestrator：関連スキルへのルーティングを行い、共通のゲートを管理します
• subordinate：オーケストレーターの配下でのみ動作します。その依存関係を記載します

最小限のフォルダー構成を選びます。

• SKILL.md は必須です
• references/：長いガイダンス、例、表、またはプラットフォーム固有の詳細に使用します
• assets/：テンプレート、チェックリスト、出力例、静的ファイルに使用します
• agents/：実行環境がスキルごとのエージェントに対応している場合に、特化したヘルパー役に使用します
• scripts/：決定論的な自動化によって安全性または信頼性が大幅に向上する場合にのみ使用します

参照資料は1階層の深さにとどめます。一部だけを読む必要が生じる入れ子構造は作成しないでください。

Step 5 — 最小限の実用的な SKILL.md を作成する

まず、必要最小限のメインドキュメントを作成します。

• 発見しやすい手がかりを盛り込んだ簡潔なフロントマター
• When to use と When not to use
• Required inputs
• Instructions
• Expected output
• Safety & constraints

300行未満に収めます。実行環境によってコンテキスト制限は異なります。300行を超えるファイルは、小規模な実行環境で品質が低下するリスクがあり、CI の警告も発生します。500行を超えるファイルは CI で失敗します。超過する内容は早めに references/ へ移してください。

背景説明よりも、簡潔で具体的な指示を優先します。エージェントには十分な能力があることを前提とし、確実に推測できないコンテキストだけを追加してください。

自由度を意図的に設定します。

• コンテキストに応じた分析やレビューでは自由度を高くします
• 推奨パターンはあるものの、状況に応じた調整が想定される場合は自由度を中程度にします
• ワークフローが脆弱、安全性が重要、または順序に依存する場合は自由度を低くします

SKILL.md に具体例を少なくとも1つ含めるか、references/ にある具体例へのリンクを記載します。

Step 6 — 曖昧さの軽減に役立つ場合にのみ補助ファイルを追加する

長い内容や専門的な内容は SKILL.md から移します。

• references/：詳細なガイダンス、大きな例、API／プラットフォームに関する注記、長いチェックリストに使用します
• assets/：テンプレートや再利用可能な成果物に使用します
• agents/：実行環境がスキルごとのエージェントに対応し、ワークフロー上、範囲を限定したセカンドオピニオンが有用な場合にヘルパー一式に使用します
• scripts/：再生成するのではなく実行すべき決定論的な処理に使用します

スクリプトを追加する場合：

• 依存関係と副作用を記載します。
• 入力を検証し、対処方法がわかるエラーを返します。
• ネットワークアクセスは明示し、その必要性を示します。
• リモートコード実行のパターンは決して使用しないでください。

実行環境が同梱のヘルパーエージェントを無視する場合は、同じ役割をインラインで記述してください。

スキルが MCP に依存する場合は、metadata.mcp で宣言し、スキルの内容にクライアント固有のツール名を記載してください。

ステップ 7 — ディスカバリー、構造、ローカルポリシーを検証する

変更の作成後、対象環境で利用できる検証を実行します。

• 利用可能な場合は、スキルカタログのインベントリまたはスキーマ検証
• 命名、所有権、ライフサイクル、構成のメタデータに関するリポジトリまたはカタログのポリシーチェック
• スキルがスクリプト、GraphQL、リンター、テストに関わる場合は、それらの検証

専用のスキルツールがない場合：

• SKILL.md と直接参照されているすべてのファイルを最後まで読む
• 代表的な各リクエストで、スキルが正しく起動することを確認する
• 参照されているすべてのファイルパスとワークフローの前提が有効であることを確認する

ステップ 3 の代表的なリクエストを使って、次の点を確認します。

• 説明は適切なリクエストで起動し、誤検出を避けていますか？
• エージェントは、入れ子になったリンクをたどらずに、直接参照されているすべてのファイルを見つけられますか？
• 出力、承認ゲート、安全上の制約は明示されていますか？

サブエージェントが利用できる場合：

• 作成前のスコープ決定では agents/scoper.md を使い、新規作成、更新、スキル対象外のいずれかを判断します
• スコープ決定と作成の間に重要な懸念を洗い出すには agents/devils-advocate.md を使います。ユーザーが厳しい質問を求めている場合や、重大な曖昧さが見つかった場合は、完全な構造化インタビューを行います
• 作成後にディスカバリー、構造、安全性、検証の証拠を確認するには agents/reviewer.md を使います
• 主なリスクが起動の手掛かりの弱さである場合は agents/trigger-tuner.md を使います

移植可能なパッケージが正しく整ったら、リポジトリ固有のリリースまたはバージョン管理ルールを適用します。

ステップ 8 — 変更内容と追加情報が必要な項目を報告する

作成結果は、次の内容を明示した契約として返します。

• 作成または更新した内容
• スキルをどのように分類したか
• 受け入れ基準として使用した代表的なリクエスト
• 使用したヘルパーエージェント（該当する場合）
• 実行した検証コマンドと、それによって確認できたこと
• 未解決の質問または推奨するフォローアップ課題

維持すべき中核的な動作

• 既存のスキルを編集する前に、インストール済みコピーの出所を確認する
• 新規作成する前に再利用を検討する
• まず移植可能な形にし、その後にリポジトリ固有のオーバーレイを追加する
• 長文の文言調整より先に、代表的なリクエストを用意する
• SKILL.md に情報を詰め込むのではなく、段階的な開示を行う
• リスクのある操作には、安全策と承認ゲートを明示する
• 正しさを推測するのではなく、実際の検証結果を示す

任意のヘルパーエージェント

Anthropic の skill-creator パターンを参考にしていますが、Fusion 固有のスコープ決定、レビュー、起動調整に絞っています。

• agents/scoper.md — 新しいスキル、更新、スキル対象外のいずれかを判断し、最小限のフォルダー構成を選択します
• agents/reviewer.md — 作成したスキルをディスカバリー、構造、安全性、検証の観点から確認します
• agents/trigger-tuner.md — 説明の文言を調整し、起動の手掛かりとなる表現の候補を比較します
• agents/devils-advocate.md — 常時利用できる品質確認の協力者です。作成中は穏やかなモードで、求められた場合や重大な曖昧さが見つかった場合は質問を深掘りするモードで動作します

実行環境でサブエージェントが利用できない場合は、同じレビュー手順をインラインで行います。

例

• ユーザー：「インシデントの振り返りを作成するスキルを作ってください。」
  • 結果：対象カタログにワークフロー指向の新しいスキルを作成し、振り返りを作成する少なくとも 3 つのシナリオを定義し、SKILL.md のひな形を作成します。テンプレートが必要な場合に限り、assets/ を追加します。
• ユーザー：「fusion-skill-authoring の起動の手掛かりと構造を改善してください。」
  • 結果：既存のスキルを更新し、補足資料やアセットを見直して、対象リポジトリの検証フローを実行します。
• ユーザー：「アプリケーションに新しい CLI フラグを追加してください。」
  • 結果：これはスキル作成ではなく製品コードの作業であるため、このスキルは使用しません。

期待する出力

以下を返してください：

• 作成または更新したファイルパス
• スキルの分類：新規／更新／スキルではない、能力とワークフローのどちらか、単独型／オーケストレーター型／従属型
• 最終的な有効化の手がかりとアンチトリガー
• 選択したフォルダー構成とその理由
• 受け入れ基準として使用した代表的なリクエストを少なくとも3つ
• 使用したヘルパーエージェント（使用した場合）
• 実行した検証コマンド、合否、結果の解釈
• ポータブルなドラフトの作成後に適用したリポジトリ固有のオーバーレイ
• フォローアップアクション、未解決の質問、または推奨する Issue リンク

デフォルトのフォルダー構成と基本テンプレートについては、references/skill-template-baseline.md を参照してください。

検証

成功のシグナル、失敗のシグナル、復旧手順については、references/validation-signals.md を参照してください。

スキルの準備状況チェックリスト

最終品質チェックリストとして、assets/skill-readiness-checklist.md を使用してください。リポジトリ固有の PR 要件は、インストール可能なスキルのアセットではなく、リポジトリの指示に記載してください。

安全性と制約

以下は決して行わないでください：

• シークレットや認証情報を要求または公開する
• ユーザーの明示的な確認なしに破壊的なコマンドを実行する
• 検証結果や評価の根拠を捏造する
• 依頼された範囲外の無関係なファイルを変更する
• 隠れたネットワークアクセス、リモートコード実行、安全でないスクリプトの手順を追加する
• APM がインストールしたコピーについて、元のリポジトリを明らかにして明示的な確認を得る前に、その場で編集する

必ず以下を守ってください：

• SKILL.md は簡潔に保ち、あふれた内容は直接参照する資料に移す
• 説明にディスカバリー契約を明示する
• 曖昧な助言ではなく、決定論的な検証ループを優先する
• ヘルパーエージェントの担当範囲を厳密に限定し、ランタイムがヘルパーエージェントを呼び出さない場合でもコアワークフローが機能するようにする
• 対象カタログの命名、所有権、ライフサイクル、リリースポリシーに従う