aif-distillation

蒸留

ソース資料を有用なスキルに変換します。出力は単なる要約ではなく、資料からベストプラクティス、判断ルール、ワークフロー、確認事項、例を取り入れた、実際に使えるスキルです。

ステップ 0：設定とスキルのコンテキストを読み込む

最初に、 .ai-factory/config.yaml が存在する場合は読み込み、次の設定を確認します。

• language.ui：プロンプト、質問、進捗報告、最終的な要約に使用する言語
• language.artifacts：生成するスキルパッケージの内容（SKILL.md、references/、`examples/）に使用する言語
• language.technical_terms：翻訳する成果物での技術用語の扱い。設定がない場合は keep を既定値とします

config.yaml が存在しない場合は、次の既定値を使用します。

• language.ui：en
• language.artifacts：language.ui と同じ
• language.technical_terms：keep

.ai-factory/skill-context/aif-distillation/SKILL.md を読み込みます。 このファイルが存在する場合は必ず読み込んでください。

スキルコンテキストのルールは、このスキルに対するプロジェクトレベルの上書きとして扱います。生成するすべてのスキルファイル、参照資料、例、ソースマップの方針、最終レポートに適用されます。

入力

$ARGUMENTS には、次のいずれかを 1 つ以上指定できます。

• ローカルファイル
• ローカルディレクトリ
• URL
• 任意の --name <skill-name>
• 任意の --path <directory>：生成したスキルパッケージのディレクトリを、{{skills_dir}} ではなくカスタムの出力ルートに保存します
• 任意の --update：重複するスキルを作成するのではなく、既存のスキルを改善します
• 任意の --redact-source-map：生成するソースマップのファイルとセクションをすべて省略し、ソースの正確なタイトル、URL、ローカルパス、リポジトリパス、リンク参照定義が出力に記載されないようにします
• 任意の --split：1 つの資料セットから、複数の焦点を絞ったスキルを作成します
• 任意の --split-by <strategy>：分割方法を選択します
  • auto（既定）：ユーザーの目標、トリガー、ワークフロー、ソースのトピック、ユースケースからスキルの境界を推定します
  • goal：分野にかかわらず、ユーザーの目標や達成すべき作業ごとに分割します
  • topic：ソースの主なトピックや章ごとに分割します
  • workflow：エージェントが繰り返し実行するアクションごとに分割します
  • audience：ユーザーの役割や実装コンテキストの違いに応じて分割します

対象のスキル名が指定されていない場合は、資料のトピックまたはユーザーの目標から、clean-code-style、api-design-rules、decision-making、writing-feedback、meeting-facilitation のような、簡潔で汎用的な小文字とハイフンによる名前を導き出します。

ファイルを書き込む前に、最終的な対象スキル名を検証してください。

• ^[a-z0-9]+(?:-[a-z0-9]+)*$ に一致する必要があります。
• 空の名前、長すぎる名前、., ..、ドット、パス区切り文字（/ または \）、絶対パス、Windows のドライブパス、隠し名前は拒否します。
• ユーザーが AI Factory 自体の開発を明示している場合を除き、予約済みの aif-* 名は拒否します。
• 出力ルートを解決します。--path <directory> が指定されている場合はその値を使用し、それ以外の場合は {{skills_dir}} を使用します。
• 相対パスの --path は、現在の作業ディレクトリを基準に解決します。出力ルートが存在しない場合は作成し、既存のファイルに解決される場合は拒否します。
• 最終的な保存先パスを解決し、ファイルの作成または更新を行う前に、そのパスが解決済みの出力ルート内にあることを確認します。

単一スキルモードの既定の保存先：<output-root>/<skill-name>/。<output-root> は、--path が指定されている場合はその値、それ以外の場合は {{skills_dir}} です。

分割モードの既定の保存先：生成する各子スキルの <output-root>/<prefix>-<child-scope>/。既存のスキルとの衝突を防ぐため、分割後のすべての子スキル名に共通の名前空間プレフィックスを付けてください。--name が指定されている場合はそれを優先的にプレフィックスとして使用し、指定されていない場合は書籍のタイトルまたは主な資料のタイトルから簡潔なプレフィックスを導き出します。--redact-source-map が指定されており、ソースの正確なタイトルを公開すべきでない場合は、公開用の名前空間として --name を使用するか、中立的なトピックのプレフィックスを導き出します。

ユーザーが AI Factory 自体の開発を明示している場合を除き、スキルをパッケージの skills/ ディレクトリに保存しないでください。

ワークフロー

1. ソースを準備します。

   • 通常のテキスト、Markdown、JSON、YAML、HTML、コードファイルは、そのまま読み取ります。
   • 大きなフォルダーや PDF には、Python 3 インタープリターが利用可能な場合に限り、{{skills_dir}}/aif-distillation/scripts/material-prep.py を使用します。python3 --version、python --version、py -3 --version、py --version の順に実行して検出し、正常終了して Python のメジャーバージョンが 3 と報告された最初のコマンドを使用します。
   • ヘルパーを実行するときは、選択したインタープリターを python3 ...material-prep.py や py -3 ...material-prep.py など、具体的なコマンド形式に展開します。任意の Python ペイロードは実行しないでください。事前承認済みのツール契約で対象となるのは、バージョンの確認と material-prep.py の実行のみです。
   • Python 3 を利用できない場合は、ヘルパーを実行しないでください。アクセス可能なテキストファイルを Read／Glob／Grep／find／wc で直接サンプリングし、PDF や非常に大きなソースについてはユーザーにテキストまたは Markdown 形式でのエクスポートを依頼し、網羅性が低下する場合はその旨を明確に伝えてください。
   • URL の場合は、ソースと、内容の理解に必要な重要なリンク先ページを取得します。

2. コピーではなく、要点を抽出します。

   • 応用可能な原則、ワークフロー、ヒューリスティック、チェックリスト、用語、失敗パターンを抽出します。
   • 出力構成を決める前に、ソース内の例、特にコードスニペットを洗い出します。
   • 後から網羅性を確認できるよう、ソースの例をトピックごとに分類します。
   • 不可欠な場合に限り、ソースからの短い抜粋を残します。言い換えを優先し、出典を示してください。
   • 説明的なアドバイスはエージェントが実行できる手順に変換し、ソースの例は独自の再利用可能な例に置き換えます。

3. 単一スキルか分割スキルかを選びます。

   • --split または --split-by が指定されていない場合は、単一スキルモードをデフォルトとします。
   • 分割モードでは、境界マップを作成する前に共通の名前空間プレフィックスを決定します。--name が指定されていればそれを使用し、指定されていなければ正規化した書籍名または資料名を使用します。提案するすべての子スキル名は <prefix>- で始めてください。
   • 分割モードでは、作成前にスキル境界マップを作成します。マップには、提案するプレフィックス付きスキル名、ユーザーが達成する目的、トリガーの説明、担当するソーストピック、必要な参考資料や例、重複のリスクを含めます。
   • レビュー、計画、診断、書き換え、指導、意思決定、テスト、ファシリテーション、監査、トラブルシューティングなど、個別にトリガーされるべき独立した目標が資料に含まれる場合は、分割モードを優先します。
   • 分割する子スキルには、抽象的なソースのテーマではなく、ユーザーの目標や達成したい作業に基づいた名前を付けます。目標の分類は資料の分野に合わせて選びます。ソフトウェア分野なら refactoring-review、test-design、framework-fit-review、ライティング分野なら argument-edit、style-review、運用分野なら incident-triage、runbook-review、マネジメント分野なら decision-brief、stakeholder-analysis、学習分野なら concept-coach、practice-drill などが考えられます。
   • ユーザーがその名前を公開用の分類として明示的に求めている場合を除き、framework-evolution、principles、philosophy、chapter-4、mindset、overview など、曖昧なライフサイクル名や章名は避けてください。
   • トリガー、ワークフロー、参照資料の要件が実質的に重複する場合は、表現がわずかに異なるだけの小さなスキルに分割せず、候補を統合してください。
   • 生成する子スキルは、それぞれ単独で役立つものにしてください。明確なフロントマター、焦点を絞ったワークフロー、関連する参考資料や例を含めます。--redact-source-map が指定されていない場合は、それぞれに独自のソースマップを含めます。指定されている場合は、references/SOURCE-MAP.md もソースマップのセクションも作成しないでください。

4. 対象スキルパッケージを設計します。

   • 対象の SKILL.md は、目的、起動条件、ワークフローに焦点を絞ります。
   • 生成するスキルは、ディレクトリ名とフロントマターから内容が分かるようにします。説明文は動作を表す動詞で始め、そのスキルが何をレビュー、改善、生成、またはチェックするのかを示します。
   • 生成するすべての SKILL.md の冒頭付近に、このスキルが何をするのか、いつ使うのか、どのような出力を作成すべきかを平易な言葉で記載します。スキルの目的を理解するために、ユーザーがソース資料を確認する必要がないようにします。
   • 詳細な知識は references/ に配置します。
   • 再利用可能なプロンプト、ケース、変換済みの例は examples/ に配置します。
   • 資料でコード例を用いてプログラミングを教えている場合は、オリジナルの変換前／変換後のスニペット、または簡潔なコードパターンを含む例のファイルを作成または更新します。逐語的なコピーが適切でないという理由だけで、コード例を省略してはいけません。
   • 書籍規模または広範なコード資料の場合は、コードに関わる主要なトピックすべてを、応用した例でカバーするか、そのトピックに例が不要な理由を記載します。1つのファイルが内容の浅い寄せ集めになってしまう場合は、例を複数のファイルに分けます。
   • ワークフローで繰り返し可能な処理が必要な場合に限り、スクリプトを追加します。
   • 書き込み前に、--path または {{skills_dir}} から <output-root> を解決します。--path は生成するスキルパッケージの親ディレクトリとして扱い、スキルパッケージ名として扱ってはいけません。
   • 単一スキルモードでは、選択した簡潔な名前を使い、パッケージを <output-root>/<skill-name>/ に保存します。
   • 分割モードでは、各子パッケージを <output-root>/<prefix>-<child-scope>/ に直接保存します。子スコープだけで内容が明らかな場合でも、共通のプレフィックスを省略してはいけません。
   • --redact-source-map が指定されている場合は、references/SOURCE-MAP.md を作成せず、生成ファイルに「Source Map」セクションを作成せず、下書き中に誤って作成した空の SOURCE-MAP.md を削除します。--update モードでは、ユーザーが明示的に削除または書き換えを依頼しない限り、既存の空でない SOURCE-MAP.md は変更せずに残します。
   • ソース資料またはユーザーが別の言語を明示的に指定していない限り、生成するスキルの内容には、解決済みの language.artifacts を使用します。

5. 書き込み前に既存の内容を確認します。

   • 対象スキルに一致するリファレンスまたは例がすでにある場合は、それらをその場で更新します。
   • 名前を変えただけの重複ファイルを作成してはいけません。
   • 有用な既存の内容を保持し、不足している内容、またはより的確に整理された内容のみを追加します。
   • 分割モードでは、<output-root> にある既存の兄弟スキルも確認し、起動条件が重複していないか調べます。--update を使う場合は、新たな類似の子スキルを作成するのではなく、一致するスキルを更新します。

6. 有用性を検証します。

   • スキルでは、エージェントが何をすべきか、いつ実行すべきか、良い出力とはどのようなものか、どのような間違いを避けるべきかを示します。
   • 名前と説明は、呼び出しに使えるものにします。ユーザーが「このスキルは具体的に何をするのか」と尋ねるようなら、完了前に名前を変更するか、起動条件を書き直します。
   • リファレンスは、情報密度が高く、内容をたどりやすいものにします。
   • 例では、装飾的な内容ではなく、判断や変換の方法を示します。
   • ソース資料に意味のあるコードスニペットや実例が含まれていた場合、生成するスキルには応用した例を含める必要があります。応用した例が抜けている場合は、完了前に修正します。
   • 例の網羅範囲はソース資料の範囲に合わせます。--redact-source-map が指定されていない場合は、これをソースマップに記録します。指定されている場合は、ソースマップファイルやセクションを作成せずに、内部で網羅性を検証します。
   • プロジェクトの成果物を読み書きする場合は、生成するスキルに成果物の管理／設定ポリシーのセクションを含めます。
   • 生成する品質ゲートスキルは、/aif-verify のリファレンスにある aif-gate-result の契約に従う必要があります。
   • 分割モードでは、各子スキルに、それぞれ異なる起動条件を設定します。2つのスキルが同じ依頼で起動し、エージェントに同じ作業を指示する場合は、完了前に統合します。

必須の補足ガイダンス

スキルを要約して生成または更新する前に、以下をお読みください。

• references/DISTILLATION-PROTOCOL.md
• references/OUTPUT-STRUCTURE.md
• references/LARGE-MATERIALS.md

呼び出しパターンについては、examples/REQUESTS.md をご利用ください。

成果物の所有権

• 主な所有対象：<output-root>/<skill-name>/ 配下の生成または更新されたスキルパッケージ、または分割モードでの <output-root>/<prefix>-<child-scope>/ 配下にある複数の直接の子スキルパッケージです。<output-root> は、ユーザーが --path <directory> を指定しない限り {{skills_dir}} です。
• 読み取り専用のコンテキスト：.ai-factory/config.yaml、既存の AI Factory コンテキスト成果物、および更新モードで選択した対象スキルを除く既存のスキルファイルです。
• 設定ポリシー：language.ui、language.artifacts、language.technical_terms のみを設定に応じて扱います。config.yaml は書き込まないでください。