skill-builder

Skill Builder

1 つの標準スキルパッケージの作成、修復、監査、エクスポート、またはサポート対象の専門知識を小規模な作成提案に変換します。

作成するかどうかを判断する

新しいスキルやファイルをすでに指定されている場合も含め、作成に取りかかる前に以下を適用してください。

1. 既存の所有者を見つけます。 スキル、リファレンス、チェックリスト、指示ファイルを検索し、すでにその動作を担当しているものがないか確認します。新たなルートを追加するのではなく、その所有者を拡張してください。
2. 独立した事例の数を数えます。 新しいスキル、ゲート、ライブラリ、ワークフローを作成するには、独立した証拠に裏付けられた実例が 3 件あり、不足するコンテキストなしにソース事例へ再適用できることが必要です。事例が 3 件未満の場合は、既存の所有者への限定的なメモの追加にとどめます。1 件の事例は観察であり、スキルではありません。権威ある情報源が裏付けるのは、その情報源を忠実に記述することだけです。
3. 新しい成果物ごとに利用者を明示します。 提案するプロセス成果物（レポート、台帳、カウンター、ダッシュボード、トラッカー）には、具体的な利用者、その成果物が判断に役立つ内容、対応する観察済みの不具合、廃止条件が必要です。いずれかが欠けている場合は追加しません。その成果物を使うためだけに書かれたコードは、利用者にはなりません。
4. 何もしないことも有効な結果です。 既存の所有者への短い追加も有効です。草案を作成する前に、証拠から裏付けられる内容を伝え、呼び出し側が許可したものだけを作成してください。永続的な提案が求められていない場合は、提案をインラインで返します。
5. パッケージを作成しても、効果が証明されたことにはなりません。 振る舞い上の効果は Skill Eval で評価し、受け入れ可否の判断は Validate に委ねてください。

要求された操作を選択する

必要なこと	エントリーポイント
ソースパッケージを作成する	scripts/build.sh の from-scratch、from-template、absorb-external
パッケージ構造を確認する	scripts/heal.sh --check [--strict] skills/<slug>
所有する投影ファイルを修復する	scripts/heal.sh --fix skills/<slug>
監査証拠を確認する	`scripts/audit.sh [--profile canonical
重複するスキルを統合する	統合
別のプラットフォームにエクスポートする	変換
繰り返し使う専門知識を再利用可能にする	専門知識の抽出

選択した操作だけを実行してください。スキルは、ネイティブの呼び出し側が許可した成果を実現するための任意のツールにとどまります。このスキルは、実行フェーズを追加したり、作業を所有したり、Git を操作したり、ソフトウェア候補を検証したり、提供や再試行を判断したりするものではありません。入力、レポートの出力先、終了コード、作成が部分的に失敗した場合の復旧方法については、ビルドとチェックの仕組みを参照してください。

作成と保守

外部のスキルは、構造上の手がかりとしてのみ扱ってください。クリーンルームで作成する出力に、それらの名前、文章、プロンプト、スクリプト、例をコピーしてはいけません。from-template はメタデータの既定値を再利用し、absorb-external <slug> --from <path> は入力を検証して空のソースパッケージを作成します。どちらも別のスキルの内容は取り込みません。

scripts/build.sh は、metadata.authoring_state: scaffold を含む SKILL.md だけで構成される未完成のソースパッケージを1つ作成します。ヘルパー、参照資料、アセットは、実際の動作に応じて追加してください。プレースホルダーを置き換え、適用範囲、入力、権限、結果、完了条件、失敗時の動作を、明確になるレイアウトで記述します。「引き継ぐ」や「その後停止する」といった終端表現は、スキルがインラインで実行されると、呼び出し元のターンを終了させる場合があります。記述する前に終端表現を読んでください。動作を記述し終えてから scaffold 状態を削除してください。厳格なソースチェックでは、この状態があると拒否されます。これを削除するのは作成者による表明であり、意味上の完全性を証明するものではありません。

見落としやレビューでの指摘を受けてスキルを編集する前に、既存テキストの変更を読んでください。テキストを変更しない場合、リストを明示したままにする場合、行を削除する前に確認すべきことが定められています。

ソースの管理元として skills/<slug>/ を編集してください。完成したソースを scripts/heal.sh --check --strict skills/<slug> でチェックし、その後、リポジトリの管理コマンドを使って、管理対象の投影を再生成します。生成された差分を確認してください。投影を手作業で編集してはいけません。チェックに合格しても、動作が保証されるわけではありません。編集によって、スキルのルーティング条件、質問内容、停止条件、コミットや公開の内容、または劣化時の動作が変わる場合や、記録された来歴によって保護されている行を削除する場合は、Skill Eval の結果でその動作が測定されていない限り、その動作は未測定であると報告し、何が不足していたか（ランナー、ホスト、または呼び出し元の許可）を明記してください。誤字、パス、書式の編集では、この報告は不要です。

作成は段階的に行われ、アトミックではありません。後続の段階で失敗した場合は、作成済みのソースとレポートを保持し、終了コードと診断内容を記録したうえで、ソースの作成と、投影およびチェックの完了を分けて報告してください。部分的な結果を完成済みパッケージと呼んだり、作成をやり直すために削除したりしてはいけません。必須のスクリプト、参照資料、ランタイムサポートがない場合は、それらに依存する操作だけをブロックしてください。不足しているリソースを明記し、それに依存しない作業を続けてください。

チェックモードは読み取り専用です。修正モードは、明示的に指定された対象の管理対象投影を再生成しますが、ソースの動作を創作することはありません。既定の監査では、静的な適合性、特定された効果、動作の証拠、そしてゲート判定に影響しない作成者向けの疑義を、それぞれ分けて報告します。総合点、評価、総合判定は出しません。監査ではスキルやトライアルを実行しないため、効果と動作は NOT_PROVEN のままです。厳密なチェック、終了コード、オプトイン式のレガシースキーマについては、監査チェック、作成者向けドクトリン、Codex との同等性を参照してください。

統合

2つのスキルが同じ振る舞いを担っている場合に限り、統合します。共通の記述が1つか2つあるだけなら、統合ではなく相互リンクにします。上記の判断ルールを適用してから、どちらを統合先にするか選びます。適用範囲、権限、結果、失敗時の対応がより明確な、契約が強い方のスキルを残し、もう一方にあって残す方にないルールだけを移します。もう一方の名前を廃止する前に、スキル、参照資料、目標プロンプト、ワークフロー、ドキュメントを検索し、その名前で呼び出している箇所を見つけて、それぞれを統合先に差し替えたうえで、廃止した名前と新しい統合先を docs/MIGRATION.md に記録します。他のスキルや目標から名前で呼び出されているスキルは、廃止時にそのスラッグを scripts/check-cathedral-cut-conformance.py の REMOVED_SKILLS に追加するまで残してください。この設定により、スキルが復活するとチェックが失敗します。この記録なしに削除してはいけません。統合によってルーティングが変わる場合、ルーティングまたはスキル評価の結果で測定されていない限り、廃止したスキルが受けていたリクエストが現在は統合先に届くかどうかは、未測定として報告します。

変換

明示的なリポジトリ外へのエクスポートには、bash skills/skill-builder/scripts/converter/convert.sh <skill-dir> <target> [output-dir] を使います。対象は codex、cursor、test です。--all はすべてのソースパッケージを選択し、--codex-layout inline は従来のインライン Codex レイアウトを選択します。形式の詳細が必要な場合は、 SkillBundle を参照してください。ソースを一度だけ解析し、対象形式を生成してから、リソースの同等性と対象形式を検証します。レイアウトと、Cursor の参照資料で省略したものを報告します。

デフォルトのエクスポート先は .agents/projections/converter/<target>/<skill-name>/ です。 エクスポーターは出力ディレクトリをクリーンな状態から書き込むため、明示的に指定された派生先のみを使用します。ソースパッケージ、その祖先、またはリポジトリのルートは拒否してください。ソースは変更せず、出力を編集するのではなく、ソースまたはアダプターを修正します。 解析、書き込み、形式、必須リソースのいずれかで失敗した場合、エクスポートは未完了になります。Codex を含むすべてのランタイムは skills/ を直接読み込みます。このアドホックなエクスポーターは、配布用ツリーを生成しません。

専門知識を抽出する

呼び出し元が再利用可能なルールを求めている場合は、上記の判断ルールを適用してから、引用付きの出現例または名前のある権威ある情報源を起点にします。適用条件、望ましい振る舞い、入力、出力、否定例、制限を明記します。短い原文の抜粋やコマンド結果は、解決可能な引用とともに保持します。主張をパッケージ化する前に具体例とホールドアウトが必要な場合は、Research のパターンモードを使います。否定例またはホールドアウトのケースを示し、提案するルールが正しい判断を返す仕組みを説明します。最小限の復旧状態を採用する場合は、名前を付けた証拠の喪失または破損のリスクが必要です。

マイニングした情報には、Memory の情報源と保存先のルールを守ります。証拠そのものがポリシーを公開することはできません。提案のみを求めるリクエストは、提案で終わります。既存の権限の範囲内で、通常の既知の欠陥は修正します。ツールの失敗はネイティブの呼び出し元にとって明示的な事実であり、自動的なヘルパーチェーンを開始するものではありません。

実際にパッケージを編集する場合は、必須フィールドについてソーステンプレートを使い、どの文章を含めるべきか判断する際はコンテキスト密度のガイダンスを参照します。どちらも新しいスキルの追加を求めるものではありません。