agent-skill-authoring

エージェントスキルの作成

エージェントスキルを作成、改善、分割、統合、改名、監査するとき、またはその導入状況の評価を設計するときは、この機能を使用してください。継続的に適用される慣習を、適切に構成され、見つけやすいスキルにまとめます。また、異なる動作の証拠を混同せずにルールの改訂を評価するための比較基準を、作成者に提供します。

ここで作成するスキルは、agentskills.io 形式に準拠します。ホストプロジェクトで有効なスキル一覧と、トピックからスキルへのルーティングについては、各スキル独自の description 検出メタデータと、スキルルート配下のディレクトリ一覧を参照してください。ホストが AGENTS.md などの文書化されたインデックスも管理している場合は、それも同期してください。

ガイドライン：

• MUST：変更対象に対応するバンドル済みバリデーターを実行してください。frontmatter の編集後は scripts/check-skill-frontmatter.mjs、本文の編集後は scripts/check-skill-body.mjs、参照ファイルの追加、移動、改名後は scripts/check-skill-references.mjs を実行してください。判断に迷う場合は、3つすべてを実行してください。これらは合わせて、このスキルのほかの箇所には記載されていない、frontmatter、命名、検出可能性の長さ制限、参照の関連付けに関するルールを適用する手段です（audit-checklist.md を参照）。
• SHOULD：タスクを通じて、再利用できる慣習、古くなったガイダンス、繰り返し発生するレビュー上の問題、または不足しているプロジェクトルールが明らかになった場合は、スキルの更新を提案または実施してください。スキルのメンテナンスは、作業から継続的に役立つ知見が得られたときに行うものであり、限定的な修正のたびに行うものではありません。
• SHOULD：一般化できる知見が得られなかった場合は、スキルのメンテナンスを省略し、その旨を明記してください。

この文書における「MUST」、「MUST NOT」、「REQUIRED」、「SHALL」、「SHALL NOT」、「SHOULD」、「SHOULD NOT」、「RECOMMENDED」、「MAY」、「OPTIONAL」は、RFC 2119 に記載されているとおりに解釈してください。

スコープ設定と MECE

scoping-and-mece.md では、以下について説明しています。

• 一貫性のあるスキルの境界、スキル名、分割、統合、または信頼できる情報源の場所を選ぶ
• 新しいガイダンスを追加する前に、隣接するスキルとの重複を確認する
• 移植可能な判断やワークフローの意味を、プロジェクトポリシー、ホストでの実行、スキルの配布から切り分ける
• 詳細なルールを移行する前に、複数の要素が混在する段落や参照を分類する
• ベンダーまたはランナー固有のスキルがツール非依存の上位スキルの下位にある場合、各セクションをメカニズムか判断かに分類する
• セクションの長さやトピックの増加を、構成を見直すべき兆候として活用する

能力のフレーミング

capability-framing.md では、以下について説明しています。

• スキルを、エージェントが読む文書ではなく、エージェントが得る能力として捉える
• スキルが可能にする活動に名前を付け、避けるべき文書形式の接尾辞を把握する
• description の冒頭節、H1、導入段落の語調
• 既存のガイドライン形式のスキルを、要求事項を変えずに所定の順序で再構成する

Frontmatter と命名

frontmatter-and-naming.md では、以下について説明しています。

• 検出に不可欠な SKILL.md の frontmatter を作成または編集する
• 標準で必須および任意のメタデータと、ホスト固有の呼び出し制御を区別する
• スキルのディレクトリ名を選び、name フィールドと一致させる
• 選択したホストと配布経路に照らして、ホストプロジェクトのハーネス用フィールドを評価する

説明文の作成

以下については、description-writing.md を参照してください。

• description フィールドをバイト上限に合わせて作成、短縮、または監査する方法
• 4 つの要素からなる規約（トリガー、識別情報、境界、対象範囲）と、ホスト側の一覧表示で切り詰められる場合に犠牲にしてよいのが最後の要素だけである理由
• トリガーと識別情報を 1 つの冒頭節にまとめる方法、および単独では機能しない 2 つの半端な節（単語を並べただけのリスト、「〜する機能」）
• スキルが対応しない領域を、競合するスキルへ振り分ける引き継ぎ方法とともに明示する方法
• スキルの対象範囲を広げすぎずに、ユーザーが使いそうな言い回しや症状に基づくトリガーを加える方法
• 約 640 バイトというコーパスの平均目標値、およびこれがスキルごとの上限ではなく中心値である理由

本文のスタイル

以下については、body-content-style.md を参照してください。

• スキル本文や参照ファイルの実質的なセクションを作成または改訂する方法
• 簡潔なトピックの説明、例、ガイドラインの箇条書きのバランス
• バージョンを固定するセクションや、ベンダーのオプションを網羅するセクションで、上流のドキュメント URL を引用する方法
• RFC 2119 に準拠する規範的な要件の箇条書きを、親のルーティングセクションではなく詳細な参照資料に配置する方法

段階的な開示

SKILL.md に記載するのは、次の3つだけです。このスキルでどのような機能を提供するか、スキル内で無条件に適用されるルール、そしてどの参照先をどのような場合に読むかを示すルーティングです。それ以外の規範的な記述、つまり MUST や SHOULD の詳細、手順、表、例はすべて参照ファイルに記載します。ルールを本文に残すかどうかは、そのルールが重要かどうかではなく、読者がルーティングの判断を下す前に知る必要があるかどうかで判断します。たとえば、変更ループ機能では、読み取り専用の作業と変更を伴う作業の区別を、読者が実装の参照先を選ぶ前に把握できる必要があります。この契約自体も、それが定めるルーティングの判断を下す前に必要です。そのため、以下のポインターの先に置かず、ここに記載しています。同じ理由で、その直後にある重要なルールの判定基準も、先送りせずに直接記載しています。

エージェントが SKILL.md を読み込み、参照ファイルを開かない場合に、そのルールがなければ誤った出力をするなら、そのルールは重要なルールです。そのルールの記述は適切な参照ファイルに置き、親のルーティングには、その参照ファイルが該当する状況を記載します。該当する状況を別途「必ず読む」項目として繰り返しても、選択に必要な情報は増えません。したがって、ルーティングは See ... for: または See ... when のリンクと、状況を説明する箇条書きだけで構成し、**Guidelines:** ブロックは設けません。

ガイドライン：

• エージェントが SKILL.md だけを読み込んだ場合に、そのルールがなければ誤った出力をするなら、そのルールを重要なルールとして扱わなければなりません。固定の順序、閉じた選択肢、または違反が出力から自明ではない制約がこれに該当します。それ以外は詳細説明として扱わなければなりません。
• 重要なルール自体の記述、その RFC-2119 の箇条書き、およびそれを詳しく説明するすべての内容は、そのルールを規定する参照ファイルに置かなければならず、SKILL.md に置いてはなりません。
• 参照先へのルーティングは、See ... for: または See ... when のリンクに続けて、その参照先を確認する状況、ユースケース、条件を示す説明的な箇条書きを置く形式に限定しなければなりません。
• 空のブロックや、読むべき参照先だけを記載したブロックであっても、参照先へのルーティングに **Guidelines:** ブロックを付けてはなりません。参照先の選択条件は、説明的な箇条書きで示さなければなりません。
• 以下の例外に該当する場合を除き、参照ファイルに重要なルールの記述がある場合は、SKILL.md でその記述や RFC-2119 の箇条書きを再掲してはなりません。
• ルールの発動条件が、そのスキルの範囲内で無条件に成立する場合は、ルール自体の記述を SKILL.md に残し、参照ファイルへ移してはなりません。毎回適用されるポインターは、読む手間を増やすだけで、何も揺るがしません。

progressive-disclosure.md を参照してください。内容は次のとおりです。

• スキルを単一ファイルのままにするか、references/ に分割するかの判断
• 3つの役割から成る契約と「ルーティングの判断を下す前に必要かどうか」の判定基準の詳細、および重要なルールの判定基準と無条件適用範囲の例外との関係
• 重要なルールの判定基準を網羅した分類表と、参照先のルーティングで示す選択条件
• スキルファイルや参照ファイルが大きくなりすぎたことを示すサイズのしきい値
• スキルの分割時や参照先の構成変更時に使う、説明のみの親ルーティングセクションの形式
• 関係のない参照先をスキップできるよう、参照先の選択条件を限定して記述する方法
• ルーティングの箇条書きで、ある事実が存在すると告げるのではなく、その事実、つまりフラグ、上限、ルールを名前で示す方法
• 親のルーティングの箇条書きから RFC-2119 形式の要件を表すキーワードを取り除き、重複したルールではなく、ルーティングの手がかりとして維持する方法
• 本文に置くルールを、ルーティングのリストの前後どちらに配置するかの判断

相互参照と検出

cross-referencing.mdでは、以下について説明しています。

• スキルや参照ファイルの追加、名前変更、移動、削除、リンク
• スキル間で詳細なルールをコピーせず、信頼できる情報源を一つ選ぶ方法
• トピックベースのスキル間参照の使用、スキル内の相対リンクの検証、スキルの検出情報の最新状態の維持（ホストが管理する文書化されたインデックスも含む）
• 任意のオーナー文書やプロジェクトホスト文書がない場合も含め、該当するオーナーとホストにのみ処理を振り分ける方法

プロジェクトスキルの類型

project-skill-archetypes.mdでは、以下について説明しています。

• スキャフォールディングの工程で必要とされる、構造、コンポーネント、UI／デザインのプロジェクト固有スキルの作成
• 3者間のオーナーシップの関係と、各類型の骨格、トピックのチェックリスト、またはテーブルパターン
• 実例と機械的な境界チェックを用いた、類型の骨格の拡充

スキル採用評価の設計

skill-adoption-evaluation.mdでは、以下について説明しています。

• スキル採用評価の設計、または実行前の意図的なルール改訂の比較
• タスク、処置、採点者、機会、主張範囲に関する契約を固定しつつ、採点者の回答を実施者向けの資料から分離する方法
• 自然なタスクと境界制御を分け、不完全な集団や該当項目がゼロの集団も保持する方法
• 合成レポートのチェックと実運用での適格性確認を区別し、範囲を網羅するQAプラクティスにのみ証拠の十分性の判断を振り分け、それ以外の場合はレビュー上の制約を保持する方法

監査と検証

audit-checklist.mdでは、以下について説明しています。

• 複数のスキルの監査、またはスキルツリーの品質の報告
• 同梱の3つの構造バリデーター、check-skill-frontmatter.mjs、check-skill-body.mjs、check-skill-references.mjsの実行方法と、それぞれが検証する編集の種類
• 同梱のリンク鮮度監査（scripts/link-freshness/check.mjs）を定期実行して、引用したベンダーのURLが404になっていないか確認する方法、確認済みのリンク切れのみをエラーとする理由、およびpull_requestトリガーがリクエスト偽造の攻撃要素となる理由
• インベントリ、スキルの検出、セクションの構造、RFC-2119の箇条書き、トピックベースのスキル間参照、相対リンクの確認
• 重複、古くなった前提、孤立した参照、信頼できる情報源へのリンクの不足の特定
• 範囲を限定した変更をライブラリ全体の移行に拡大せずに、オーナーシップと移植性のチェックリストを適用する方法

保護されたMarkdownlintの実行

markdownlint-execution.mdでは、以下について説明しています。

• 作成者のチェックアウトからインポートせずに、利用側のプロジェクトに同梱のネイティブESMパッケージをインストールする方法
• スキル／コレクションのルート、生ソースのスナップショット、対象を絞った部分チェックの宣言
• インライン、設定、または無視による抑制を使わずに、AS001の実際のYAMLとAS010の明示的なフェンス閉じを実行する方法
• 真の警告と、読み込み／実行時の失敗、および実効的なカバレッジの欠落の区別
• 既存の構造監査とネットワーク監査を維持しながら、共有ルール／コンテキストの実行を拡張する方法