プロジェクトのドキュメントから、AIエージェント用のスキルを作って最新に保つ

## 編集の前に、スキルを誰が管理しているかを見分ける ファイルを作成または更新する前に、各スキルがどのように所有されているかを判断します。ドキュメントは提供しているもののエージェントスキルのパッケージを管理していないプロジェクトには生成スキル、独自のスキルをすでに提供しているプロジェクトには同期スキル、意図的に精選された専門知識には手書きスキルを使用します。 これらのワークフローを混在させないでください。生成スキルはドキュメントから統合して作り、同期スキルは上流のスキルソースからコピーし、手書きスキルはタスクの対象に明示的に含まれていない限り変更しません。 ## ドキュメントから、エージェントの作業に役立つ内容だけを選ぶ 機能、判断点、実践的な利用パターン、動作する例、エージェントが別の手法よりもある手法を選ぶべき状況に重点を置きます。タスクの実行を実質的に改善する知識を優先します。 利用者向けの導入説明、インストール手順、一般的な入門資料、宣伝的な文章、高性能なモデルがすでに確実に扱える概念は省きます。ドキュメントをそのままコピーするのではなく、ソース資料を書き直して統合します。 スキルはコンパクトに保ちます。異なる概念を扱うために必要な参照ファイルだけを作成し、重複ファイルを避け、パターンの仕組みだけでなく、なぜ、またはいつ使うべきかも説明します。 ## 新しいプロジェクトを登録簿に足し、スキルを生成する 新しい生成ソースを、そのソースの場所と安定したプロジェクト識別子を含めて、リポジトリの正本となるプロジェクト登録簿へ追加します。追跡されないローカルコピーを作るのではなく、リポジトリが対応しているワークフローを通じてソースを初期化または同期します。 プロジェクトの機能と規約を理解できる範囲まで、プロジェクトのドキュメントとプロジェクト固有の生成指示を十分に読みます。有用な資料を、中核概念、機能、ベストプラクティス、高度なワークフローなどのカテゴリに整理します。 登録した生成ソースの識別子と名前が一致する出力ディレクトリを作成します。参照ファイルを記述し、スキルの索引を構築し、正確なソースリビジョンを含む生成メタデータを記録します。 ## 生成スキルを、ドキュメントが変わった所だけ更新する 生成メタデータに記録されたソースリビジョンを読み、現在のソースと比較します。ソースの差分は、生成スキルを規定するドキュメント領域に限定します。 その差分の影響を受ける参照ファイルだけを更新し、必要に応じて索引のプロジェクトバージョン、生成日、トピック表、説明を更新します。影響を受けない参照ファイルは保持し、ソースリポジトリが進んだという理由だけで無関係な内容を再生成しないでください。 レビュー後、記録されたリビジョンを更新に使用した正確なリビジョンへ置き換え、次の比較で信頼できる基準線として使えるようにします。 ## 上流が管理するスキルは、手で直さずコピーで同期する 上流で管理されるスキルについては、どのソーススキルをコピーし、どの出力名を使用するかを登録簿から判断します。出力名は意図的に上流ディレクトリと異なる場合があるため、ソース名だけから推測してはいけません。 初回の取り込みでは、設定されたスキルツリーをコピーし、上流のリビジョンを同期メタデータに記録します。更新時は、記録されたリビジョンと現在の上流スキルディレクトリを比較し、設定対象の変更されたファイルだけをコピーして、記録されたリビジョンを進めます。 同期スキルの内容を手作業で変更してはいけません。修正は上流の所有者へ提供し、同期ワークフローを通じて取り込むことで、ローカルコピーのずれを防ぎます。 ## 各参照ファイルへのリンクを並べた、短い索引を作る スキルの索引には、ケバブケースの名前、簡潔な機能説明、来歴メタデータ、生成日または同期日、関連するツールまたはプロジェクトのバージョンを含む、有効なフロントマターを設定します。 短い案内文を追加してから、参照ファイルを明確なカテゴリにまとめます。各トピックには簡潔な説明と対応する参照ファイルへの相対リンクを示し、エージェントが現在のタスクに必要な資料だけを読み込めるようにします。 索引は簡潔でナビゲーションに特化させます。参照ファイルの全内容を索引内で重複させたり、存在しないファイルの項目を追加したりしないでください。 ## 参照ファイル1つに、実践的な話題を1つだけ書く 各参照ファイルには、安定した名前と焦点を絞った説明を含むフロントマターを設定し、その後に明確な概念タイトルを置きます。無関係な機能をまとめず、ファイルごとに一貫した機能またはワークフローを一つ扱います。 実践的な利用指針、概念が実行可能な場合は動作するコード例、主要な制約、推奨パターンの根拠を含めます。エージェントの判断や実行に役立たない背景は省きます。 内容の統合に使用したドキュメントを特定するソース参照を最後に置きます。スキルをソース資料のコピーに変えることなく、その参照を追跡可能に保ちます。 ## スキルを作った時のソースのリビジョンと日付を記録する 生成スキルには、ソースの場所、正確なソースリビジョン、生成日を記録します。同期スキルには、上流スキルの場所、正確な上流リビジョン、同期日を記録します。 索引のバージョンを実際のソース状態と一致させ、リポジトリの方針に従って直近の生成日または同期日を使用します。内容の基になったものより新しいプロジェクトバージョンやリビジョンを記載してはいけません。 登録簿を、対応対象となるプロジェクトとソースの場所を示す正本の一覧として扱います。登録簿がすでに管理している場合は、変更され得るリポジトリURLや所有権の対応関係をスキルファイル間で重複させないでください。 ## 最後の差分で、壊れたリンクや古いリビジョンが無いか確かめる 完了前に、ソースの分類、登録簿の項目、出力名の規則、索引のリンク、参照ファイルのフロントマター、カテゴリ構成、リビジョンメタデータ、ソース引用がすべて一致していることを確認します。 生成された内容がコピーではなく統合されたものであること、同期された内容に手作業によるずれがないこと、手書きスキルが対象範囲に含まれないまま変更されていないこと、各参照ファイルがエージェントに異なる価値をもたらしていることを検証します。 最終差分で、無関係なファイル、過剰な参照ファイル、古いバージョン、欠けている例、壊れたリンク、記録されていないソース変更がないかレビューします。完全な生成または同期を妨げたソースやツールの制約があれば報告します。