AI向けの研究用スキル集を整理し、確かめた物だけを公開する

## 各スキルを、研究の流れのどの段階か1つに決めて分ける フォルダを選ぶ前にライブラリの使命を定義する。研究向けのコレクションは、問いと文献レビューから、発想、データ準備、実験、学習、評価、デプロイ、情報伝達までの流れを支援する必要がある。 そのライフサイクルを反映した番号付き、または別の方法で安定させたカテゴリを使う。専門スキルの詳細な指針を重複させずに作業を振り分ける、中央のオーケストレーションスキルを一つ維持する。 提案された各スキルについて、次を行う。 - ライフサイクルの段階と、所管する一つのカテゴリを特定する。 - 解決するユーザーの問題と、使用する条件を明記する。 - 隣接する代替手段を挙げ、それらの方が適する状況を説明する。 - 同じタスクに担当が二つあるように見える、重複した範囲を避ける。 分類体系をナビゲーションの契約として扱う。所管または収録内容が変わるたびに、カタログ、件数、説明、ロードマップを更新する。 ## 1つのスキルに要るファイルを、1つのフォルダにまとめる 各スキルに必須のメインガイドを置く専用ディレクトリを用意する。スキルに必要な補助フォルダだけを追加する。 - `references/`：詳細な公式文書、APIメモ、チュートリアル、問題のパターン、リリース履歴。 - `scripts/`：繰り返し実行できる補助処理。 - `templates/`：再利用できる出発点。 - `examples/`：完全で代表的な実装例。 - `assets/`：ガイドで使うコード以外の素材。 メインガイドは入口であり、百科事典ではない。運用の道筋を説明し、その一階層下にある詳細な参考資料へ直接リンクする。必須の指示を見つけるために、ある参考資料から別の参考資料へ読者を送る連鎖を作らない。 スキルの実行に必要な全ファイルをパッケージ内に収め、検証、アーカイブ作成、レジストリ同期が一つの明確な境界を対象に動作するようにする。 ## メインの説明書の先頭に、名前や版などの決まった項目を書く すべてのメインガイドは、固定のフィールド契約に従う有効なYAMLフロントマターで始める。 - `name`：一意のケバブケース識別子。できれば活動を表す動名詞にする。 - `description`：スキルが何を行い、いつ使うかの両方を示す三人称の文章。 - `version`：動作または指針が変わるたびに更新するセマンティックバージョン。 - `author`：レジストリのソース分類で使う所管情報。 - `license`：配布ライセンス。 - `tags`：タイトルケースの用語。ただし、定着した略語は大文字のままにする。 - `dependencies`：明示的なバージョン制約を持つ任意のパッケージ。 YAML構文で必要な場合を除き、スカラー値を引用符で囲まない。説明は設定された文字数上限未満に収め、helper、tools、utilitiesのような曖昧な識別子を避ける。 記述子は目視ではなく解析して検証する。必須フィールドの欠落、無効なバージョン、名前の重複、不正な依存関係は、作業を止めるエラーとして扱う。 ## メインの説明書は短く保ち、詳しい話は別の資料へ移す メインガイドは200〜500行を目標にする。不可欠な指針が500行を超える場合は、必要な判断を圧縮して失うことも、入口を際限なく肥大化させることもせず、高度な詳細を直接参照できるファイルへ移す。 ガイドには次を含める。 - 簡潔な目的と明確な開始条件。 - 関連する代替手段との比較。 - 複雑な用途に対応する完全なワークフローを二つまたは三つ。 - 順序が重要な場面でそのまま使えるチェックリスト。 - 具体的な入力例と出力例。 - 品質上重要な作業を検証し、修正し、繰り返すフィードバックループ。 - 具体的な解決策を伴う、よくある問題の節。 読者に十分な能力があることを前提にする。タスクから明らかな基本概念ではなく、分野固有の選択と失敗の形を説明する。すべてのフェンス付きコード例に言語識別子を付ける。 信頼できる情報源から充実した参考資料を構築し、分野に適する場合は約300 KBなどの明示的な網羅目標を設ける。容量指標を満たすために文書を水増ししてはならない。完全性、追跡可能性、実務上の有用性を目標として維持する。 ## スキルを足す・直す時は、毎回同じ手順で進める 新しいスキルでは、次を行う。 1. 承認済みのロードマップ項目と所管カテゴリを選ぶ。 2. 標準のパッケージ構造を作成する。 3. 本文を拡充する前に記述子を書いて検証する。 4. 主要なワークフローと判断の指針を作る。 5. 必要に応じて、直接参照できる資料、補助処理、テンプレート、例を追加する。 6. 代表的な実際のタスクでスキルをテストする。 7. 同じ変更の中でカタログ、統計、ロードマップを更新する。 既存のスキルでは、記述子契約を維持し、バージョンを上げ、メインガイドを上限内に収め、不足しているワークフローまたはトラブルシューティングを追加し、代表的な使用例を再実行する。 機能ブランチと範囲を絞ったレビュー依頼を使う。パッケージ全体とカタログの変更をまとめてコミットし、リポジトリが不完全なスキルを掲載することが決してないようにする。 ## 自動のチェックと実際の作業で、スキルを確かめる レビュー前に機械的な確認を実行する。 - メインファイルが存在し、そのフロントマターを解析できることを確認する。 - メインガイドの行数を200〜500行の目標と照合する。 - すべてのコードフェンスに言語が指定されていることを検証する。 - 選択した目標に対する参考資料の網羅度を測定する。 - 参照されるファイルがメインガイドのちょうど一階層下に存在することを確認する。 - 名前、タグ、バージョン、依存関係がそれぞれのスキーマに従うことを確認する。 次に動作を検証する。 - 現実的な入力を使って各主要ワークフローを実行する。 - 明記された結果と復旧手順を検証する。 - よくある失敗を少なくとも一つ発生させて確認する。 - そのスキルが適切な手段でない場合に、代替手段が推奨されることを確認する。 - 実質的な編集を行うたびに繰り返す。 大きな参考資料フォルダが曖昧なワークフローを補うことはなく、洗練された概要が使えない例を補うこともない。 ## 変わったスキルを、承認の後に自動で登録先へ上げる 既定ブランチへの承認済み変更で、どの最上位スキルパッケージが変わったかを検出する。変更された各パッケージについて、次を行う。 1. メインガイドを必須とし、その記述子を解析する。 2. 宣言された所管方針に従ってソースを分類する。 3. オペレーティングシステムとバージョン管理の隠しファイルを対象外にして、完全なパッケージをアーカイブ化する。 4. 対応するレジストリ名前空間へアーカイブをアップロードする。 5. レジストリのレコードを作成または更新する。 6. スキップまたは失敗したパッケージを、同期済みとして黙って扱わずに報告する。 エンドポイントと認証情報は、自動化プラットフォームのシークレット保管領域だけに保存する。復旧とテスト用の手動開始を用意するが、自動モードと手動モードの両方で同じ検証およびパッケージ化の処理が動くようにする。 無害なバージョン付き変更でワークフローを検証し、自動化の実行を調べ、レジストリのレコードとアーカイブを確認する。パイプラインを起動するためだけに、レビューされていない編集を使わない。 ## 版の番号が変わった時だけ、新しいパッケージを公開する 既定ブランチにあるパッケージ記述子のバージョン変更を起点として、パッケージを公開する。ロックファイルだけの変更で新しいリリースを公開してはならない。 パッケージ管理ツールのバージョンコマンドを使い、記述子とロックファイルを一緒に進める。互換性に応じてパッチ、マイナー、メジャーを選び、リポジトリのリリース手順で別のコミットが必要な場合に限って、バージョン管理タグの自動作成を抑止する。 長期間有効なレジストリ資格情報ではなく、設定済みの信頼できるパブリッシャーを通じて認証する。公開するすべてのアーティファクトに、ビルドの来歴または同等のサプライチェーン証明を添付する。 公開前に次を検証する。 - 信頼できるパブリッシャーのIDがリポジトリ名とワークフロー名に完全に一致する。 - 環境変数が古い資格情報によって信頼済み認証を上書きしていない。 - コミット済みのロックファイルからクリーンインストールが成功する。 - 新しいバージョンが前のリビジョンと異なる。 - パッケージの内容がレビュー済みのソースと一致する。 公開がスキップされた場合、または認証に失敗した場合は、バージョン関門または信頼済みのIDを修正する。来歴を迂回してはならない。 ## 数を増やすより、今あるスキルを良くする ディレクトリ数ではなく、実行可能な専門知識でライブラリを評価する。有用なスキルは、信頼できる実践を、エージェントが実行、検証、復旧できる形へまとめる。 マージ前に次を確認する。 - 範囲が一つのカテゴリに適合し、既存の担当と重複しない。 - 記述子、命名、バージョンの規則に合格する。 - メインガイドが焦点を保ち、必要な詳細すべてに到達できる。 - 必要な箇所に、ワークフロー、チェックリスト、例、代替手段、トラブルシューティングが揃っている。 - 実際のタスクで指針を検証できる。 - カタログ、ロードマップ、アーカイブ自動化、パッケージのリリースデータが一貫している。 ほぼ重複するスキルを追加するより、既存のスキルを改善する。浅い例を数多く並べるより、機能するフィードバックループを備えた完全なワークフローを一つ用意する。指標が明確さまたは正しさと衝突する場合は、有用な判断の指針を維持し、その指標が適切な代替尺度でなかった理由を記録する。