skillforge

Skillforge — Claude Code のスキルを正しく作成・最適化する

Anthropic の公式ガイダンス全般（フロントマターのフィールド、500 行の上限、動的なコンテキスト注入、テストフレームワーク、アンチパターン、9 種類のスキル、5 種類のワークフローパターン）を確認するには、references/anthropic-skill-best-practices.md を読み込んでください。

2 つのモード

モード	用途	出力
forge（デフォルト）	まだ存在しない新しいスキル	以下のプロセスに従って作成した新しいスキルディレクトリ
optimize	動作するものの、改善が必要な既存のスキル	成果を測定可能な形で改善した、そのスキルの V2

forge は、このファイルの残りに記載されたプロセスとチェックリストに従います。

optimize <skill> は、指標に基づくループを実行します。成果と指標の定義 → ゲートの設定（不正な採点を防ぐ監査を含む） → 品質監査 → 成果を改善する手法をドメインで調査 → 変更履歴を添えて V2 を作成 → 単一の例ではなく、未使用のベンチマークで V2 が V1 を上回ることを検証し、ゲートに失敗した候補は破棄します。「最適化」であり、「整理」ではありません。成果を変えない整理は V2 ではなく、評価基準を悪用してスコアが上がったなら、それは退行です。このループだけで完結します。多数の仮説、並行実験、数時間にわたる作業など、大規模な実行では、利用可能な外部オプティマイザー（ce-optimize plugin、evo、Microsoft の SkillOpt）に任意で委ねることもできます。詳細な手順はreferences/optimize-mode.mdをご覧ください。

メタプロセス：まず反復し、その後に抽出する

Anthropic が推奨する作成フロー：Claude が成功するまで、1 つの難しいタスクで反復し、その後、うまくいったアプローチをスキルとして抽出します。 仮想的な将来のニーズに対してスキルを書かないでください。会話の中で実際の問題を解決し、うまくいくプロンプトとコンテキストの形を見つけて固定します。

プロセス

1. 要件を収集する - ユーザーに以下を尋ねます。

   • スキルの対象となるタスクやドメインは何ですか？
   • どのような具体的なユースケースに対応する必要がありますか？（最近の実例を挙げてもらいます。）
   • 実行可能なスクリプトが必要ですか、それとも手順だけでよいですか？
   • 含めるべき参考資料はありますか？
   • 副作用（デプロイ、コミット、メッセージ送信）はありますか？ → disable-model-invocation: true を設定します。
   • 通常は確認を求めるツールはありますか？ → allowed-tools: に記載します。

2. スキルを作成する - 以下を作成します。

   • 簡潔な手順を記載した SKILL.md（ローカルでは 100 行以下を目標とし、Anthropic の公開基準は 500 行です。）
   • 毎回の呼び出し時に読み込む必要のない詳細を記載した references/ ファイル
   • 決定論的な処理（並べ替え、検証、形式変換）を行う scripts/

3. ユーザーとレビューする - 作成したものを提示して、以下を尋ねます。

   • ユースケースに対応できていますか？
   • 不足している点や、わかりにくい点はありますか？
   • もっと詳しく、または簡潔にすべきセクションはありますか？

スキルの構成

skill-name/
├── SKILL.md           # Main instructions (required)
├── REFERENCE.md       # Detailed docs (if needed)
├── EXAMPLES.md        # Usage examples (if needed)
└── scripts/           # Utility scripts (if needed)
    └── helper.js

SKILL.md のテンプレート

---
name: skill-name
description: Brief description of capability. Use when [specific triggers].
---

# Skill Name

## Quick start

[Minimal working example]

## Workflows

[Step-by-step processes with checklists for complex tasks]

## Advanced features

[Link to separate files: See [REFERENCE.md](REFERENCE.md)]

説明の要件

エージェントがどのスキルを読み込むかを判断する際に見るのは、説明だけです。説明は、インストール済みの他のすべてのスキルとともにシステムプロンプトに表示されます。エージェントはこれらの説明を読み、ユーザーの依頼に基づいて関連するスキルを選びます。

目標：エージェントが以下を判断できるだけの情報を記載します。

1. このスキルが提供する機能
2. スキルを起動するタイミングと理由（具体的なキーワード、状況、ファイル形式）

形式：

• description と when_to_use の合計で最大 1,536 文字
• 三人称で記述する
• 最初の文：スキルが何をするか
• 2 文目：「Use when [具体的な起動条件]」
• アンチパターン： 説明的な要約（「このスキルは A、B、C を実行します」）では、振り分けのテストに合格しません。判断ルールを記述してください。

良い例：

Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction.

悪い例：

Helps with documents.

悪い例では、エージェントがこれを他のドキュメント系スキルと区別する方法がありません。

スクリプトを追加する場合

以下に該当するときは、ユーティリティスクリプトを追加してください。

• 処理が決定論的である（検証、書式設定）
• 同じコードを繰り返し生成することになる
• エラーを明示的に処理する必要がある

スクリプトを使うと、トークンを節約でき、生成コードと比べて信頼性が向上します。

ファイルを分割するタイミング

次の場合は、別々のファイルに分割します。

• SKILL.md が100行を超える
• コンテンツに異なる領域が含まれる（財務と営業のスキーマなど）
• 高度な機能がほとんど必要とされない

Gotchas セクション（本番用スキルでは必須）

Anthropic：「あらゆるスキルで最もシグナルの高いコンテンツです。信頼性60％と95％の差を生みます。」予測ではなく、実際に発生した失敗をもとに作成します。1行で失敗モードを示し、1行で回避策を示します。同じ失敗が繰り返されるたびに更新します。Gotchas セクションのない本番用スキルは、信頼性を高める機会を逃しています。

スキルのテスト

Anthropic によると、次の3段階があります。

1. トリガー — 必要なときに起動しますか？起動すべきでないときに起動しませんか？（トリガー条件に該当するプロンプトと該当しないプロンプトの両方をテストします。）
2. 機能 — 既知の入力に対して、期待どおりの出力を生成しますか？エッジケースに対応していますか？
3. パフォーマンス — 同じタスクを、スキルありとスキルなしで実行します。スキルありの場合に結果が向上しないなら、そのスキルは枠に見合う価値を発揮していません。

レビューチェックリスト

ドラフトの作成後、次の項目を確認します。

• 説明にトリガー（「次の場合に使用…」）が含まれ、1,536文字以下である
• SKILL.md が100行未満である（ローカルでの目標値。Anthropic の公開基準は500行）
• スキルで特定のツールが必要な場合、フロントマターで allowed-tools を宣言している
• スキルに副作用がある場合、disable-model-invocation: true を設定している
• Gotchas セクションがある（または最初の失敗を記録して TODO としてマークしている）
• 時間とともに古くなる情報がない
• 用語が統一されている
• 具体例が含まれている
• 参照が1階層以内である
• スキル名に claude または anthropic が含まれていない。フォルダー内に README.md がない

変更履歴

V2.2 (2026-05-29) — SkillOpt と train/val 分割を追加

• Microsoft SkillOpt（MIT、arxiv 2605.23904）を、ce-optimize と evo に加わる3つ目の任意の外部エスカレーション先として追加しました。SkillOpt は標準化されたベンチマーク（SearchQA、ALFWorld、DocVQA、SpreadsheetBench、OfficeQA）に対し、エポック／ミニバッチ／検証ゲートを用いた NN 方式で Markdown スキルをトレーニングします。ベンチマーク主導の厳密さには SkillOpt、セッション内のワークフローには ce-optimize、並列／木探索アーキテクチャには evo が最適です。
• 検証ステップ（#6）を train/validation 分割で強化 — 保留しておいたベンチマークを、調整用サブセット（反復により過学習する可能性がある）と検証用サブセット（変更プロセスで一度も使用しない）に分割します。調整用サブセットで改善しても検証用サブセットで劣化する場合、その変更は過学習しています。破棄してください。SkillOpt の規律を取り入れました。
• 手動で回すループを実態に即して「1エポック、バッチサイズ1」と表現しました。小規模かつ高速で、単一スキルの V2 に有用です。本格的なトレーニングを行う場合は、外部にエスカレーションしてください。

V2.1 (2026-05-28) — ce-optimize の規律を統合

ce-optimize（CE plugin）と evo（alokbishoyi97、evo-hq.com）のメトリクス主導の厳密さを統合し、optimize モードを進化させました。

• ゲートのステップ（縮退ゲート＋不正行為監査＋保留データチェック）を追加しました。最も高いスコアを獲得した場合でも、ゲートを通過できない候補は破棄します。以前のループにあった「メトリクスを不正に操作する」余地をなくします。
• 検証では単発のタスクではなく、**保留ベンチマーク（約10～20タスク）**を使用するようにしました。これにより、council-review の A/B テストにあった N=1 の弱点を解消します。
• 任意の外部エスカレーションを追加しました。大規模な実行（多数の仮説／並列実験／数時間かかる場合）では、外部オプティマイザー（インストール済みの場合は ce-optimize plugin または evo-hq.com の evo）に任意で引き継げます。skillforge は自己完結型のままであり、独自の成果調査＋スキル品質監査のフロントエンドを維持します。

V2 (2026-05-27)

• optimize モードを追加しました（新規作成と既存スキルの V2 への最適化を選択）。Optimize はメトリクス主導のループを実行します。成果とメトリクスの定義、品質監査、ドメインの成果調査、V2 と変更履歴の統合、V2 が V1 を上回ることの検証を行います。これにより、「V2」はパッケージングだけでなく、成果を測定可能な形で改善する必要があります。プレイブック：references/optimize-mode.md。
• 7つのスキルでドッグフーディングを実施しました（council-review のパイロットと、6スキルの一括実施）。これにより skillforge は in-progress/ から昇格しました。