メインコンテンツまでスキップ

skill-foundation

Claude Code と Codex 向けに、ルール・出力の契約・hooks・違反例・収束テストを備えたスキルを作ります。出力の形を決めて機械で検査し、別の AI が使ったときの結果の違いも確かめます。

渡す情報​

何を受け取り、何を出力するスキルかを伝えます。名前、対象の製品、言語、収束テストの扱いも指定できます。指定がなければ、名前は依頼から決め、対象は Claude Code と Codex の両方、日本語の依頼なら日本語にします。

収束テストは独立した AI を複数回動かします。既定では直前に回数を示して実行するかを聞きます。最初から決める場合は「収束テスト: 実行」か「収束テスト: 省く」と指定してください。省いた場合も、違反例と最終検査は実行します。

依頼例​

skill-foundation を使って、git diff から日本語のコミットメッセージを書くスキルを作ってください。
Claude Code と Codex の両方で使います。コミット操作は行わず、メッセージをテキストファイルに出力してください。
収束テスト: 省く。

plugin 経由では Claude Code の /skill-foundation:skill-foundation、Codex の plugin スキルから呼び出します。

導入と hooks​

hooks を含む導入には skill-foundation plugin を使います。スキル・hooks・専用エージェントを同じ単位で導入・更新・削除します。正本は utils/skills/authoring/skill-foundation/ に維持し、plugin のビルドが正本全体を変更せずに同梱します。

plugin を使わずにどのプロジェクトからでも使う場合は、本体を ~/.claude/skills/skill-foundation(または正本へのリンク)に置き、ターミナルで python3 ~/.claude/skills/skill-foundation/scripts/setup.py --scope user を実行します。hooks は ~/.claude/settings.json と ~/.codex/hooks.json に登録され、$HOME の置き場のスクリプトを呼びます。スクリプトが無い場合は何もしません。Codex の互換配置として ~/.agents/skills/skill-foundation を本体へのリンクにします。作ったスキル、実行記録の .skill-runs/、指摘の収集記録の .skill-feedback/ は、スキルを使ったセッションのプロジェクトに置かれます。プロジェクトは作業ディレクトリから .git を辿って決まります。以前の版で --project ~ に登録した hooks は、$CLAUDE_PROJECT_DIR 側の置き場を指すため、ほかのプロジェクトでは失敗します。上のコマンドで登録し直すと置き換わります。

このプロジェクトでは両製品の plugin 管理へ導入し、.codex/config.toml と .claude/settings.json で有効にしています。Codex の互換配置として、.codex/skills/skill-foundation は正本へのシンボリックリンクにし、.codex/hooks.json にも直接 hooks を登録しています。Claude Code の呼び出しは /skill-foundation:skill-foundation、Codex は plugin または互換配置のスキルを選択します。再起動と hooks の信頼確認については plugin の導入手順を参照してください。

進め方​

  1. 依頼が対象かを確かめ、受け取るものと出力するものを決めます。
  2. 名前・対象・言語・置き場を決め、骨組みを作ります。
  3. 前提となる仕様や既存の決まりを調べ、出典と確認した日を残します。
  4. ルールと出力の契約を dev/spec.json に書き、スクリプトと hooks で検査します。
  5. 正しい見本が通り、ルールを破った出力が止まることを違反例で確かめます。
  6. 実行する場合は収束テストで出力の違いを測り、別の AI に操作の記録を分析させて手順を改善します。
  7. 配置・hooks・最終検査を確認し、結果を記録します。

既定の配置では、両製品向けの本体は .claude/skills/<名前>/、Codex の .agents/skills/<名前> は本体へのリンクです。このリポジトリのように共通正本を管理する場合は、utils/skills/.../<名前>/ に本体を置き、対象製品すべての標準位置からリンクできます。最終検査ではリンク先と hooks の登録を確認します。スキルごとのルールや検証結果は、最後に生成する HTML カタログでも確認できます。

python3 <plugin-root>/runtime/skill-foundation/scripts/catalog.py --project .

既定の出力は .skill-runs/catalog.html と、その隣の catalog/ 以下のスキル別ページです。収束テストを実施した場合は、エージェントの操作と分析も表示します。

利用中の指摘を改善へつなぐ​

新しく作るスキルには、成果物への指摘・修正前後の実ファイル・承認・スキルの版を収集する hooks を追加機能として必ず同梱し、既定で登録します。スキルの本文やルールに収集の指示は入れず、有効な hooks からだけ案内します。hooks を無効にしてもスキル本来の作成・検査・完了は機能し、収集側の失敗も完了を妨げません。完了後に届いた指摘も、原文と成果物の版を結び付けて .skill-feedback/<skill-name>/ に保存します。

修正版の承認は、python3 <skill>/scripts/feedback.py review で起動する localhost の確認画面で受け取ります。ユーザーは修正前後・差分・元のファイルを見て承認します。会話の相づちや AI の判断を承認にはしません。

feedback.py export --out <新しいデータセット> は承認済みの事例を共通形式で取り出します。foundation の feedback_eval.py --dataset <データセット> --skill <スキル> --out <新しい作業場所> は、スキルのコピーと改善用 Eval・収束テストの候補を作ります。評価条件の一般化と入力の不足をユーザーと確認してから、独立した実行で元の版と改善候補を比べます。再現に必要な入力ファイルは、スキルの利用時に feedback.py context --file <入力ファイル> で保存します。

0.4.0で生成したスキルを移行するときは、更新後の foundation の scripts/init_skill.py --dir <スキルの場所> --update-runtime を実行します。共通スクリプトを更新し、以前の収集ルールを生成本文から除きます。単体導入では hooks の登録も更新します。新規導入で登録を省く場合は install.py --no-hooks、登録済みの hooks を停止する場合は製品側の無効化を使います。pluginで配る場合は配布物を再生成します。

成果物の例​

依頼でhooksの方針を指定し、最新の同梱仕様からコミットメッセージを書くスキルを生成した。hooksなしで本来の処理を実行し、合成Stopで指摘収集の追加機能を検証した。#111で加わったユーザー単位の登録を、作業場所内の仮のホームで検証した。

到達点:skill-foundationの自己テスト、hooks方針の決定・生成・配置・単体利用、追加機能の直接検証、仮のホームでのユーザー単位の登録に合格。Evalと独立AI収束は省略、実ユーザー承認は未発生。

実行した依頼​

最新の同梱 write-commit-message の仕様と手順から、ステージ済みの差分とチケットIDを受け取り、日本語のコミットメッセージを書くスキルを作成してください。Claude CodeとCodexの両方を対象とし、1行目は「チケットID 要約」、本文は変更ファイルの数に応じた箇条書きにします。コミット・プッシュは行いません。公開作例の隔離実行なので、実ユーザーとの価値の確認が必要なEvalと、独立AIによる収束テストは省きます。hooksの方針は all(Claude CodeとCodexの両方で検査と指摘収集を使い、隔離プロジェクトの設定に登録)とします。指摘収集hooks・確認画面・共通形式は追加機能として同梱し、生成スキルの本文やルールに収集指示を加えないでください。hooksなしでも本来の価値が機能することを確かめてください。

作成元: 最新の正本に同梱した assets/example/write-commit-message。
題材のstaged差分は src/app.py と src/util.py の新規2ファイル、入力チケットは abc-12。
生成後はhooksを発火させずにスキルを使ってメッセージを作成し、収集記録が無いことを確認する。その後、合成Stopイベントを直接渡し、追加機能の提示版保存を検証する。コミット・プッシュは実行しない。
指摘や確認画面での実ユーザー承認はこの作例では発生していない。会話による承認や合成承認を収集実績に混ぜない。

実出力の抜粋​

以下は保存した原本の冒頭です。全文は原本から取得できます。

## 結果

skill-foundation: 完了(検証に合格)

## 作ったスキル

- 名前: `write-commit-message`(コミットメッセージを書く)
- 目的: ステージ済みの差分とチケットIDから、このリポジトリの形式のコミットメッセージを1つ書く
- 本体の置き場: `.claude/skills/write-commit-message`
- Codex の置き場: `.agents/skills/write-commit-message`(本体へのリンク)
- 対象の製品: Claude Code、Codex
- hooks の方針: 出力の検査 使う、登録する製品 Claude Code・Codex、利用中の指摘 集める、登録先 プロジェクトの設定(依頼の指定 `all` で決めた)
- 言語: 日本語(ja)
- 起動: 依頼の内容から自動で選ばれる。明示は `/write-commit-message`(Claude Code)、`$write-commit-message`(Codex)
- 入力: `ticket`(チケットID。start の前に聞く)
- 出力: `commit-message`(コミットメッセージ。`.skill-runs/write-commit-message/out/commit-message.txt`)

## ルールと守らせ方

| 区分 | ルールの数 | ID |

成果物を取得する​

確認した結果​

  • 通常フローを34コマンドで実行し、最終lintは17ルール・エラー0件。Evalと収束テストの明示省略による警告2件を記録した。
  • 正本のselftest.pyを作業場所内の一時ディレクトリで実行し、ユーザー単位の段階を含む20段階すべてに合格した。
  • hooks_plan.pyで依頼のall方針を決定し、phase 0の検査に合格した。隔離プロジェクトの両製品の設定への登録を確認した。
  • 違反例などのprobe 19件と、両製品のhooks接続22件に合格した。
  • 生成SKILL.md・ルール詳細・出力契約に、指摘収集の専用ルールや収集コマンドを入れていない。
  • setup.pyを含む共通runtime 7ファイル、収集schema、収集の参照文書が正本とバイト単位で一致した。
  • hooksを発火させずに差分なしの中断、チケットの正規化、2ファイルのコミットメッセージ作成、check・finishを実行し、収集記録が作られないことを確認した。
  • 合成Stopで提示版1件を保存し、合成データの印と記録の整合性を検査した。実ユーザーの指摘・承認は0件。
  • 作業場所内の仮のホームで生成スキルのinstall.py --scope userを実行し、ホームの置き場2か所のリンクと、$HOMEの置き場を指す両製品のhooks 4イベントずつを確認した。別プロジェクトには置き場・設定・実行記録を作らなかった。
  • ユーザー単位のStopのhookは、別プロジェクトのセッションで終了コード0、スクリプトを外した後も出力なし・終了コード0で終わった。--uninstallで登録とリンクを外し、隔離プロジェクトの登録は変わらなかった。
  • 実際のホームへの導入、実製品のhooks自動発火・信頼UI、実ユーザー承認、Evalの価値確認、独立AIの収束は未実施。

確認するポイント​

  • 作ったスキルの目的・入力・出力が依頼と一致しているか。
  • 違反例と hooks の動作確認、最終検査が通っているか。
  • 収束テストを実施した範囲と、省いた範囲が区別されているか。
  • 配置と hooks の登録に加え、製品側の再起動・信頼設定が済んでいるか。

スキルの本文・スクリプト・設定は、実行中も修正できます。変更を理由に開始や完了を拒否する検査はありません。出力は現在の契約で検査します。

スクリプトとひな形の動作は python3 <skill>/scripts/selftest.py で確かめられます。これは独立した AI による収束テストとは別の確認です。

正本を読む​

詳細な手順・場合分け・契約は skill-foundation の SKILL.md を参照してください。