skill-authoring

スキルの作成

段階的な情報開示、明確なコンテキストへのポインター、確認可能な完了条件、動作の一元管理によって、予測可能なエージェントスキルを作成します。

原則

• トリガーフレーズごとにスキルを1つにします。 1つのスキルが受け持つのは、ユーザーが実際に口にする1つの用件です。同じ発話に応える2つのスキルは1つにまとめます。互いに関係のない複数の発話に応える1つのスキルは、複数に分けます。
• 名詞ではなく、動詞で分けます。 動詞が振り分けを決め、名詞は衝突を招きます。create と refine は別々のスキルです。Feature、Epic、Story は、ユーザー自身がどれを望んでいるか分からないことが多いため、種類を推測する1つのスキルにします。
• 誤った振り分けのコストに応じて、分割の重みを決めます。 誤った振り分けによって誤った 書き込み が行われる場合は統合し、明らかな誤答が返される場合は分割します。読み取り専用の誤った振り分けはすぐに分かりますが、誤った変更はそうとは限りません。
• 曖昧さを解消するサブコマンドが必要なスキルは、2つのスキルに分けます。 本文の冒頭でユーザーにモードを尋ねるなら、ルーターがすでに判断しているべきです。
• どの分岐にも共通する手順は SKILL.md に記載します。特定の分岐だけで使う参考情報は、いつ読むべきかを示すポインターの先に置きます。
• 参考情報は1階層までとし、それぞれ単独で利用できるようにします。
• 説明文は1024文字未満、スキル本文は500行未満にします。この本文の上限が適用されるのは SKILL.md のみです。ディレクトリ全体も計測し、行数が示唆するだけの問いに答えて解決します。呼び出し元が習得しなければならない語彙はいくつあるか？ トリガーフレーズが1つなら、呼び出し元が習得する語彙も1つです。このパックの2つのスキルは、SKILL.md が余裕を持って上限内に収まっている一方で、合計行数がそれぞれ4,029行と7,784行に達しました。
• 決定論的な検証や変換はスクリプトに任せます。

重複

量ではなく、層ごとに判断します。

プロンプトの重複は禁止です。 同じ指示、プロトコル、ドメインルールが2つのスキルに現れる場合、所有するスキルがなければ参考用スキルに切り出し、モジュールがすでに担っている場合は既存のインターフェースを適用し、能力ではなくルールであれば一度だけ記載します。切り出す目安は呼び出し元が2つあることです。1つだけなら、その呼び出し元のスキルに含めます。

コードの重複は想定内です。 スキルを単独でインストールできるように、同梱スクリプトは自己完結させます。境界を越えて参照するのではなく、ヘルパーをコピーしてください。

エージェントが作業中のリポジトリで 実行時 に必要とするルールは、スキルに含めなければなりません。リポジトリ固有の AGENTS.md、意思決定記録、用語集は、そのチェックアウト内の作業を規定するものであり、インストールしたスキルには付属しません。そのため、それらを参照するスキルは、インストールしたすべての人にとって機能しません。

命名

名前は対象を表します。対象のドメイン名を動詞の前に置き、スキルが受け持つトリガーフレーズに合わせて、<domain>-create、<domain>-review の形式にします。同じ階層のスキルでは、同じものを同じ言葉で表します。

スキルが 何についてのものか を問い、その答えで名前を決めます。特定の製品やシステムについてのスキルには、その製品やシステムの名前を付けます。本当に汎用的なスキルには、製品固有のスキルと一緒に公開される場合でも、汎用的な名前を付けます。範囲を誇張する接頭辞は、付けないよりも悪いものです。スキルが持っていない知識を約束してしまいます。

名前は、人がフォルダーのないフラットな一覧で読みます。振り分けは別の課題であり、説明文で解決します。プロジェクトキー、リポジトリ名、ファイル名、ツール名、識別子の例など、文字どおりの固有名詞は残してください。文字どおりのトークンは、利用できる中で最も強い手掛かりです。

その手掛かりは存在するだけで働くため、対象外だと断る目的で説明文に文字どおりの名称を入れてはいけません。「ABC-123 のようなキーはスプリントではありません」と書くと、まさに拒否しようとしている依頼に対する候補として、そのスキルが選ばれてしまいます。トークンを使わずに対象外であることを示します。「単一の課題キーではなく、チームとボードを対象とします」のように記載してください。

ホストリポジトリで作業する

スキルを設計する前に、リポジトリに記載されている規約を確認してください。通常は AGENTS.md、用語集、各種決定記録などです。これらの規約は、これから作成するスキルを制約します。ただし、インストール後のスキルには適用されないため、スキル内に記述する内容は、これらの規約を参照できることに依存してはなりません。

リポジトリにスキル集が公開されている場合は、どのスキルが人間による呼び出しを想定しているか、名前に接頭辞が必要か、スキルをどのように組み合わせるか、メンバーシップマニフェストの場所、テストの保護対象が定められていると考えてください。その内容に従ってください。

インタビューの依存関係

スキルの作成またはインタビューには、草案を作成する前にスコープを厳しく検証するインタビュースキルが必要です。このコレクションでは /grilling が該当します。ホストから名前を指定して呼び出せない場合は、草案の作成に進まず、作成にはそのスキルが必要だと伝えてください。監査と統合では、インタビューを開始しない限り必要ありません。

条件に応じた参照

該当するブランチを1つだけ読み込んでください。そのブランチ内の参照先に、後で必要となる仕様、説明、アーキテクチャ、スクリプト、品質に関する参照資料が示されています。

• 新しいスキルを一からインタビューし、草案を作成してレビューするには、references/create.md を読んでください。「スキルを作成する」「SKILL.md の草案を作成する」「この専門知識をパッケージ化する」などの場合に該当します。
• 既存のスキルをレビュー、修正、診断するには、references/audit.md を読んでください。「なぜまったく起動しないのか」「この SKILL.md を確認する」「このスキルを改善する」などの場合に該当します。
• 重複するスキルを少数に統合する場合、または統合しすぎていないかを確認する場合は、references/consolidation-guide.md を読んでください。最後に、references/create.md のフェーズ5のレビューを行ってください。

完了条件

選択したブランチのレビューチェックリストに合格し、参照されたリソースがすべて解決でき、古いスキル名のもとに動作が重複して残っておらず、変更した .py ファイルがすべてホストのリンターに合格したら、作業は完了です。