build-cs-skill

build-cs-skill

目的

エージェントが関連するコンテキストを選択し、厳格なゲートを守り、安全に協働し、復旧可能な証拠を残せる、常時読み込まれる最小の制御面を構築します。SKILL.md は薄いハーネスであり、参照資料とリポジトリの事実は厚いコンテキストです。厚いとは、量が多いことではなく、判断に役立つことを意味します。

責任、権限、コンテキストの選択、証拠、停止条件を明確にします。安全な実装上の選択は、実行するエージェントに委ねます。

スコープと参照資料

対象は plugins/codestable/skills/<skill-name>/ または .claude/skills/<local-skill-name>/ です。

現在の判断に必要な参照資料だけを読み込みます。

• references/cs-skill-spec-standard.md：契約の定義、型付き判断、復旧、出力の意味。
• references/cs-skill-quality-gates.md：配置、コンテキスト、進化、実行時の整合性、安全な検証に関するレビューアルゴリズム。
• references/cs-skill-fixture-patterns.md：リスクのあるルーティング、チェックポイント、失敗、互換性、禁止操作のシナリオ。

仕様

data SkillKind
  = OperatorSkill | WorkflowSkill | MethodologySkill | CompatibilityShim | ReferenceDoc

data SkillShape = NoActiveSkill | ThinOperator | ContextualWorkflow | ToolBackedWorkflow
                | ShimSkill | ReferenceSkill
data ProcessProtocol = WorkflowProtocol | DomainProtocol | LifecycleProtocol
                     | OperationProtocol | AlgorithmProtocol | ShimRoute | ReferenceOnly
data RulePlacement = Harness | StageContext | ProjectContext | DeterministicGate | Remove
data DelegationRole = Orchestrator | LeafExecutor

selectSkillShape :: SkillKind -> SkillSource -> SkillShape
selectSkillShape kind source | not (independentSkillNeeded kind source) = NoActiveSkill
selectSkillShape kind source =
  case kind of
    ReferenceDoc      -> ReferenceSkill
    CompatibilityShim -> ShimSkill
    OperatorSkill     -> ThinOperator
    WorkflowSkill
      | deterministicRouter source -> ToolBackedWorkflow
      | otherwise                  -> ContextualWorkflow
    MethodologySkill  -> ContextualWorkflow

selectProcessProtocol :: SkillKind -> SkillSource -> ProcessProtocol
selectProcessProtocol kind source =
  case kind of
    WorkflowSkill
      | lifecycleDriven source -> LifecycleProtocol
      | otherwise              -> WorkflowProtocol
    OperatorSkill
      | algorithmic source -> AlgorithmProtocol
      | otherwise          -> OperationProtocol
    MethodologySkill  -> DomainProtocol
    CompatibilityShim -> ShimRoute
    ReferenceDoc      -> ReferenceOnly

placeRule :: Rule -> RulePlacement
placeRule r
  | mechanizable r                                    = DeterministicGate
  | nonMechanizableSafety r                           = Harness
  | projectSpecific r                                 = ProjectContext
  | stageSpecific r                                   = StageContext
  | everyInvocationNeeds r && changesDecisionOrGate r = Harness
  | otherwise                                         = Remove

buildContextPlan :: SkillShape -> [PlacedRule] -> ContextPlan
buildThinHarness :: SkillShape -> ResponsibilityContract -> ContextPlan -> Markdown

構築プロトコル

1. スコープと責任を確定する

対象と関連するリポジトリ設計上の事実を読み、git の状態を確認して、無関係な編集を保持します。このスキルが担う唯一の成果、その権限の境界、完了を示す証拠、安全でない場合の停止条件を明示します。作成自体にプロジェクトの事前確認は必要ありません。生成するスキルの動作がプロジェクトのセットアップ、リポジトリの事実、成果物の書き込み、または復旧に依存する場合に限り、事前確認を追加します。

独立してインストールできる責任がない場合、または既存のスキル、参照資料、ツールがその責任を担っている場合は、NoActiveSkill を選択します。廃止された v1 CodeStable 名も NoActiveSkill を選択します。移行に関する説明は、互換性シムを再作成する指示ではありません。ReferenceSkill は、知識に独立した配布契約がある場合に限り使用します。

2. 最小限の形を選ぶ

作成前に分類し、全面的なプロトコルのリファクタリングを既定にしないでください。1つのアクションまたは成果物には ThinOperator、段階的な作業や復旧可能な作業には ContextualWorkflow、脆弱な選択を決定論的なルーターまたはゲートが担う場合には ToolBackedWorkflow を使用します。ShimSkill には正規の対象とプリセットだけを含め、新たに承認された配布契約がそのエイリアスを明示的に提供する場合に限り許可されます。ReferenceSkill には、作り上げたワークフローを含めず、知識を収めます。

安全な実装上の選択には自由度を高く、推奨パターンには中程度の自由度を適用します。低い自由度は、脆弱な操作や不変条件に左右される順序に限って使用します。

3. 各ルールの配置先を1つにする

編集前に、現在のルールと追加予定のルールを一覧にします。各ルールについて、その出典、影響を受ける判断、頻度、RulePlacement を記録し、そのうえで placeRule を適用します。

• 機械化できる安全対策と繰り返し行う変換 → スクリプト、フック、またはゲート。
• 段階的な手法、テンプレート、例 → 各段階の参照資料。
• プロジェクトの事実、ADR、学び → リポジトリの CodeStable 成果物。
• 毎回の実行で行う判断と、機械化できない厳格なゲート → ハーネス。
• 一般的な助言、重複する根拠、古い説明、動作に影響しない手順 → 削除。

情報は正規の置き場所を1つだけ持つ必要があります。同じルート、ゲート、手法をハーネスと説明用の参照資料の両方に残してはいけません。

4. ハーネスを作る前にコンテキスト計画を立てる

本文を書く前に buildContextPlan を呼び出します。各コンテキストソースについて、読み込むタイミング、重要な理由、鮮度の確認方法、コンテキストの収集が十分になったと判断する条件、すでに読み込んだ事実の再利用方法を記述します。

エントリー時のコンテキストは、安全に次のアクションへ進むために必要な最小限とします。選択後、該当する段階のプロトコルを1つだけ読み込み、関連する事実や補足情報のみを追加します。すべての参照資料、ADR、メモ、ソースファイルを事前に読み込まないでください。

5. 薄いハーネスを書く

ランタイムカーネルは、トリガー／フロントマター、責任、コンテキスト契約、必要に応じた 判断契約、ハードゲート、必要に応じたコラボレーション、完了／失敗の順に記述します。

レビューの目安は、オペレーターが本文30～80行、ワークフローのフロントドアが60～120行、 シムが最大40行です。この範囲を超える場合は、切り詰めるのではなく、配置を再検討し、 明示的な理由を示してください。

ハーネスには、長い根拠、歴史的な説明、広範なチェックリスト、テンプレート、通常の コーディング手順を含めないでください。新しいエージェントが開始から復旧可能な終了まで の流れを把握するのに役立つ場合に限り、簡潔な ## Operation、## Workflow、または ## Lifecycle を残してください。

6. 有用な場合にのみコラボレーションを追加する

明確な所有権と独立した完了確認がある、範囲の限定された作業のみを委任してください。 プロバイダー固有の役割や固定のエージェント数を事前に決めないでください。

提供するハーネスはバックエンドに依存しないようにし、製品名ではなく機能を記述します。 正確なバックエンド／モデルの指定は ProjectContext に記載してください。 レビュアーを作成する前に、現在のセッションで呼び出し可能なサブエージェントの作成・管理機能を 確認してください。機能の確認を PATH 上の実行ファイルの検索で代用しないでください。 レビュアーの作成方法は、まず新しいコンテキスト、明示的なモデル選択、ワークスペースへの アクセス、ライフサイクル制御、最終レポートを備えた、管理された構造化委任を優先します。 次にホストのサブエージェントを使用し、最後の手段として範囲を限定した単発のエージェント CLI を使用します。品質の最低基準を満たした後に限り、異質性を優先しつつ、安定していて 適格なモデルの中から最も強力なものを明示的に選択してください。

正常に実行中の委任は、その実行と対象に紐づいたままにしてください。照会可能なアクティブな Awaiting 実行は正常な状態です。後からより優れた作成方法が見つかっても、キャンセルや 重複したディスパッチの理由にはなりません。 切り替えは、レポートを伴わない終端失敗、復旧可能な実行識別情報の喪失、機能の不一致、 または対象の無効化が起きた場合に限ります。

ディスパッチの前にトポロジーを分類してください。委任されたエージェントは、明示的な責任が オーケストレーションでない限り、デフォルトで LeafExecutor とします。LeafExecutor は、 別のエージェントをディスパッチしたり、子エージェントを起動またはフォローアップしたり、 自身や別名を呼び出したりしてはいけません。さらなる委任を担うのは Orchestrator のみです。

次のパケット契約を使用してください。

contextPacket = goal + relevantContext + scopeOwnership + boundaries + evidence + returnContract
mainAgentOwnsIntegration = true

委任されたエージェントが実行経路を選択します。呼び出し元のオーケストレーターは、統合、 競合処理、最終確認、永続状態を担います。返却契約を待ってください。返却ペイロードがなく、 復旧可能な実行識別情報もないままアイドル状態になった場合は、タスクを無条件に再送する許可 ではなく、委任の失敗として扱ってください。ワークツリー／ブランチのポリシーはホスト側が 管理します。

7. ハードコントラクトを維持する

Haskell コントラクトゲート

実際に閉じた判断、遷移、ライフサイクル、または不変条件がある場合に限り、Haskell を使用 してください。プロンプトで経路を振り分けるワークフローでは、簡潔な判断の根拠を一つだけ 維持し、並行する文章ベースのルーターを作らないでください。すべてのステージチェックポイントを、 正規のメインエントリにおけるタグ付き再開ドメインと照合してください。Awaiting 状態、 理由、実行識別情報を永続化してください。ステージ型をローカルで閉じるだけでは不十分です。

ランタイム整合性ゲート

ToolBackedWorkflow では、分岐表を複製せずに、ツールのコントラクト、不変条件の境界、 結果、失敗時の動作を記述してください。ハーネス、ランタイム、リファレンス、テストの間で、 永続化スキーマ、正規化、終端状態の優先順位、結果を一致させてください。

各スキルは個別にインストール可能な状態を維持してください。隣接するスキルのファイルや 一元化されたオンボーディング用ランタイムを必須にしないでください。スキル固有のコンテキストや 決定論的なヘルパーは、そのスキルが所有する references/ と scripts/ に配置してください。 プロジェクトのコンテキストは .codestable/attention.md、.codestable/lessons/、 .codestable/work/、またはプロジェクト既存のドキュメントや ADR に記載してください。v2 スキルは 有用な v1 の成果物を検索してもかまいませんが、それらのツールを実行したり、現在の配布対象として 扱ったりしてはいけません。シムは薄く保ってください。ブランチ／ワークツリーのポリシーと エージェントのバックエンドはホスト側が管理します。

8. 圧縮、検証、仕上げ

継続的な進化のため、新たな教訓はすべて placeRule を通じて反映してください。文章を追加する許可だと解釈してはいけません。古くなったルールを置き換え、専門的な知識はコンテキストに移し、ファイル全体を対象に削除を見直してください。追加だけで進化させるのは失敗パターンです。

変更した契約が関連する範囲に及ぶ場合は、関連スキル、共有リファレンス、テスト、ADR の文言も更新してください。実行時スキルに変更履歴や移行の説明を追加してはいけません。

references/cs-skill-quality-gates.md を読み込み、検証計画を作成してください。該当する場合は、その Regression Ladder、Live Host Safety Gate、ファミリーのカバレッジを適用してください。構造上の契約は、シナリオテストや実行環境での適合テストに代わるものではありません。

関連するリポジトリのテストと git diff --check を実行してください。依頼に複数モデルを使った測定実験が明示的に含まれる場合、またはリリースポリシーで求められる場合に限り、eval-cs-skill を使用してください。

失敗時の動作

対象または出力が曖昧な場合、重複する編集内容を維持できない場合、権限の境界が矛盾する場合、必要なコンテキストを特定できない場合、または提案された圧縮によって復旧や安全性に関する契約が失われる場合は、NeedsHuman を返してください。現在の対象、阻害要因、維持したファイル、安全な次のアクションを報告してください。

出力契約

以下を報告してください。

• 対象スキルのパスと SkillShape。
• 責務と選択した自由度を一文で示したもの。
• ルールの配置先：ハーネスに保持、ステージまたはプロジェクトのコンテキストに移動、自動化、または削除。
• コンテキスト計画とコラボレーション契約、または不要とする理由。
• 変更したファイル。
• 検証結果と省略した検証レイヤー。
• 未解決のメンテナー判断事項と、次に実行する具体的なアクション。

実際に行った編集と推奨事項を区別してください。行数の削減だけを根拠に成功を主張してはいけません。チャット履歴のない新しいエージェントでも、安全に復旧でき、利用可能な状態を維持してください。