skill-based-architecture

スキルベースのアーキテクチャ

肥大化した単一ファイルのスキルや、分散したプロジェクトルールを、整理されたスキルディレクトリに再構成します。公式の最小限のエージェントスキル契約（name + description）を基盤とし、単一の小さな SKILL.md では足りなくなったときに機能します。

使用するタイミング

• 単一の SKILL.md が約150行を超え、ルール、ワークフロー、背景資料が混在している場合、またはプロジェクトルールが AGENTS.md、CLAUDE.md、CODEX.md、.cursor/rules/、.claude/ などに分散している場合。
• 繰り返し発生するタスクに手順、適切な検証、または信頼できる完了チェックが必要な場合、あるいはユーザーがスキルベースのアーキテクチャやルールの統合を明示的に求めている場合。
• 持続的なルーティングの必要がない一時的なリポジトリ、機能している簡潔な指示システムがあるチーム、小規模なプロジェクトでは使用しないでください。ただし、SBA が明示的に要求された場合は、完全な直接 SKILL.md キャリアを作成してもかまいません。

段階的な厳密化

必要に応じてのみ拡張します。マテリアライザーは、対象の根拠に基づいて内部的に 単一ファイル、軽量フォルダー、または フル／広範 を選択します。ユーザーが階層、プロファイル、機能パック、インストールモードを選ぶことはありません。routing.yaml、タスク実行、タスク完了、メンテナンスチェック、および各ハーネスのサーフェスには、それぞれ独自のルーティング／読み込み／所有権の必要性が求められます。内容が不変の設計理論と現行コードの事実とで絡み合っている場合は、抽象度ごとに分割します（骨格／肉）：抽象理論 → architecture/、コードマップ → references/、チームのスタイル → conventions/、モジュールごとの注意点 → gotchas/（方法論は rules/ に置きます）。内容が減ったら縮小します。詳細：references/progressive-rigor.md。

根拠に基づいて選択する構成

# direct
skills/<name>/SKILL.md
# folder-light or broad: only admitted owners/directories
skills/<name>/{SKILL.md,rules/,workflows/,references/,scripts/}

routing.yaml は、ルートデータに独立した所有者がいる場合にのみ配置します。ルート／ツールのエントリーポイントや登録サーフェスは、利用者がいることが確認された場合にのみ配置します。既存のルートエントリーは保持されます。出力されるルーティング付きエントリーでは、生成された routing.yaml ブートストラップを使用します。直接エントリーは、唯一の SKILL.md 手順を参照します。Cursor の登録は、Cursor が検出された場合、申告された場合、現在使用されている場合、または明示的に要求された場合にのみ行います。情報源については REFERENCE.md を参照してください。

基本原則

1. 簡潔な単一エントリー — SKILL.md は二重の予算を維持します。説明は 25 行以下（トリガーフレーズ＋有効化）、本文は 90 行以下（ナビゲーション）です。網羅するのではなく、案内します。✓ 確認：スモークテストで両方が個別に報告されます。どちらかを超えた場合は、意図のクラスターを分割するか、詳細をサブファイルに移します。
2. フォルダーが採用された場合はスキルフォルダーを 1 つにする — フォルダーを軽量に保ち、幅広い結果を扱うため、正式なドキュメントは skills/<name>/ の下に置きます。直接の結果は、完全な単一の SKILL.md キャリアのままでもかまいません。✓ 確認：出力されるルートエントリーが、別のルール／ワークフロー所有者になっていません。
3. ルール ≠ フロー — 制約には rules/、手順には workflows/ を使います。✓ 確認：rules/ に番号付き手順がある、または workflows/ に「常に／決して」がある場合は、混在しています。
4. 採用時は Routing.yaml をソースにする — 直接のキャリアは SKILL.md に唯一のルートを保持します。複数または共有のルートは routing.yaml のみに置き、そこからルーティング用シェルを生成します。✓ 確認：マニフェストを正当化する独立したセレクターまたは利用者が存在し、適合する同期チェックに合格していますか？
5. ハーネスのサーフェスは読み手に合わせる — 既存のファイル／設定、現在のハーネス、リポジトリ／チームの宣言、または明示的な依頼によって裏付けられるエントリーと登録のみを作成／統合します。✓ 確認：出力されるすべてのサーフェスについて読み手を特定でき、既存のエントリーはすべて保持されていますか？
6. 段階的な厳密さ — 3 つのキャリア（単一ファイル／フォルダー軽量／フル）は必要に応じてのみ拡張し、ユーザーが選ぶパッケージではありません。✓ 確認：生成された各ファイルを必要とした独立した責務を説明できますか？
7. 説明 = 大まかな有効化 — ドメインの境界と、実際のユーザートリガーフレーズを記します。ワークフローのキーワードを列挙したり、ワークフローの手順を要約したりしてはいけません。✓ 確認：説明を書き換えずに routing.yaml のタスクルートを変更できますか。また、説明／ラベルに、本文を開かずともエージェントが実行できる HOW が含まれていませんか？
8. 落とし穴は最も価値が高い — コストの高い落とし穴を積極的に維持し、見つけやすくしておきます。✓ 確認：コストの高い各落とし穴は、references/ の奥に埋もれているだけではなく、採用されたルート所有者（SKILL.md または routing.yaml）によって有効化されていますか？
9. 段階的な開示 — 読み込まれる各ファイルには、タスク実行時に必要となる独立した理由が必要です。条件付きコンテンツは起動時の読み込み対象から外します。すべての実際の呼び出し元が同時に読み込むファイルは、所有権または生成の要件によって別々に保存する必要がない限り、統合します。✓ 確認：ルートの読み込みごとに、今それを必要とするリクエストと、それによって変わる次のアクションを挙げられますか？できない場合は、条件付きでルーティングするか、統合するか、削除します。
10. タスクの実行＋完了 — 新たな望ましい動作を伴わない、明確な読み取り専用または固定契約の保守アクションが 1 つだけなら直接実行します。ユーザーから見える動作、ビジネスフロー／状態、または外部契約を追加／変更するものはすべて、requirement-ready -> Task Anchor -> implementation-ready -> Native Plan -> mutation に従います。現在の状況との整合性を適切な量で示し、各主要ステップの前に簡潔な Anchor Checkpoint を実施します。ワークフローはドメインの手順です。Native Plan はこのセッションの実行時ステップのみを管理し、計画ファイルは永続化しません。完全なプロトコル：references/protocols.md § Task Execution Protocol。
11. 永続記録のルール — 汎用記録はプロジェクトをまたいで一般化します。ビジネスのグローバルモデルはプロジェクト固有のままにしますが、実装を置き換えても存続させる必要があります。✓ 確認：保存先に応じた基準を使います。プロジェクト横断のパターンか、実装を超えて維持されるビジネス上の真実のどちらかであり、どちらにもコードの詳細を混在させません（ref）。
12. 自己保守 — 行数は評価の目安であり、自動的なアクションを意味しません。独立して選択されるタスクがある場合にのみ分割します。所有権または生成によって境界が説明されない限り、常に同時に読み込まれる／変更されるファイルは統合します。✓ 確認：変更前後の読み込みマトリクスによって、定義、条件、境界、理由を失わずに無関係な読み込みが減ったと証明できますか？
13. 保存より有効化 — references/ にあるだけでは「取り込まれた」ことになりません。タスクの経路上にあり、読んだときにエージェントの行動を変える必要があります。到達しても機能しない状態（正しく、経路上にあるが、エージェントが同じように進んでいた状態）は、別種の失敗です。構造上のゲートでは検出できず、判断でしか見抜けません。✓ 確認：通常の経路をたどってください。エントリーに到達すると次のアクション（ファイルを読む、チェックを実行する、ステップを省く）が変わりますか？
14. トークン効率 — Always Read の既定値は空です。追加するには、ワークフロー選択前にすべての実タスクで必要になることの証明が必要です。ドメイン知識とライフサイクル知識は、証拠またはフェーズの境界によって次のアクションが変わる場合にのみ読み込みます。✓ 確認：最初のワークフロー判断を変えずに、起動時の読み込みを後回しにできますか？できる場合は、そのワークフローのチェックポイントに移します。
15. 合理化テーブル — 実際のプレッシャーテストで失敗した際に出た言い訳のみを、一字一句そのまま記録します。✓ 確認：各行は実際の失敗に結び付いていますか？失敗が確認されておらず、ベースラインを設定する意思もない場合は、想像上の痛みとして削除します（ref、フェーズ 9）。
16. 応答の規律 — 短く、正確で、直接的に答えます。プロセスの叙述、自画自賛、不要な確認、要件の言い直しは避けます。✓ 確認：各文は明示的な依頼に応えるものですか？そうでなければ削除します。
17. 証明の主張は分けて扱う — 適合した構造チェック、ソースの処置に関する移行証拠、実環境でのエージェントの動作は、それぞれ異なることを証明します。構造チェックの成功を、意味上または動作上の正しさの証明に格上げしてはいけません。✓ 確認：最終的な主張は実際に実行したレイヤーを正確に示し、利用できない実環境の証拠は判定なしと報告していますか？

よくある落とし穴

1. 対応しているハーネスの抜け — プロジェクトが Cursor／Claude などのリーダーを使えることを実証していても、それに適した登録／エントリがない場合 → そのハーネスは正式なオーナーを見つけられません。逆に、根拠もなくすべてのハーネスを出力すると、恒常的な保守コストが発生します。
2. ルーティングの担い手が不適切 — ルーティング用のシェルが、生成された routing.yaml によるブートストラップを用意せず、「SKILL.md を読んでください」とだけ指示している場合や、直接型のプロジェクトに一貫性だけを理由に空のマニフェストを追加する場合 → どちらも復旧が破綻するか、不要な仕組みが生まれます。
3. 説明が曖昧／スコープが不適切 — 受動的な表現、言語の誤り、狭すぎる説明（「バグ修正」のみ）、またはあらゆるワークフローのキーワードを詰め込んだ冗長な説明 → 自然な依頼を見逃したり、過剰に発動したりします。説明はドメインレベルに保ち、タスクのルーティングは SKILL.md で行ってください。
4. 保存されていても有効化されていない — または有効化されていても機能しない — コストの大きい落とし穴が references/ に記録されていても、オーナーとなるワークフローのチェックポイントで提示されていない場合や、ルート上にあっても背景情報として書かれ、エージェントの次のアクションを変えない場合です。参照可能であることと、有用であることは同じではありません。
5. 具体化中に完了責任が失われる — 対応するワークフロー／Closure のオーナーが、適切な検証や AAR を求めているにもかかわらず、エージェントが主要な作業を終えた時点で完了と判断します。単純なワークフローなら、その責任をインラインで担えます。純粋な Q&A／読み取り専用のタスクは対象外です。
6. プロジェクト固有の記録 — 「自社製品のモジュールでは、〜が見つかった」のようなプロジェクトの物語として書かれた教訓は、現在のコンテキストの外では役に立ちません。記録する前に一般化ルールを適用してください。
7. 長時間のセッションで SessionStart フックがない — /clear や /compact によって、ユーザーが気づかないままコンテキストから SKILL.md が消えてしまいます → ハーネスが対応している場合は SessionStart フックをインストールしてください（references/thin-shells.md § SessionStart Hook）。
8. 複数タスクのセッションでルートを再選択しない — エージェントが新しいタスクにも直前のタスクのルートを使い、古い記憶に基づいて作業して重要なルールを見落とします → タスクごとにルートを再照合してください（段階的な Session Discipline。すべてのシェルでトリガーを伝えます）。
9. Task Anchor の欠落または形だけの使用／長時間タスクの脱線 — エージェントが安定した Goal／Done When を定めずに Simple ではないタスクを始めたり、ネイティブの Plan と重複するラベル付きブロックを出力したりします → templates/skill/workflows/task-execution.md を使用してください。Anchor は実行時の状態として維持し、最終検証／コミット前に reboot-check.md を実行してください。
10. 想像上の問題に基づくエンジニアリング — 仕組み（ルール／スクリプト／ファイル／テンプレートのセクション）を追加する前に、それが実際に起きたことを示す具体的な事例（ファイル＋行番号／コミット／セッション）を提示してください。なければ追加しないでください。過去の例：5 つの幽霊スクリプト（2026-05-19 に削除）、dossier スキーマ（2026-05-19 に削除）、内省優先のモード変更（2026-05-20 に廃止）、観察ログ（2026-05-20 に却下）。

コンテンツの分類

コンテンツの種類 — 抽象度で分類：骨格（アーキテクチャ／ワークフロー／ルール＝不変の理論）対 肉（規約／落とし穴／リファレンス＝現在のコードに関する事実） · 分割ガイド	対象	種別
抽象的な設計理論 — レイヤリング／契約／オーケストレーション／トランザクションの原則、「なぜ」（モジュールマップではない）	architecture/	骨格
コードマップ＋背景情報 — モジュールツリー、ディレクトリ構成、ソースインデックス、ビルド／環境に関する注意事項	references/	肉
ハウススタイル — 命名、パス、コマンド、形式、必須／禁止の規約	conventions/	肉
コードに結びついた落とし穴（症状 → 原因 → 修正）。個別にルーティングされるモジュールごとにのみ分割	gotchas/（複数ファイルへの拡大が必要になった場合に限り gotchas/index.md を選択）	肉
手順を追ったタスクの進め方（プロセス理論）	workflows/	骨格
プロンプト／レポート／ドキュメント · エディター設定（薄いシェル）	docs/ · .cursor/ .claude/	—

マルチスキルと構成

マルチスキルリポジトリ — references/multi-skill-routing.md（運用 + 分割 + 共存）を参照してください。ワークフローから他のスキルを呼び出す方法（埋め込み／逐次実行／サブエージェントへの委任）については、references/skill-composition.md とスターターテンプレート templates/skill/workflows/invoke-skill.md.example を参照してください。

リソース

• WORKFLOW.md — 移行手順（クイックスタート + 9 つのフェーズ + 下流のアップグレード）
• REFERENCE.md + references/ — テンプレート、判断ガイド、アンチパターン、トラブルシューティング、セルフホスティングのルーティングソース
• TEMPLATES-GUIDE.md — スターターテンプレート + メタワークフローテンプレート；EXAMPLES.md + examples/ — 動作上の失敗 + 変更前／変更後のシナリオ