agents-skills

エージェントスキル

ポータブルなコアとランタイム拡張を分離したまま、スキルバンドルを作成または最新化します。このスキルでは、このリポジトリのデュアルランタイム、カタログ、グラフ、構成に関するルールを定めています。汎用的なひな形作成や評価の仕組みには、Agent Skills のオープン仕様と標準の skill-creator を使用してください。

クイックリファレンス

作業	読み込むもの、または実行するもの
スキルのひな形を作成する	標準の skill-creator、次に frontmatter-reference.md
省略または切り詰められたスキル一覧を修正する	skill-context-budgets.md
スキルを監査する	python3 scripts/validate_skill.py <skill-dir> と maintenance-workflows.md
サポートファイルの境界を決める	skill-patterns.md
ランタイム固有のメタデータを追加する	frontmatter-reference.md
トリガーとナビゲーションの動作をテストする	skill-validation.md
Claude 固有の動作を維持する	anthropic-skills-guide.md
複数のランタイム向けにリリースする	dual-distribution.md
スキル、エージェント、またはその両方を選ぶ	skill-vs-agent-decision.md

コア契約

ポータブルなベースライン：

• 明示的な name と、トリガーを豊富に含む description を備えた skill-name/SKILL.md を必須とします。
• license、compatibility、metadata はポータブルな任意フィールドとして扱います。allowed-tools はオープン仕様に含まれていますが、ランタイムのサポート状況は異なる場合があります。
• 本文は、選択、ワークフロー、完了基準、ナビゲーションに焦点を絞ります。参照情報の詳細は references/ に、決定論的なヘルパーは scripts/ に、テンプレートは assets/ に配置します。
• バンドル単体で使用できる状態を維持します。すべてのサポートファイルは、ワークフローまたはナビゲーションからリンクしてください。

ランタイム拡張：

• ランタイム固有のフィールドと置換処理は、コピーする前に最新の公式ドキュメントで確認します。
• スキルがランタイム固有のヘッダーや呼び出し動作に依存する場合は、compatibility に対象のランタイムを記載し、条件を明示しないポータビリティの主張は削除します。
• Anthropic 専用の仕組みは、ポータブルな例ではなく、frontmatter-reference.md と anthropic-skills-guide.md に記載します。
• agents/openai.yaml は、Codex 向けの補助メタデータとして扱います。SKILL.md は引き続き正規のファイルであり、単独で有効である必要があります。意図に変更があった場合は、意味上の整合性を再検証してください。

ワークフロー

1. スキルを使うべき具体的なユーザータスクを2つか3つ挙げ、スキルを起動すべきでない類似ケースも含めます。
2. 新規作成する前に、グラフと既存のバンドルを検索します。既存のオーナーがすでにその機能をカバーしている場合は、そちらを拡張します。
3. 移植可能なコアを作成します。フォルダー、SKILL.md、name、description、最小限のワークフロー、完了基準を用意します。
4. 対象のランタイムを選び、その後、検証済みのランタイム固有メタデータのみを追加します。
5. 詳細な情報や再利用可能な成果物は別ファイルに分け、必要となる段階で各ファイルへのリンクを追加します。
6. 変更内容に応じた静的チェックを実行し、トリガー、非トリガー、ナビゲーション、ランタイム固有の評価を行います。
7. 本文またはルーティングを変更した場合は、リポジトリのグラフと評価マニフェストを再生成して検証します。
8. 差分を確認し、変更が原因の失敗を修正してから引き継ぎます。観測したルーティング動作をリポジトリのルーティングログに記録します。

完了を主張する際は、その根拠のレベルを明記します。静的なバンドル検証、実際のランタイム読み込み、観測されたルーティング、タスク品質の評価のいずれかです。validate_skill.py の合格で証明されるのは、構造とローカルリンクの正しさです。ランタイムがスキルを読み込んだこと、プロンプトに対してスキルを選択したこと、回答の品質が向上したことは証明されません。

作成、監査、ランタイム、ルーター、状態、グラフに関する正確な手順については、maintenance-workflows.mdを読み込みます。評価の設計とネガティブコントロールについては、skill-validation.mdを読み込みます。

設計ルール

• 共有スキルは、事実に基づき、成果を重視するリファレンス形式を標準とします。コーチング調の文体や、より豊かな行動指針が必要な場合は、ランタイム固有のレイヤーに記述します。
• 実際のユーザーの表現からスキルを選択できるよう、説明を十分に具体的にします。ランタイム側で別途要件がある場合を除き、このカタログの目安である120～180文字、25語のディスカバリー目標の範囲内に収めます。
• ルーターや組み合わせたワークフローは、候補の情報源、情報の補完、理由を伴う適格性フィルター、独立したスコアリング、選択、選択後の検証、副作用という明示的な段階で構成します。
• 情報の補完時に候補や根拠を暗黙のうちに除外してはいけません。入力を保持するか、フィルターの理由を明示します。
• 選択する前に、隣接する候補をそれぞれ独立して評価します。
• ディスカバリーの一覧表示に収めるためだけに、有用な本文の指示を縮めてはいけません。ホスト固有のカタログ制御と段階的な情報開示を活用します。生成された簡易マップは、ネイティブな起動時ディスカバリーをフィルタリングしません。
• 正確な主張を再現可能な対照実験、日付入りの根拠、開示された制限で裏付けられない限り、モデルの品質やトークン節約に関する数値を公開してはいけません。

完了基準

スキルの変更は、以下を満たした時点で完了です。

• 移植可能なフロントマター、ローカルリンク、サポートファイルのナビゲーション、ソースメタデータが、該当する静的チェックに合格している。
• ランタイム固有のフィールドが適切な範囲に限定され、移植可能なものとして提示されていない。
• 選択の意味を変更した場合、トリガーと非トリガーの動作が網羅されている。
• 影響を受けるグラフ、カタログ、長いスキルのマニフェスト成果物が同期されている。
• 回答で使用した既知のバグ、現在のランタイム動作、バージョン固有の回避策が、現行の一次情報源と照合されている。
• 残る失敗がある場合は、根拠を添えて、既存の問題かスコープ外かを特定している。

ナビゲーション

現在の判断に必要なリソースだけを読み込みます。

• skill-context-budgets.md — Codex のカタログあふれ、ホスト固有の制御、検証
• maintenance-workflows.md — リポジトリのレシピ、検証コマンド、完了条件、繰り返し発生する落とし穴
• frontmatter-reference.md — 移植可能なヘッダーとランタイム固有のヘッダーの仕様
• skill-patterns.md — 段階的開示、スクリプト連携、状態管理、合成可能なパターン
• skill-validation.md — 静的検証、トリガー、非トリガー、ナビゲーション、有効性の主張に関する評価
• anthropic-skills-guide.md — Anthropic 固有の動作
• dual-distribution.md — 正規ソースとラッパーの差異に関する制御
• skill-vs-agent-decision.md — 配置と実行境界に関する判断
• data/sources.json — このスキルで使用した日付付きソース

スクリプト：

• scripts/validate_skill.py — 1 つのバンドルを検証します
• scripts/validate_catalog.py — カタログのルートを検証します
• scripts/audit_skill_metadata.py — メタデータ、ローカルインベントリのしきい値、コンパクトインデックスの構造を監査します
• scripts/build_skill_graph.py — ローカルスキルグラフを構築します
• scripts/test_validate_skill.py — バリデーターの回帰テストを行います

関連するスキル：agents-subagents、agents-hooks、および agents-mcp。

ファクトチェック

• 最新の外部情報、フィールドの意味、ランタイムの制限、パッケージングの動作、既知のバグ、バージョン固有の回避策は、一次情報源と照合して検証します。
• 変化する可能性があるランタイム固有のガイダンスには、プラットフォームと検証日を明記します。
• 最新の検証ができない場合は、その制限を明記し、主張を未検証として示します。

学びのループ

過去の判断や落とし穴が関係する場合は、learnings.consolidated.md があれば参照します。必要な履歴の確認や、利用できる代替手段としてのみ learnings.md を使用します。それ以外の場合は、どちらも参照しません。長期的に役立つ新たな知見は agents-skills-feedback-loop/scripts/append_learning.py で追加し、メインのスキル本文をタスクログとして使用しないでください。