build-skill

/build-skill

意図を持って、質の高いスキルの草案を1つ作成します。

このスキルでは、ローカルの前提知識がない、能力の高いシニアエンジニア向けに、スキルを実務ブリーフとして記述します。シェル操作の手順や形式的な作法よりも、不変条件、判断の境界、証拠、停止ルールを重視してください。

引数

引数の文字列には、次の内容を含めてください。

• スキル名
• スキルの機能
• 設計に大きく影響するモード、コマンド、リポジトリのコンテキスト

依頼の内容が不十分な場合は、作業に着手する前に確認の質問を1つしてください。

基本原則

• シェル操作を自動化する仕組みではなく、能力の高いシニアエンジニア向けに記述してください。
• フロントマターの説明は、スキルを見つけてもらうためのものです。ワークフロー全体の要約ではなく、どのようなときに使うかを記述してください。
• 品質を保てる範囲で、プロセスは最小限にしてください。
• レビューのフィードバックは、不変条件を守るか、判断の境界を明確にするものであるべきです。手順を無条件に再導入するものではありません。
• トークン効率は重要です。詳細を必要とする場面がまれであれば、本文には含めず、必要に応じて参照できるようにしてください。

振り分けの判断

草案を作成する前に、次を分類してください。

• スコープ：ユーザーレベルか、プロジェクトレベルか
• 対象パス：そのスコープから判断される、正確な SKILL.md の保存先
• ルールの記述形式：通常のワークフローではなく、ガバナンス、ポリシー、判断のロジックを主に維持するスキルかどうか

確認の質問を1つした後も、いずれかが曖昧な場合は、作業を中止してエスカレーションしてください。

RED フェーズ

スキルを記述する前に、失敗するベースラインを確立してください。

次の場合、ベースライン失敗の検証は必須です。

• 既存のスキルを編集する場合
• ルール、規律、判断の境界を適用するスキルを作成する場合
• エージェントの失敗、逸脱、自己正当化が実際に確認されたことを受けて依頼された場合

失敗の履歴が確認されておらず、仕様が明確な新規ワークフロースキルを作成する場合は、より簡易な RED フェーズでもかまいません。ただし、草案の作成前に、起こり得る失敗モードを少なくとも1つ特定してください。

次の内容を記録してください。

• スキルがない場合に起こること
• 弱いスキルでは防げないこと
• スキルが抑止すべき自己正当化や近道

作成フロー

1. 状況を把握する

   • スキル名と目的を抽出する
   • スコープ、対象パス、ルールの記述形式を分類する

2. 作業場所を分離する

   • すでにワークツリー内で作業している場合は、そのまま続ける
   • それ以外の場合は、ファイルを書き込む前に /isolate を使う

3. 設計する

   • 最初の確認後もスキルの形が明確でない場合は、/brainstorming を使う
   • 短く進めてください。目的は明確にすることであり、長い発見フェーズを行うことではありません。

4. 計画を作成する

   • ai-workspace/plans/build-skill-<name>.md に計画を記述する
   • スキルの仕様、RED ベースライン、対象パス、このスキルにおける「良い状態」を含める

5. 計画をレビューする

   • /plan-review を実行する
   • 良いスキルを評価できるよう、レビュアーに次の観点を伝える。
     • 明確な目的
     • 明確な不変条件
     • 収集すべき証拠
     • 安全な自動処理の経路
     • 明示的な停止境界
     • シェル操作の手順を避けても減点しないこと

6. スキルを1つ草案として作成する

   • 対象のスタイルに沿って、意図を持った草案を1つ作成する
   • デフォルトの3案比較は行わない

7. 草案をレビューする

   • RED ベースライン、不変条件、自己正当化への対策を基準にレビューする
   • 不変条件を守る、または判断の境界を明確にするフィードバックを受け入れる
   • 安全性や明確さを高めずに、手順を増やすだけのフィードバックについては議論する

8. 改善またはエスカレーションする

   • 簡潔で見つけやすく、安全なスキルになるまで修正する
   • 次の場合は、際限なく磨き続けずにエスカレーションする。
     • 確認の質問を1つした後も、依頼の内容が不十分なままである
     • レビューで、未解決の不変条件違反が見つかった
     • レビューでの意見の不一致が、リポジトリのコンテキストでは決められないポリシー上の選択によるものである
     • 修正を繰り返しても、安全性や明確さが高まらず、プロセスだけが増える

9. 検証する

   • プロジェクトレベルの場合は、リポジトリのスキル一覧からスキルを見つけられることを確認する
   • 変更したファイルに必要なリポジトリの検証を実行する

10. 計画をアーカイブして出荷する

• 作業が完了したら計画をアーカイブする
• 通常のリポジトリのワークフローで出荷する

ポリシー代数

スキルが主にガバナンスルール、ポリシー不変条件、または後から編集しても維持すべき決定代数を定める場合に限り、ポリシー代数を使用してください。

ガードレールが少し含まれているからといって、通常のワークフローや手法のスキルにポリシー代数を適用しないでください。

ポリシー代数が適用される場合：

• ドラフトの作成前に、凍結ルールブロックを生成する
• ドラフト内の必要な場所に、その内容を正確に含める
• 公開前に、最終的なスキルをそのブロックと照合して検証する

望ましいスキルの条件

優れたスキルは、次の条件を満たします。

• 見つけやすい
• いつ使うべきかをエージェントに伝える
• 目的をすぐに明確にする
• 重要な不変条件を維持する
• 安全に行動するために必要最小限の証拠を集める
• 自動で実行できることを定義する
• エージェントが停止すべきタイミングを定義する
• 成果を向上させない形式的な手順を避ける

維持すること／避けること

維持すること：

• トリガーを先に示す説明
• 失敗モードを先に考える姿勢
• 簡潔で実務的な表現
• 明示的な不変条件と停止ルール

避けること：

• ワークフローの要約に終始する説明
• 正確な構文が要点でない限り、シェルマクロの手順を細かく並べること
• 複数のドラフトを競わせることを標準にすること
• 詳しさと品質を混同させるレビューの反復