skill-forge

Skill Forge

このスキルは、Claude Code および Codex のスキルを作成、テスト、改善、パッケージ化、保守するために使用します。

デフォルトのループは次のとおりです。

1. 意図するスキルの境界を理解します。
2. SKILL.md を起草または編集します。
3. 現実的な評価プロンプトを作成します。
4. スキルと適切なベースラインを実行します。
5. 採点、集計し、ユーザーにビューアを表示します。
6. フィードバックに基づいて改善し、繰り返します。
7. 必要に応じて、frontmatter の description を最適化し、スキルをパッケージ化します。

ユーザーがブレインストーミングのみを希望する場合は、評価をスキップし、設計パートナーとして行動します。 ユーザーがすでにドラフトを持っている場合は、検証、評価、またはイテレーションから始めます。

段階的開示のマップ

現在のブランチに必要な参照ファイルのみを読み取ります。

• references/skill_authoring.md - SKILL.md を起草、レビュー、または大規模にリファクタリングする前に読み取ります。特に、本文が 500 行に近づく可能性がある場合や、既存のスキル知識を短縮、再編成、翻訳、または参照に移動する場合に読み取ります。
• references/eval_workflow.md - テストケースの実行、ベンチマーク、採点、ビューアの生成、ブラインド比較、またはフィードバックに基づくイテレーションの前に読み取ります。
• references/description_optimization.md - スキルのトリガー description を最適化またはデバッグする前に読み取ります。対象スキルの SKILL.md を読み取り、helps with と should not help with を抽出し、ユーザーとともにトリガー評価をレビューする必要があります。
• references/openai_yaml.md - Codex の agents/openai.yaml メタデータを生成またはレビューする前に読み取ります。
• references/skill_creator_comparison.md - プラットフォームの前提を更新したり、skill-forge を Anthropic/OpenAI の作成フローと比較する前に読み取ります。
• references/trigger_eval_boundaries.md - トリガー評価のパースを変更したり、予想外の Claude Code / Codex CLI のトリガー結果を解釈する前に読み取ります。
• references/schemas.md - evals.json、eval_metadata.json、grading.json、または benchmark.json を作成または手動で検査する前に読み取ります。
• references/platform_notes.md - Claude.ai、Cowork、またはヘッドレス環境で実行する場合に読み取ります。

agents/ ディレクトリには、専門化されたサブエージェントの指示が含まれています。

• agents/grader.md - 出力に対する期待値を評価する方法。
• agents/comparator.md - ブラインド A/B 比較を行う方法。
• agents/analyzer.md - ベンチマーク結果を分析する方法。

ユーザーとのコミュニケーション

Skill Forge は、コーディングの習熟度が大きく異なる人々に使用される可能性があります。ユーザーの語彙に合わせてください。デフォルトの場合、「評価」や「ベンチマーク」といった用語は問題ありませんが、「JSON」や「期待値」には短い定義が必要になることがあります。

トレードオフを平易に説明してください。高コストな評価ループの実行、トリガー動作の変更、またはスキルのパッケージ化の前に、確認を求めてください。

スキルの作成または編集

まず、会話がすでに伝えていることを抽出します。ユーザーが「これをスキルにして」と言った場合は、さらに質問する前に、観察されたワークフロー、ツール、修正、入力、出力を再利用します。

次の点を明確にします。

1. このスキルによって、エージェントは何をできるようになるべきですか？
2. このスキルはいつトリガーされるべきですか？
3. どのような出力を生成すべきですか？
4. このスキルは Claude 専用、Codex 専用、または両方と互換性があるべきですか？
5. 今すぐ評価を追加すべきですか？

起草するときは、references/skill_authoring.md を読み取ります。少なくとも、次を生成します。

• name: 安定したスキル識別子。
• description: トリガーの境界。すべての「いつ使用するか」のガイダンスをここに記述します。
• compatibility: オプションの要件。有用な場合にのみ記述します。
• 本文の指示: 永続的なワークフローと、バンドルされたリソースへのポインタ。

description は、真陽性のために直接的で少し押しの強いものにするべきです。スキルはトリガーされにくいことがあるためです。また、スキルが通常のコーディング、ドキュメント、または運用の作業を乗っ取らないように、ニアミスに対する明示的な除外も含めます。

SKILL.md を編集した後は、それを検証し、存在する場合は Codex メタデータを再生成します。

Python 環境のセットアップ

スクリプトを実行する前に、skill-forge ディレクトリから Python 環境が準備されていることを確認してください:

uv sync --group dev

すべてのスクリプト呼び出しには uv run を使用してください。uv が見つからない場合は、ユーザーに https://docs.astral.sh/uv/ を案内してください。

スキルの検証

Codex 互換のスキルについては、agents/openai.yaml を生成またはレビューする前に references/openai_yaml.md を読んでください。

対象のスキルの SKILL.md フロントマターが安定したら、Codex UI メタデータを生成します:

uv run python -m scripts.generate_openai_yaml <skill-dir>

パッケージ化または公開の前に検証を実行してください:

uv run python -m scripts.quick_validate <skill-dir>
uv run python -m scripts.quick_validate <skill-dir> --platform claude
uv run python -m scripts.quick_validate <skill-dir> --platform codex
uv run python -m scripts.quick_validate <skill-dir> --platform codex --strict-openai-yaml

disable-model-invocation、user-invocable、when_to_use など Claude Code 専用のフロントマターには --platform claude を使用してください。Codex スキルと agents/openai.yaml には --platform codex を使用してください。Codex メタデータを公開する前に --strict-openai-yaml を使用してください。これは display_name、short_description、default_prompt を必須とし、SKILL.md の変更後に古くなったメタデータを検出します。

評価とベンチマーク

評価を実行する前に、references/eval_workflow.md を読んでください。

基本的なルール:

• 分離されたワークスペースを作成し、そのパスをユーザーに示してください。
• 各テストケースについて、スキルありの実行とベースラインの実行を同じターンで開始してください。
• 各タスクはワークスペース配下のそれぞれ専用の作業ディレクトリで実行してください。
• 各テストケースごとに eval_metadata.json を書き出してください。新規ファイルは "expectations": [] で始めます。
• 実行が進行している間に期待値を下書きしてください。
• 実行通知が届くたびにタイミングデータを保存してください。
• agents/grader.md を使って採点してください。
• scripts.aggregate_benchmark で集計してください。
• 人間によるレビュー UI は eval-viewer/generate_review.py で生成してください。独自のビューア HTML を書かないでください。
• スキルを再度改訂する前に、ユーザーのフィードバックを読んでください。

スキーマの詳細については、references/schemas.md を読んでください。書き手は expectations を出力する必要があります。古い assertions は読み手にとってのレガシーエイリアスにすぎません。

スキルの改善

雰囲気だけでなく、証拠に基づいて改善してください:

• 既存スキルの大規模なリファクタリングでは、編集前と最終検証前に references/skill_authoring.md の保全パスを実行してください。「短縮」「整理」「英語化」「references への移動」を、振る舞いを形作るスキルの知識を破棄する許可と解釈しないでください。
• 1 つの評価プロンプトに過剰適合させるのではなく、ユーザーのフィードバックから一般化してください。
• 出力が意外な場合はトランスクリプトを読んでください。
• 繰り返し無駄な作業を引き起こす指示を削除してください。
• 複数の評価が同じ決定論的なヘルパーを再発明している場合は、ヘルパースクリプトをバンドルしてください。
• 意味のある変更の後は、評価ワークフローを再実行してください。

ブラインド A/B 比較については、agents/comparator.md と agents/analyzer.md を読んでください。

説明の最適化

スキル本体が安定したら、トリガー最適化を提案してください。開始する前に references/description_optimization.md を読んでください。

最小限のワークフロー:

1. 対象スキルの SKILL.md を読んでください。
2. helps with と should not help with を抽出してください。
3. should-trigger と should-not-trigger のクエリを下書きしてください。
4. ユーザーに assets/eval_review.html でクエリセットをレビューしてもらってください。
5. 適切な CLI で scripts.run_loop を実行してください。
6. best_description を適用し、変更前後を示し、スコアを報告してください。

Claude Code の例:

uv run python -m scripts.run_loop \
  --eval-set <path-to-trigger-eval.json> \
  --skill-path <path-to-skill> \
  --model <model-id-powering-this-session> \
  --max-iterations 5 \
  --verbose

Codex CLI の例:

uv run python -m scripts.run_loop \
  --eval-set <path-to-trigger-eval.json> \
  --skill-path <path-to-skill> \
  --model <model-id-powering-this-session> \
  --cli codex \
  --max-iterations 5 \
  --verbose

最適化ループに Anthropic API クライアントの個別セットアップは不要です。status: "error" または status: "not_run" を解釈する前に、references/trigger_eval_boundaries.md を読んでください。

プラットフォーム固有の分岐

Claude.ai、Cowork、ヘッドレス環境については、ワークフローを適応させる前に references/platform_notes.md を読んでください。

短縮版:

• Claude.ai にはサブエージェントがないため、テストケースを自分で実行し、ベースラインをスキップし、定性的なレビューに集中してください。
• Cowork にはサブエージェントがありますが、ブラウザがない場合があります。eval-viewer/generate_review.py --static <output_path> で静的ビューアを生成してください。
• 説明の最適化には claude -p または codex exec が必要です。適切な CLI が利用できない場合はスキップしてください。

パッケージ化と提示

ファイル提示ツールが利用可能な場合は、最終的なスキルをパッケージ化してください:

uv run python -m scripts.package_skill <path/to/skill-folder>

そうでない場合は、生成された .skill のパスをユーザーに返してください。

最終チェックリスト

• スキルの境界が frontmatter の description で明確になっています。
• SKILL.md は簡潔に保ち、分岐ごとの詳細については参照先を示しています。
• Claude と Codex の検証パスが明示されています。
• SKILL.md の変更後に Codex のメタデータが再生成されています。
• 評価、期待値、グレーディング、ベンチマーク、ビューアの成果物は references/schemas.md のスキーマを使用しています。
• パッケージ化の前にユーザーフィードバックが反映されています。