skill-system-foundry

スキルシステムファウンドリー

AI に依存しないスキルシステムを構築し、発展させるためのメタスキルです。

このスキルは、スキル（オプションの機能を含む）とロールからなる2層アーキテクチャの作成と保守を管理します。このシステムで作成されるすべてのスキルは、Agent Skills 仕様に準拠します。また、公式ベンダーガイドの作成に関するベストプラクティスを取り入れています。ロールの契約は、プラットフォーム間でシームレスにデプロイできるよう、ツール統合ガイダンスに沿っています。

重要： 機能は、親スキル内のオプションで粒度の細かいサブスキルです。デフォルトでは機能を作成しないでください。インテグレーターから明示的に求められた場合、またはドメインの特性上、分割が明らかに必要な場合（異なるトリガーコンテキストを持つ3つ以上の個別の操作がある場合）のみ導入してください。まずは単独のスキルから始め、正当な理由がある場合にのみルーター＋機能へ発展させてください。

アーキテクチャの概要

スキルシステムは、スキルとロールからなる厳密な2層アーキテクチャに従います。依存関係は厳密に下方向へ流れ、その逆はありません。機能は、自身がオーケストレーションされていることを認識してはなりません。ロールはスキルを参照できますが、他のロールを参照してはなりません。

依存関係の方向が規定するのは、レイヤー間の参照であり、オーケストレーションの開始場所ではありません。次の2つの有効なオーケストレーションパスがあります。

Path 1:  orchestration skill → roles → skills (with optional capabilities)
Path 2:  skill (standalone or router) → role(s) → skill's capabilities

• パス1 — 調整専用スキル。 ドメインをまたいでロールを順序付ける、簡潔な独立型スキルです。ドメインロジックは含みません。
• パス2 — 自己完結型スキル。 ドメインスキルが、インタラクティブなワークフローロジックのために1つ以上のロールを読み込みます。スキルが機能を所有し、ロールが責任、権限、制約に加えて、引き継ぎルール、順序付け、インタラクションパターンを提供します。

各パスの判断チェックリストと制約については、references/architecture-patterns.mdを参照してください。

各レイヤーには明確な責任があります。

• スキル — 正準となる、AI に依存しない知識とロジックです。Agent Skills 仕様に準拠します。スキルはタスクを直接処理する（単独型）か、分割が妥当な複雑なドメインに限り、オプションで機能へルーティングします。
• ロール — 正準となる、AI に依存しないオーケストレーション契約です。複数のスキル／機能を組み合わせながら、責任、権限、制約に加えて、引き継ぎルールとワークフローの順序付けを定義します。

機能

タスクに応じて適切な機能にルーティングしてください。

機能	トリガー	パス
skill-design	スキル、機能、ロール、マニフェストの作成、アーキテクチャの決定、説明文の作成	capabilities/skill-design/capability.md
validation	スキルの仕様への準拠確認、システムの一貫性監査	capabilities/validation/capability.md
migration	フラットなスキルをルーター＋機能パターンへ移行	capabilities/migration/capability.md
bundling	配布用にスキルを zip バンドルとしてパッケージ化	capabilities/bundling/capability.md
deployment	ツールへのデプロイ、ラッパーやシンボリックリンクの設定、ツール固有の拡張機能の使用	capabilities/deployment/capability.md

関連する機能ファイルのみを読み込んでください。タスクが明示的に複数の機能にまたがる場合を除き、複数の機能を読み込まないでください。

共有リソース

共有リソースはスキルのルートに配置し、各機能から相対パスで参照します。各機能の末尾にある## Key Resourcesブロックには、複数の機能に関わるリソースと読み込みトリガー（内容ではなく、いつ読むか）が記載されています。アクション固有のリソースは、該当する本文の手順内でインラインリンクされています。ルーターはディレクトリを索引化し、機能はファイルを索引化します。

references/ — 機能が必要に応じて読み込むガイダンス

複数の機能で共有される横断的な参照資料です。機能から相対パスで参照します。

assets/ — 新しいコンポーネントのひな形

スキル、機能、ロール、マニフェストのテンプレートです。新しいコンポーネントを作成する際にコピーし、内容を記入します。

scripts/ — 検証、スキャフォールディング、バンドル、測定ツール

6 つのエントリポイント（validate_skill.py、audit_skill_system.py、scaffold.py、bundle.py、stats.py、yaml_conformance_report.py）と共有ライブラリモジュールがあります。すべてのエントリポイントは、機械可読な出力を得るための --json に対応しています。

stats.py は、スキルのコンテキストコストを示す、バイト数ベースの 2 つの指標を報告します。discovery_bytes（SKILL.md の frontmatter ブロック）と load_bytes（SKILL.md と、推移的に到達可能なすべての機能ファイルおよび参照ファイル。ただし scripts/ と assets/ は除外）です。バイト数はディスク上の状態を示す決定論的な指標であり、トークナイザーに基づく正確な値ではありません。モデル間で絶対値を比較するのではなく、編集による推移を確認してください。

基本原則

1. Agent Skills 仕様への準拠

すべてのスキルは Agent Skills 仕様（agentskills.io）に準拠する必要があります。登録されたスキルディレクトリには、適切な YAML frontmatter を含む SKILL.md が必ずあります。name フィールドは親ディレクトリ名と一致し、小文字とハイフンのみを使用し、最大 64 文字です。description フィールドは最大 1024 文字で、スキルの機能と、どのような場合に起動するかの両方を説明します。三人称で書くことは、このプロジェクトの慣例であり、仕様上の要件ではありません。

注：capability は、ディスカバリー内部で使用するサブスキルです。そのエントリポイントは capability.md です。capability の frontmatter は任意です（単独で利用できるように移植・昇格する可能性が高い場合に使用してください）。

段階的開示は、すべてのレベルで維持されます。

• レベル 1：メタデータ（約 100 トークン）— name と description。常にコンテキストに含まれます
• レベル 2：指示（5000 トークン未満／推奨上限 500 行）— 起動時に読み込まれます
• レベル 3：リソース（無制限）— スクリプト、参照資料、アセット。必要に応じて読み込まれます

2. トークンの節約

ディスカバリー用トークンは常にコンテキストに含まれ、コストが高くなります。実行用トークンのコストが発生するのは、機能を起動した場合だけです。機能ごとではなく、ドメインごとに 1 つのスキルを登録してください。ルーターとなる SKILL.md は簡潔に保ち、詳細は capability や参照資料に移してください。ドメインで capability が必要になるまでは、単独のスキルを優先してください。

3. 簡潔さ

モデルはすでに十分に賢いものです。モデルがすでに把握している内容は追加せず、本当に必要なコンテキストだけを加えてください。情報を一つずつ検討し、「モデルにこの説明が本当に必要か」と問いかけてください。詳しくは references/authoring-principles.md を参照してください。

4. 自由度

タスクの壊れやすさに応じて、具体性の度合いを調整してください。柔軟なタスクには高い自由度を、壊れやすい操作には低い自由度を設定します。詳しくは references/authoring-principles.md を参照してください。

5. 一度だけ記述し、どこでも適応する

ドメイン知識は、正規のレイヤー（スキルとロール）に一度だけ記述します。ドメイン知識を変更する場合、変更するファイルは 1 つだけです。必要に応じたツール固有のデプロイ先ポインターは、ユーザーが任意で管理するカスタマイズです。デフォルトではシンボリックリンクを使用してください。メンテナンスが不要で、信頼できる情報源が一つになり、この原則にも沿っています。Windows の開発者モードが無効、または git 設定で core.symlinks=true が設定されていない開発者がチームにいる場合や、ポインター側でツール固有の調整が必要な場合に限り、ラッパーファイルを使用してください。判断ガイドについては references/tool-integration.md を参照してください。

注意点

このメタスキルを使う際に最もよくある落とし穴です。references/anti-patterns.md を読み込もうと思う頃には、すでに問題に直面していることが多いため、ここに掲載しています。各項目から詳しい説明を参照できます。

• 機能を早まって分割すること。 機能は任意です。まずは単独構成を基本としてください。相互に排他的なトリガーを持つ異なる操作が3つ以上ある場合にのみ分割します。anti-patterns.md#premature-capability-creation を参照してください。
• 兄弟機能への参照。 機能は独立しています。兄弟機能を参照してはいけません。機能をまたぐオーケストレーションはロールの役割です。anti-patterns.md#capability-aware-capabilities を参照してください。
• 深いネスト。 最大2階層（ルーター → 機能）です。サブルーターが必要な場合は、別のトップレベルスキルに分割してください。anti-patterns.md#deep-nesting を参照してください。
• ファイル参照規則の混在。 Markdown のリンクは、ファイルを含むファイルを基準に解決されます。これは標準的な Markdown の仕様であり、Foundry 固有の規則ではありません。機能のエントリーポイント（capability.md）からは、機能内の参照に references/<file> を、共有スキルルートのリソースへの参照に ../../<dir>/<file> を使います。ネストされた機能の参照ファイル（capabilities/<name>/references/foo.md）からは、相対パスの階層が変わります。path-resolution.md を参照してください。
• 説明をトリガーではなくドキュメントとして書くこと。 description フィールドは、見つけてもらうための主要な手段です。README の要約としてではなく、100以上のスキルから選択するモデルに向けて書いてください。具体的に三人称で記述し、トリガーとなるフレーズを含めてください。authoring-principles.md#writing-descriptions を参照してください。
• チームのOSを確認せずにシンボリックリンクを使うこと。 シンボリックリンクはデプロイ先を示す方法として標準ですが、Windows のチェックアウト環境で、開発者モード（OSレベルのシンボリックリンク権限）も git 設定の core.symlinks=true（チェックアウト時に Git がシンボリックリンクを実体化するかどうかを制御します。git config core.symlinks true で設定します）もない場合、問題が通知されないまま発生します。これを標準とする前に、チームのOS構成を確認してください。いずれかの前提条件を保証できない場合は、ラッパーファイルを使用してください。anti-patterns.md#symlinks-without-team-platform-verification を参照してください。