skill-architect

スキルアーキテクト

ベンダーに依存しない視点から、移植性が高く高品質なエージェントスキルを設計します。このスキルは、あらゆるエージェントスキルのリポジトリやランタイムに対応する、独立した計画、作成、レビュー、リファクタリング、比較、抽出、調整、指導のレイヤーとして使用できます。

コマンドモード

ユーザーが明示的に指定した場合は、コマンド形式のモードを使用します。モードが指定されていない場合は、リクエストに最も近いモードを推測し、その前提を明示します。

モード	使用する場面	主な参照資料	出力
skill-architect: plan	編集前に、スキル、リポジトリ標準、ゲート、リリース、移行を設計する場合	移植可能な基準、命名とパッケージング	スコープ、影響を受けるファイル、標準、検証方法、ロールバックの注意事項
skill-architect: create	新しい移植可能なスキルを作成する場合、またはスキルフォルダーをひな形から作成する場合	移植可能な基準	SKILL.md と、リンクされた参照資料／アセット／スクリプト、およびリポジトリのメタデータ計画
skill-architect: audit	既存のスキルまたはスキルリポジトリを基準に照らしてレビューする場合	移植可能な基準	出典を明記した指摘事項の表、機械的ゲートの状態、修正案
skill-architect: fix	validate_skill.py で正しさを証明できる、範囲の限定された決定的な修正を適用する場合	移植可能な基準	ドライランのパッチ一覧または適用済みの安全な修正と、その後の検証出力
skill-architect: refactor	目的を変えずに既存のスキルを改善する場合	移植可能な基準、評価方法	トリガーの書き直し、参照資料の分割、ルーティングの整理、検証内容の更新
skill-architect: compare	スキル開発、作成、クリエイター向けの上流基準を比較する場合	比較調査	エビデンスマトリクス、再利用可能なルール、採用／却下の判断
skill-architect: distill	1 つのセッション、セッション ID／パス、または複数のセッションをレビューし、再利用可能なスキルを抽出する場合	評価方法、移植可能な基準	セッションのエビデンスマップ、再利用可能なワークフロー、スキルの提案または草案、評価計画
skill-architect: reconcile	古くなったスキル計画、監査、セッションから抽出した提案、または保留中のスキルのバックログを更新する場合	評価方法、移植可能な基準	更新後の状態、差分に関する判断、取り下げ／再開する項目、次に実行できる計画
skill-architect: teach	スキル作成の標準を説明する場合、またはユーザー／エージェントを指導する場合	移植可能な基準、ベンダーアダプター	簡潔なレッスン、例、次の練習問題またはチェックリスト

モードのルール

• Plan は、複数ファイルにまたがる重要な変更、新しいゲート、リリース作業、またはベンダーをまたぐアダプターの変更より先に行います。
• Create では、具体的なユースケースから始め、その後、ベンダーのメタデータより先に移植可能なコアを作成します。
• Audit はデフォルトで読み取り専用です。指摘事項を提示し、ユーザーから修正の依頼もあった場合を除き、その返答を待ちます。
• Fix は決定的な処理で、まずドライランを実行します。安全な機械的編集に限って fix_skill.py --write を適用し、その後 validate_skill.py を実行します。
• Refactor では意図を維持します。明示せずに、依頼された範囲を超えて名前を変更したり、分割したり、動作を変えたりしてはいけません。
• Compare では調査した出典を引用し、出典に記載された事実と採用の判断を分けます。
• Distill ではセッション固有の出来事と再利用可能なパターンを分け、セッションの出典を引用し、繰り返し見られる行動または価値の高い行動に基づいてのみスキルを提案します。
• Reconcile では、以前の計画、指摘、提案が現在の状況にも合っているかを確認します。修正済みまたは却下された項目は再度報告せず、取り下げます。
• Teach では、役立つ最小限のルールを説明し、基準全体を列挙するのではなく、具体例を 1 つ示します。

動作モード

上流の評価基準ではなく、現在の作業コンテキストから始めます。編集前に、CWD、プロジェクトファイル、インストール済みスキルの場所、またはリポジトリの規約を確認します。移植可能な基本構文には Agent Skills 仕様を使用します。外部の評価基準はコンテンツの品質向上に役立ちますが、受け入れ可能なフロントマター項目、マニフェスト、ロックファイル、CI、リリースゲートについては、ローカルのルールを優先します。対象のランタイムとリポジトリのスキーマの両方が allowed-tools を受け入れ、適用する場合を除き、実験的な allowed-tools は追加しないでください。

次の順序で進めます。

1. 依頼を分類する — ファイルやチェックを決める前に、plan、create、audit、fix、refactor、compare、distill、reconcile、teach から選びます。完了条件：モードを1つ明示するか、推定したモードを前提として述べます。
2. ローカル標準を読む — 編集前に、CWD／プロジェクト／リポジトリの作成標準、エージェント向け指示、チェックコマンド、対象スキルを確認します。完了条件：適用される標準とチェックコマンドをパス付きで示すか、存在しないことを明記します。
3. 観点を選ぶ — 構造、品質／評価、ベンダー互換性、配布ガバナンス、予測可能性のいずれかを選びます。完了条件：対象となる各観点を明示します。
4. 予測可能性を確認する — 編集案を提示する前に、呼び出しとの適合性、分岐の一意性、情報の階層、完了条件、先頭語、重複、堆積、肥大化、何もしない行、早すぎる完了のリスクを確認します。完了条件：各チェックについて、file:line の根拠とともに維持または修正の判断を示します。
5. 成果物を計画する — 移植可能なコア、参照資料、任意のアセット／スクリプト、ベンダーメタデータ、検証手順を決めます。完了条件：追加または変更するすべてのファイルと、それを検証するコマンドを一覧にします。
6. 必要最小限の修正を行う — 差分だけを目的とした書き換えを避け、依頼された範囲と、直接関連する標準違反のみを改善します。完了条件：差分が計画したファイルだけに及んでいるか、追加ファイルを個別に示します。
7. 機械的に検証する — 引き渡す前に、リポジトリのチェック、または最も近いローカルの代替チェックを実行します。完了条件：各チェックについて、正確なコマンドとともに合格、失敗、またはスキップを報告します。

スキルのアーキテクチャワークフロー

1. 具体的なユースケースを集める

構造を決める詳細のみを記録します。

• スキルを起動するトリガーとなる、具体的な依頼文
• スキルの必要性を示すファイルパス、ツール、API、エラーメッセージ
• 繰り返し現れるタスクの形式：クイックリファレンス、ワークフロー、ルーター、レビュールーブリック、決定論的ヘルパー
• 対象ランタイムの機能：必要なツール、権限、指示の読み込みを確認します。ホスト固有の実行方法やパッケージングの詳細が重要な場合は、vendor-adapters.md を使用します
• スキルに参照資料、アセット、例、ヘルパースクリプトが必要かどうか

構造上の選択が曖昧な場合は、焦点を絞った質問を1つします。それ以外の場合は、CWD／プロジェクト／リポジトリのパターンから推定し、その前提を明示します。

2. 移植可能なコアとアダプターを分ける

移植可能なコアは SKILL.md とリンクされた参照資料に置きます。ベンダー固有の詳細は、アダプターのセクションまたはメタデータファイルに置きます。

レイヤー	含める内容	避ける内容
移植可能なコア	トリガーの意図、ワークフロー、チェック、参照資料、スクリプト／アセット	あるベンダーの CLI に関する前提を普遍的な事実として扱うこと
ローカル規約	必須のフロントマター、バージョン、ハッシュ、セキュリティファイル、README／プラグインレジストリの更新、プラットフォーム規約	ローカルのチェックに失敗する上流の既定値
ベンダーアダプター	OpenAI YAML、Claude プラグインに関する注記、Antigravity／Azure の規約、インストール上の制約	1つのエージェントに合わせて移植可能なワークフローを変更すること
品質ハーネス	評価用プロンプト、ベースライン比較、レビューパケット、負荷テスト	文章のレビューだけで品質を判断したと主張すること

3. 段階的に情報を開示する

SKILL.md は、ルーティングと即時の動作に焦点を絞ります。長い比較、応用例、ベンダーの比較表、評価の詳細は references/ に移します。

移植可能なスキルの最小構成：

skills/<skill-name>/
├── SKILL.md
├── LICENSE
└── references/          # only when detail would bloat SKILL.md

再現性が大幅に向上する場合に限り、assets/ やヘルパースクリプトを追加します。ローカルのプロジェクトまたはランタイムで実行可能なヘルパーが明示的に許可されていない限り、スクリプトは実行されないスキルアセットとして扱います。利用可能な場合は、ローカルの規約に従ってドキュメント化し、リンクを作成し、ハッシュを記録し、セキュリティスキャンを実施します。

4. パッチ適用前のレビュー

重要な編集を行う前に、簡潔な監査パケットを準備します。

チェック	根拠	判断
トリガーの説明が具体的である	SKILL.md のフロントマター行	維持／修正
呼び出し方法の適合性が正当化されている	説明、想定される呼び出し元、コンテキスト／認知負荷のトレードオフ	モデル呼び出しを維持／ユーザー呼び出しに変更／ルーターを追加
分岐が重複していない	説明、コマンド表、モードルール	維持／同義語だけのトリガー分岐を統合
情報階層が整理されている	セクション一覧	SKILL.md に残す／リファレンスへ移動／手順を分割
完了基準を検証できる	各順序付きステップまたはコマンドワークフロー	維持／明確化／完了基準を追加
先頭の語句が繰り返し登場する概念を表している	繰り返される動作語とトリガー表現	説明文を維持／先頭の語句に集約
削減パスで不要な残存物が見つからない	重複、古い記述、何もしない記述、冗長な行	維持／削除／開示
SKILL.md が十分に簡潔である	語数	維持／分割
リファレンスへのリンクがある	リンクチェック	維持／修正
ベンダー固有の前提が分離されている	該当するセクション／ファイル	維持／修正
機械的なゲートが利用できる	リポジトリのスクリプト、CI、評価、フィクスチャ	実行／未実行として記録

スタイルの評価やコンテンツの修正に取り掛かる前に、予測可能性と削減のパスを実施します。

1. 呼び出し方法の適合性： スキルをモデル呼び出しにするか、ユーザー呼び出しにするかを決定します。自律的なエージェントの到達範囲やスキル間の到達範囲が必要な場合に限り、コンテキスト負荷を受け入れます。ユーザー呼び出しのスキルが多く認知負荷を生む場合は、ルータースキルを推奨します。
2. 説明の分岐： 実際の分岐ごとにトリガーを1つに保ち、同義語だけのトリガーの重複をなくし、プロンプト、ドキュメント、コードにも登場する有力な語句を冒頭に置きます。
3. 情報階層： 主要なブロックをそれぞれ、手順、スキル内リファレンス、開示済みリファレンスのいずれかに分類します。すべての分岐に必要な情報はインラインで記述し、特定の分岐にのみ必要な詳細はコンテキストポインターの先に移します。
4. 完了基準： 順序付きの各ステップは、検証可能な完了条件で終える必要があります。手順を分割する前に、曖昧な基準を明確にします。
5. 早すぎる完了のリスク： 完了後に行うステップが見えていることで注意が先に向いてしまい、現在の基準をこれ以上明確化できない場合は、実際にコンテキスト境界を設けて分割することを推奨します。
6. 先頭の語句： 予測可能な実行や呼び出しが向上する場合に限り、繰り返される説明文を、事前学習済みの簡潔な概念に置き換えます。
7. 削減： 文単位で関連性と無効性を検査し、使われていない文章を磨くのではなく、重複、不要な残存物、冗長さを取り除きます。

動作を形作るスキルには、フォワードテストまたはプロンプトシナリオを少なくとも1つ追加します。出荷する CI、シェル、コード（ヘルパースクリプト、スニペット、ワークフロー例など）については、読んで確認しただけで正しいと判断せず、フィクスチャに対して実行します。読み取りやセキュリティスキャンでは、誤った正規表現のようなロジック上の欠陥を見逃すことがあります。埋め込みコードに関する各指摘または合格判定には、フィクスチャのコマンドと観測された出力、またはリスクを明示した未実施の注記が必要です。これがなければ監査は完了していません。

範囲を限定した実行可能面のトリアージを行い、評価、アダプター、説明の弱さに関する所見をレビュールーブリックに基づいて調整します。アルゴリズムの正しさ、悪用可能性、パフォーマンス、大規模なリファクタリングは、専用のコードレビュースキルに回します。

Skill Architect 自体を評価する著者／レビュアーのみ： 別のタスクに Skill Architect を使用する場合は、このカタログをスキップしてください。モードシナリオカタログには、9つすべてのモードについて、自己完結したフィクスチャファイル、分離手順、評価基準、説明のみを使ったルーティングプロンプトが用意されています。新しいケースディレクトリを作成し、評価内容を実行者に知らせないでください。このカタログはテスト入力であり、これらのモードが合格したことの証拠ではありません。

テストベクトル、ハーネスのセットアップ、列挙の一貫性、重大度の調整については、SKILL.md を拡張するのではなく、評価方法とポータブルルーブリックを使用してください。

5. 引き継ぎを実行可能にする

計画、提案、監査パケット、または別のエージェントや次のセッション向けに要約したスキル仕様を作成する際は、想定される中で最も経験の浅い実行者にも伝わるように記述します。参照可能な信頼できる一次資料を、正確なパスまたは URL で示します。実行者が必要とする場合に限り、重要な抜粋を含めます。ローカルの規約、スコープの境界、期待される結果を含む検証コマンド、ドリフトチェック、STOP 条件を維持します。依存関係のあるタスクでは、消費および生成するインターフェースと、引き継ぎ計画の評価基準を使った要件の網羅状況を明記します。

却下した調査結果や採用しなかったパターンには、次回の監査や調整で再び持ち出されないよう、理由を一行で記録します。

6. 検証して引き継ぐ

現在の作業コンテキストに適した、最小限で意味のあるチェックを実行します。文書化された検証コマンド、CI ゲート、評価、フィクスチャテスト、ハッシュチェック、セキュリティスキャンがある場合は、それらを優先します。skills4sh では、パッケージングチェックリストを実行します。

新しいファイルにスクリプト、シェルの例、認証情報に関するガイダンス、ネットワークの例、その他セキュリティ上重要なパターンが含まれる場合は、対象を絞った、または完全なセキュリティスキャンを実行します。

何が成功し、失敗し、スキップされたかを正確に報告します。実行していない評価、スキャン、フィクスチャテストを実行したと主張してはいけません。

ヘルパースクリプト

任意のヘルパースクリプトは assets/scripts/ にあり、実行されないスキルアセットとして同梱されます。

スクリプト	用途
assets/scripts/inspect_skill.py	スキルフォルダーのファイル、フロントマター、本文の単語数、リンクされた参照、明らかな不足項目を要約します
assets/scripts/validate_skill.py	1 つのスキルフォルダーに対して、警告のみの段階的開示に関するヒントを含む、ローカルで移植可能なスキル検証を実行します
assets/scripts/fix_skill.py	SKILL.md に対して保守的で決定論的な修正をドライランまたは適用し、その後、検証を再実行します
assets/scripts/scaffold_skill.py	スタータースキルフォルダーを作成します。--author は metadata.author を設定し（それ以外の場合は省略）、--openai-yaml は Codex の agents/openai.yaml を追加します
assets/scripts/run_uv.py	継承した UV_* ホスト設定を削除してから uv を起動します

inspect_skill.py と validate_skill.py は、それぞれ 1 回の実行につき 1 つのスキルフォルダーを受け取ります。複数のスキルを処理する場合は、同じ Python 環境を再利用し、フォルダーごとに各ヘルパーを個別に実行します。

検証と検査には、隔離されたランナー内で Python >=3.10 とハッシュ固定された Python 依存関係ファイルが必要です。まず run_uv.py を使い、使用できない場合は一時的な仮想環境を使います。すべてのヘルパーは python -E -B で実行します。検証用の依存関係をグローバルな Python 環境にインストールしてはいけません。また、python -I も使わないでください。正確な uv、venv、PowerShell コマンドと、ヘルパーを利用できない場合の報告方法については、ヘルパーのランタイムを参照してください。

スキャフォールドおよび修正ヘルパーに必要なのは Python のみです。修正ヘルパーは、列 0 から始まるリテラルなマッピングキーと、単純な単一行のリテラル名を受け付けます。サポートされていないキー構文や名前構文を検出した場合は、編集前に処理を拒否します。そのようなケースでは手動で確認してから、検証を実行してください。

決定論的な検査やスキャフォールドが必要な場合に限り、スクリプトを読んだり実行したりしてください。ローカルの検証コマンドと CI がある場合は、引き続きそれらを正式な基準とします。

決定論的なチェックと判断

スキルの作業は4つのレイヤーに分かれています。これらを分けて、それぞれのチェックを判断できるレイヤーに割り当ててください。

レイヤー	担当範囲	例
ポータブルバリデーター（validate_skill.py）	1つのスキルフォルダー内で完結し、リポジトリのメタデータやネットワークに依存しない、最小限の決定論的チェック	有効な YAML と型が指定された空でないフィールド、仕様上の長さ制限、name とディレクトリ名の一致およびケバブケース、具体的な発動条件の詳細を含む説明、本文が厳格なサイズ上限以内であること、SKILL.md からリンクされている references/*.md、スキル内の相対 Markdown リンクのリンク先、および同一ファイル内・ファイル間の Markdown 見出しアンカー
ポータブルフィクサー（fix_skill.py）	好みや専門領域の判断を必要としない、安全で機械的な編集。--write が明示されない限りドライランで実行	フロントマターの name の正規化、および SKILL.md への未リンクの references/*.md リンクの挿入
ローカルバインディングゲート（プロジェクトの CI）	リポジトリの規約に依存する決定論的なチェック。必須であり、より広範なチェックを含みます	ファイルハッシュ、skills-lock.json、セキュリティマニフェスト、ドキュメント同期、セマンティックバージョニング。skills4sh ではパッケージングチェックリスト
このスキルのルーブリック（判断）	スクリプトでは判断できない項目	発動条件の 品質、実行可能なサーフェスのトリアージ、埋め込みコードの 正確性（レビューとフィクスチャの実行）、上限を超える本文の高度さ、ベンダーからの独立性、説明の冗長さ

判断基準は次のとおりです。**スクリプトで判断できることは自動化し、推論や好みが必要なことはルーブリックに残します。**ローカルバインディングゲートがある場合、重複する項目については、ポータブルバリデーターよりもローカルバインディングゲートを優先してください。ポータブルバリデーターの範囲は意図的に限定されています。チェックするのは、1つのスキルフォルダー内で確認できる事実だけです（たとえば、数値によるサイズ範囲などの）ルールを明文化すれば、判断対象からバリデーターの対象へ移ります。これを目指すべきことであり、損失ではありません。

参照ファイル

ファイル	読み込むタイミング
references/comparative-study.md	Anthropic、OpenAI、Matt Pocock、Obra、Azure、Antigravity、またはその他のスキル開発・執筆・作成パターンを比較するとき
references/house-rubric.md	ポータブルなルーブリックを作成またはレビューするとき。予測可能性、呼び出しへの適合性、完了条件、整理、列挙の一貫性、実行可能なサーフェスのトリアージ、重大度の調整を確認するとき
references/vendor-adapters.md	ランタイムのインストール先、ポインターファイル、ポータブルなワークフローに含めないベンダーメタデータを扱うとき
references/eval-methodology.md	発動条件のテスト、テストベクターカタログの作成、軽量なハーネスの設定、ベースラインの動作の比較、またはストレステストの計画を行うとき
references/helper-runtime.md	inspect_skill.py または validate_skill.py を実行するとき。分離された uv/venv コマンド、インタープリターフラグ、利用できない場合の報告を確認
references/naming-and-packaging.md	スラッグの衝突を避け、名前を決め、ロックファイルやセキュリティマニフェストを更新し、リポジトリの更新をパッケージ化するとき

必須事項

• ベンダー固有のスキルを、そのままポータブルなルーブリックにしないでください。
• 由来と衝突リスクを確認せずに、既存のスキルへ上流の skill-creator を再インストールしないでください。
• 要約だけの簡素な説明をリリースしないでください。説明には、簡潔な機能の記述と具体的な発動条件・使用条件を含める必要があります。
• リンクされていない参照ファイルを追加しないでください。
• 具体的な反復可能性の向上と検証手段がない限り、ヘルパースクリプトを追加しないでください。
• skills.sh での人気を品質の証明として扱わないでください。ソース、テスト、セキュリティ態勢、ポータビリティを確認してください。