creating-skills

スキルクリエーター

新しいスキルを作成し、反復的に改善するためのスキルです。

基本原則：スキルの作成は、プロセス文書に適用するテスト駆動開発です。 RED-GREEN-REFACTOR に従います。スキルなしでベースラインテストを実行し（RED — エージェントが失敗するのを確認）、その失敗に対処するスキルを書き（GREEN — エージェントが指示に従うのを確認）、抜け穴を塞ぎます（REFACTOR — 準拠を維持）。スキルなしでエージェントが失敗するのを確認していなければ、そのスキルが正しいことを教えているかどうかはわかりません。

大まかに言うと、スキルを作成するプロセスは次のとおりです。

• スキルに何をさせたいか、またおおよそどのように実現するかを決めます
• スキルの初稿を書きます
• テスト用プロンプトをいくつか作成し、そのスキルを利用できる状態でエージェントに実行させます
• 定性的、定量的な両面から、ユーザーが結果を評価できるよう支援します
  • 実行がバックグラウンドで進む間に、定量的な評価がまだなければいくつか作成します（すでにある場合は、そのまま使うか、変更が必要だと思う部分を修正します）。その後、ユーザーに説明します（すでに評価がある場合は、既存の評価について説明します）
  • eval-viewer/generate_review.py スクリプトを使って評価結果を表示し、ユーザーが確認できるようにします。また、定量的な指標も確認できるようにします
• ユーザーによる結果評価からのフィードバックに基づいてスキルを書き直します（また、定量的なベンチマークで明らかな欠陥が見つかった場合も修正します）
• 満足できるまで繰り返します
• テストセットを拡張し、より大規模に再度試します

このスキルを使う際の役割は、ユーザーがこのプロセスのどの段階にいるかを見極め、各段階を進められるよう支援することです。たとえば、「X のスキルを作りたい」と言われたら、意図を明確にし、初稿を書き、テストケースを作成し、評価方法を検討し、すべてのプロンプトを実行して、反復を続けるところまで支援できます。

一方、すでにスキルの初稿がある場合は、評価と反復の段階から始められます。

もちろん、ユーザーが「評価をたくさん実行する必要はないので、気軽に相談に乗って」と言うような場合は、柔軟に対応してそのように進めてください。

スキルが完成したら（もちろん、順序は柔軟です）、別の専用スクリプトが用意されているスキルの説明文改善ツールを実行して、スキルが適切に呼び出されるよう最適化することもできます。

いいですか？　では始めましょう。

スキルとは

スキルとは、実証済みの手法、パターン、ツールをまとめたリファレンスガイドです。スキルがあると、将来のエージェントインスタンスが効果的なアプローチを見つけ、適用できるようになります。

スキルに適したもの： 再利用可能な手法、パターン、ツール、リファレンスガイド
スキルに適さないもの： 一度だけ問題を解決したときの経緯

スキルの種類

• 手法： 実行する手順が具体的に示された方法（例：条件に基づく待機、根本原因の追跡）
• パターン： 問題に対する考え方（例：フラグを使った平坦化、不変条件のテスト）
• リファレンス： API ドキュメント、構文ガイド、ツールのドキュメント（例：オフィス文書）

スキルを作成するタイミング

作成する場合：

• 手法が直感的にはわかりにくかった
• 複数のプロジェクトでまた参照する
• パターンが幅広く適用でき、特定のプロジェクトに限定されない
• ほかの人にも役立つ

作成しない場合：

• 一度限りの解決策
• ほかの場所で十分に文書化されている一般的な慣行
• プロジェクト固有の規約（AGENTS.md に記載します）
• 正規表現や検証で強制できる機械的な制約

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

スキル作成者は、コーディング用語への習熟度がさまざまな人々に利用されることを念頭に置く必要があります。聞いたことがない方もいるでしょう（始まったのはごく最近なので、当然かもしれません）。現在、エージェントの能力に刺激されて、配管工がターミナルを開いたり、親や祖父母が「npm のインストール方法」を Google で検索したりする傾向が見られます。一方で、ユーザーの大半はコンピューターの操作にかなり慣れているでしょう。

ですから、文脈の手がかりに注意し、どのように伝えるかを判断してください。標準的なケースでは、目安として次のように考えてください。

• 「評価」と「ベンチマーク」は判断が分かれるところですが、使用しても問題ありません。
• 「JSON」や「アサーション」を説明なしで使う場合は、ユーザーがそれらを知っているとわかる明確な手がかりが必要です。

迷った場合は用語を簡単に説明してかまいませんし、ユーザーが理解できるか不安であれば、短い定義を添えてください。

---

スキルの作成

意図を把握する

まず、ユーザーの意図を理解してください。現在の会話に、ユーザーがスキルとしてまとめたいワークフロー（たとえば「これをスキルにして」）がすでに含まれている場合があります。その場合は、まず会話履歴から、使用したツール、手順、ユーザーが行った修正、確認できた入出力形式を抽出してください。不足部分はユーザーに補ってもらい、次のステップに進む前に確認を取ってください。

1. このスキルで、エージェントに何ができるようになればよいですか？
2. どのようなときにこのスキルを起動すべきですか？（どのようなユーザーの表現や状況がきっかけになりますか？）
3. 期待される出力形式は何ですか？
4. スキルが正しく動作することを確認するためのテストケースを用意しますか？ファイル変換、データ抽出、コード生成、固定された手順など、出力を客観的に検証できるスキルにはテストケースが有効です。文章のスタイルやアートなど、主観的な出力のスキルには通常必要ありません。スキルの種類に応じた適切な既定案を提案しつつ、最終的にはユーザーに選んでもらってください。

ヒアリングと調査

エッジケース、入出力形式、サンプルファイル、成功基準、依存関係について、積極的に質問してください。この点が固まるまでは、テスト用のプロンプトを書き始めないでください。

利用可能な MCP を確認してください。調査（ドキュメントの検索、類似スキルの調査、ベストプラクティスの確認）に役立つ場合は、サブエージェントが利用できるなら並行して調査し、利用できない場合はその場で調べてください。ユーザーの負担を減らせるよう、必要な背景情報を用意しておきましょう。

SKILL.md を作成する

ユーザーへのヒアリングに基づいて、次の項目を記入してください。

• name：スキルの識別子です。使用できるのは英字、数字、ハイフンのみです。プロセスを表す場合は、動名詞形（動詞 + -ing）を優先してください。例：creating-skills、testing-skills。一般的な用語ではなく、実行することや中核となる知見に基づいて名前を付けてください。
• description：スキルを起動する条件です。これは起動判定の主要な手がかりになります。重要：description に記載するのは、スキルを使うタイミングであり、スキルが何をするかではありません。「Use when...」で始め、具体的な症状、状況、文脈を含めてください。三人称で記述してください。スキルの手順やワークフローを要約してはいけません。 description に手順を要約すると、エージェントがスキルの内容を読む代わりに description に従ってしまう可能性があります。500 文字以内にしてください。「いつ使うか」に関する情報はすべてここに記載してください。注：現在のエージェントはスキルを「過小に起動」する傾向があり、役立つ場面でも使わないことがあります。これを防ぐため、スキルの description は少し積極的にしてください。
  • 具体的な起動条件を含めてください：エラーメッセージ、症状、ツール名、ファイル形式など
  • 類義語を使ってください：「timeout/hang/freeze」「cleanup/teardown/afterEach」など
  • 言語固有の症状ではなく、問題を説明してください
  • ユーザーがスキル名を明示していなくても、関連するキーワードが出てきたら必ずこのスキルを使うようにしてください
• compatibility：必要なツールや依存関係（任意。必要になることはまれです）
• その他のスキルの内容 :)

スキル作成ガイド

スキルの構成

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter (name, description required)
│   └── Markdown instructions
└── Bundled Resources (optional)
    ├── scripts/    - Executable code for deterministic/repetitive tasks
    ├── references/ - Docs loaded into context as needed
    └── assets/     - Files used in output (templates, icons, fonts)

段階的な開示

スキルでは、3 段階の読み込みシステムを使用します。

1. メタデータ（名前＋説明）- 常にコンテキスト内にあります（約 100 語）
2. SKILL.md の本文 - スキルが起動するたびにコンテキスト内に読み込まれます（500 行未満が理想）
3. 同梱リソース - 必要に応じて読み込まれます（上限なし。スクリプトは読み込まずに実行できます）

これらの語数は目安です。必要であれば、自由に増やしてください。

重要なパターン：

• SKILL.md は 500 行未満に保ってください。この上限に近づいている場合は、階層をさらに追加し、スキルを使用するエージェントが次に参照すべき場所を明確に示してください。
• SKILL.md から参照ファイルへのリンクを明確に記載し、どのような場合に読むべきかを説明してください。
• 300 行を超える大きな参照ファイルには、目次を含めてください。

ドメインの整理：スキルが複数のドメインやフレームワークに対応する場合は、バリエーションごとに整理します。

cloud-deploy/
├── SKILL.md (workflow + selection)
└── references/
    ├── aws.md
    ├── gcp.md
    └── azure.md

エージェントは、関連する参照ファイルだけを読み込みます。

意外性を避ける原則

言うまでもありませんが、スキルにはマルウェア、エクスプロイトコード、システムのセキュリティを損なう可能性のあるコンテンツを含めてはいけません。内容を説明したときに、スキルの意図がユーザーにとって意外なものにならないようにしてください。誤解を招くスキルや、不正アクセス、データの持ち出し、その他の悪意ある活動を助長するスキルの作成依頼には応じないでください。ただし、「XYZ の役になりきる」といったものは問題ありません。

記述パターン

指示では命令形を優先してください。

段階的なファイルの作成（重要）： モデルは大きなファイルを一度に出力できません。各編集で出力できるのは約 1000 トークンまでです。これを超えると API エラー 500 が発生します。大きなファイルは必ず段階的に作成するよう、エージェントに指示してください。

1. まず骨組み（インポート、シグネチャ、セクションコメント）を書く
2. 編集呼び出しごとに 1 セクションずつ埋める（チャンクあたり約 1000 トークン）
3. 最後にレビューしてコミットする

大きな出力（ドキュメント、コードファイル、設定ファイルなど）を生成するスキルには、このパターンを含めてください。記載する指示の例：

## Writing Large Files

This document may be large. Write it incrementally to avoid API errors:

1. **First pass:** Write the header, structure, and section outlines
2. **Subsequent passes:** Edit to fill in each section one at a time (~1000 tokens per edit)
3. **Final pass:** Review the complete document, fix issues, save

出力形式の定義 - 次のように記述できます。

## Report structure
ALWAYS use this exact template:
# [Title]
## Executive summary
## Key findings
## Recommendations

例のパターン - 例を含めると役立ちます。次のように形式を整えられます（ただし、例に「Input」と「Output」が含まれている場合は、少し変えるとよいでしょう）。

## Commit message format
**Example 1:**
Input: Added user authentication with JWT tokens
Output: feat(auth): implement JWT-based authentication

文体

強い MUST の指示を多用する代わりに、物事が重要である理由をモデルに説明するようにしてください。心の理論を活用し、スキルが特定の例に限定されすぎず、汎用的になるようにしてください。まず草案を書き、新鮮な目で見直して改善してください。

トークン効率（重要）

コンテキストウィンドウは共有リソースです。SKILL.md のトークンはすべて、会話履歴やその他のコンテキストと取り合いになります。

目標の語数：

• 頻繁に読み込まれるスキル：合計 200 語未満
• その他のスキル：500 語未満（簡潔さを保ってください）

テクニック：

• エージェントはすでに非常に賢いと想定してください。 エージェントがすでに知っていること以外を追加してください。各項目について、「エージェントにこの説明が本当に必要か」と問い直してください。
• 詳細はツールのヘルプに移す： すべてのフラグを文書化する代わりに、--help を参照してください。
• 相互参照を活用する： ワークフローを繰り返すのではなく、他のスキルを名前で参照してください。**REQUIRED SUB-SKILL:** Use skill-name または **REQUIRED BACKGROUND:** You MUST understand skill-name を使用してください。@ 構文はファイルを即座に強制読み込みし、コンテキストを消費するため、使用しないでください。
• 例を絞る： 優れた例を 1 つ示すほうが、平凡な例を多数示すより効果的です。5 つ以上の言語で実装しないでください。穴埋め式のテンプレートは作成しないでください。
• 重複をなくす： 相互参照しているスキルの内容を繰り返さないでください。コマンドから明らかなことは説明しないでください。同じパターンの例を複数含めないでください。
• 時間の経過で古くなる情報を避ける： 古くなる日付は記載しないでください。非推奨の方法には「古いパターン」のセクションを使用してください。
• 用語を統一する： 用語を 1 つ選び、全体を通して使用してください。

コード例

質の高い例が、平凡な例をいくつも並べるより優れています。 タスクに最も適した言語を選んでください（テスト手法なら TypeScript/JS、システムのデバッグなら Shell/Python、データ処理なら Python）。優れた例は、完全で実行可能であり、WHY を説明するコメントが付いていて、実際の状況に基づき、すぐに応用できます。

フローチャートの使用

フローチャート（graphviz DOT 形式）は、直感的には分かりにくい判断点、エージェントが早々に停止してしまう可能性があるプロセスのループ、「A と B のどちらを使うか」という判断に限って使用してください。参考資料、コード例、直線的な手順、意味を持たないラベルには、フローチャートを使わないでください。

graphviz のスタイル規則については、references/graphviz-conventions.dot を参照してください。人間のパートナー向けにフローチャートを SVG にレンダリングするには、render-graphs.js を使ってください。

./render-graphs.js ../some-skill           # Each diagram separately
./render-graphs.js ../some-skill --combine # All diagrams in one SVG

アンチパターン

• 物語形式の例（「セッション 2025-10-03 で、私たちは……を見つけました」） — 具体的すぎて、再利用できません
• 複数言語による質の低下（example-js.js、example-py.py、example-go.go） — 品質が平凡になり、保守の負担が増えます
• フローチャート内のコード — コピー＆ペーストできず、読みづらくなります
• 汎用的なラベル（helper1、step3、pattern4） — ラベルには意味を持たせてください
• 選択肢が多すぎること — 必要でない限り、複数のアプローチを提示しないでください。デフォルトの方法を示し、必要に応じて別の方法を選べるようにします
• 深くネストした参照 — ファイルへの参照は SKILL.md から1段階以内にしてください。エージェントは、参照先のファイルからさらに参照されているファイルを一部しか読まない可能性があります
• Windows 形式のパス — 常にスラッシュを使ってください

鉄則

NO SKILL WITHOUT A FAILING TEST FIRST

これは、新しいスキルにも既存スキルの編集にも適用されます。スキルを書く前に、スキルを使わずにベースラインシナリオを実行してください。エージェントが失敗する様子を観察し、実際に述べた合理化を正確に記録します。そのうえで、具体的な失敗に対処するスキルを書いてください。

例外はありません。

• 「簡単な追加」の場合も
• 「セクションを追加するだけ」の場合も
• 「ドキュメントの更新」の場合も

テストケース

スキルの草案を書いたら、現実的なテスト用プロンプトを2～3個考えてください。実際のユーザーが使いそうなものにします。次のように、ユーザーに共有してください（この表現をそのまま使う必要はありません）。「試してみたいテストケースをいくつか用意しました。これでよさそうですか？ 追加したいものはありますか？」その後、テストケースを実行します。

テストケースは evals/evals.json に保存してください。まだアサーションは書かず、プロンプトだけを記述します。実行中に、次のステップでアサーションを作成します。

{
  "skill_name": "example-skill",
  "evals": [
    {
      "id": 1,
      "prompt": "User's task prompt",
      "expected_output": "Description of expected result",
      "files": []
    }
  ]
}

assertions フィールドなどを含む完全なスキーマについては、references/schemas.md を参照してください。このフィールドは後で追加します。

すべてのスキルタイプのテスト

特に規律を徹底するスキルについては、testing-skills スキルで RED-GREEN-REFACTOR の一連の取り組みを網羅しています。具体的には、プレッシャーシナリオの作成、合理化の逐語的な記録、抜け道を塞ぐための4つの方法、そしてスキルを読んだにもかかわらず違反する場合のメタテストです。

スキルのタイプごとに、適したテスト方法は異なります。

規律を徹底するスキル（TDD や完了前の検証など、ルールや要件を扱うもの）：

• 時間、サンクコスト、権威、疲労など、3つ以上のプレッシャーを組み合わせたシナリオでテストします
• 自由回答ではなく、A/B/C の選択肢を明示的に選ばせます
• 合理化を特定し、明確な反論を追加します
• 成功基準：最大のプレッシャー下でも、エージェントがルールに従うこと

手法のスキル（手順を説明するガイド）：

• 適用シナリオとエッジケースでテストします
• 情報の不足や手順の不備をテストします
• 成功基準：エージェントが新しいシナリオに手法を適用できること

パターンのスキル（メンタルモデル）：

• 認識をテストします。エージェントは、パターンを適用すべき状況を理解していますか？
• 反例をテストします。エージェントは、適用すべきでない状況を理解していますか？
• 成功基準：エージェントがパターンを適用する状況と方法を正しく特定できること

リファレンススキル（ドキュメントや API）：

• 情報の検索をテストします。エージェントは適切な情報を見つけられますか？
• 適用をテストします。エージェントは見つけた情報を正しく使えますか？
• ギャップをテストします。よくあるユースケースが網羅されていますか？
• 成功基準：エージェントがリファレンス情報を見つけ、正しく適用できること

合理化による抜け道を防ぐ

規律を徹底させるスキルでは、プレッシャーがかかるとエージェントは抜け道を探します。あらゆる抜け道を明示的に塞いでください。

1. 明示的な否定： ルールを述べるだけでなく、具体的な回避策を禁止します。
2. 合理化の表： テスト中にエージェントが持ち出す言い訳をすべて記録します。
3. 危険信号のリスト： 合理化していないか、エージェントが簡単に自己確認できるようにします。
4. 基本原則： 「ルールの文言に違反することは、ルールの精神に違反することです」を加え、「精神か文言か」という議論を封じます。

権威、一貫性、希少性の原則がコンプライアンスを高める仕組みについては、調査結果を references/persuasion-principles.md で確認してください。

テストケースの実行と評価

Python スクリプトを実行する前に、必ず opencode 仮想環境を有効にしてください。

source ~/.local/opencode-venv/bin/activate

このセクションは一連の手順です。途中で止めないでください。

結果は、スキルディレクトリと同じ階層にある <skill-name>-workspace/ に保存します。ワークスペース内では、イテレーションごとに結果を整理し（iteration-1/、iteration-2/ など）、その中に各テストケースのディレクトリ（eval-0/、eval-1/ など）を作成します。これらを最初にすべて作成するのではなく、必要に応じて順次作成してください。

ステップ 1：すべての実行を同じターンで開始する（スキルありとベースライン）

各テストケースについて、同じターンでサブエージェントを 2 つ起動します。1 つはスキルあり、もう 1 つはスキルなしです。これは重要です。スキルありの実行を先に開始して、後からベースラインに取りかかってはいけません。すべてを一度に開始し、ほぼ同時に完了するようにしてください。

スキルありの実行：

Execute this task:
- Skill path: <path-to-skill>
- Task: <eval prompt>
- Input files: <eval files if any, or "none">
- Save outputs to: <workspace>/iteration-<N>/eval-<ID>/with_skill/outputs/
- Outputs to save: <what the user cares about — e.g., "the .docx file", "the final CSV">

ベースラインの実行（プロンプトは同じですが、ベースラインは状況によって異なります）：

• 新しいスキルを作成する場合：スキルは一切使用しません。同じプロンプトを使用し、スキルパスを指定せず、without_skill/outputs/ に保存します。
• 既存のスキルを改善する場合：古いバージョンを使用します。編集前にスキルのスナップショットを作成し（cp -r <skill-path> <workspace>/skill-snapshot/）、そのスナップショットをベースラインのサブエージェントに指定します。old_skill/outputs/ に保存します。

各テストケースに eval_metadata.json を作成します（アサーションは今のところ空で構いません）。各評価には、単なる「eval-0」ではなく、テスト内容に基づく説明的な名前を付けてください。その名前をディレクトリ名にも使用します。このイテレーションで新規または変更済みの評価プロンプトを使う場合は、新しい各評価ディレクトリにこれらのファイルを作成してください。前のイテレーションから引き継がれると思い込んではいけません。

{
  "eval_id": 0,
  "eval_name": "descriptive-name-here",
  "prompt": "The user's task prompt",
  "assertions": []
}

ステップ 2：実行中にアサーションを作成する

実行が終わるのを待つだけではなく、この時間を有効に活用できます。各テストケースの定量的なアサーションを作成し、その内容をユーザーに説明してください。アサーションがすでに evals/evals.json にある場合は、内容を確認し、何をチェックするのか説明してください。

適切なアサーションは客観的に検証でき、説明的な名前が付いています。ベンチマークビューアーで明確に表示され、結果をざっと見た人が、それぞれ何をチェックしているかすぐに理解できるものにしてください。文章のスタイルやデザインの品質など、主観的なスキルは定性的な評価に適しています。人間の判断が必要なものに、無理にアサーションを設定しないでください。

作成したら、eval_metadata.json ファイルと evals/evals.json をアサーションで更新してください。また、定性的な出力と定量的なベンチマークの両方について、ビューアーで何を確認できるかをユーザーに説明してください。

ステップ 3：実行が完了したら、所要時間データを記録する

各サブエージェントのタスクが完了すると、total_tokens と duration_ms を含む通知が届きます。このデータをすぐに、実行ディレクトリ内の timing.json に保存してください。

{
  "total_tokens": 84852,
  "duration_ms": 23332,
  "total_duration_seconds": 23.3
}

このデータを記録できる機会は、このときだけです。タスクの通知を通じて届き、ほかの場所には保存されません。まとめて処理しようとせず、通知が届くたびに処理してください。

ステップ 4：採点、集計、ビューアの起動

すべての実行が完了したら、次の手順に進みます。

1. 各実行を採点する — task ツールを使って grader グローバルエージェントを起動する（またはインラインで採点する）と、各アサーションを出力に照らして評価できます。結果は各実行ディレクトリの grading.json に保存します。grading.json の expectations 配列では、フィールドに text、passed、evidence を使用してください（name／met／details やその他の形式は使用しないでください）。ビューアはこれらのフィールド名を正確に参照します。プログラムで確認できるアサーションについては、目視で判断するのではなく、スクリプトを作成して実行してください。スクリプトを使うと、より高速で信頼性が高く、反復作業でも再利用できます。

2. ベンチマークに集計する — skill-creator ディレクトリから集計スクリプトを実行します。

   python -m scripts.aggregate_benchmark <workspace>/iteration-N --skill-name <name>
   

   これにより、各設定の pass_rate、time、tokens を含む benchmark.json と benchmark.md が生成され、平均 ± 標準偏差と差分も表示されます。benchmark.json を手動で生成する場合は、ビューアが期待する正確なスキーマについて references/schemas.md を参照してください。 各 with_skill バージョンを、対応するベースラインより前に配置してください。

   3. アナリストによる確認を行う — analyzer グローバルエージェントを使ってベンチマークデータを読み込み、集計統計では隠れてしまう傾向を明らかにします。スキルの有無にかかわらず常に合格するアサーション（識別力がないもの）、分散の大きい評価（不安定な可能性があるもの）、時間とトークンのトレードオフなどを確認してください。

3. ビューアを起動する — 定性的な出力と定量データの両方を渡します。

   nohup python <skill-creator-path>/eval-viewer/generate_review.py \
     <workspace>/iteration-N \
     --skill-name "my-skill" \
     --benchmark <workspace>/iteration-N/benchmark.json \
     > /dev/null 2>&1 &
   VIEWER_PID=$!
   

   反復 2 以降では、--previous-workspace <workspace>/iteration-<N-1> も渡してください。

   Cowork／ヘッドレス環境： webbrowser.open() が利用できない場合や、環境にディスプレイがない場合は、サーバーを起動する代わりに --static <output_path> を使ってスタンドアロンの HTML ファイルを作成してください。ユーザーが「Submit All Reviews」をクリックすると、フィードバックが feedback.json としてダウンロードされます。ダウンロード後、次の反復で取得できるように feedback.json をワークスペースディレクトリにコピーしてください。

注：ビューアの作成には generate_review.py を使用してください。独自の HTML を作成する必要はありません。

5. ユーザーに伝える — 次のように伝えます。「結果をブラウザーで開きました。タブは 2 つあります。『Outputs』では各テストケースを切り替えてフィードバックを残せます。『Benchmark』には定量的な比較が表示されます。作業が終わったら、こちらに戻ってお知らせください。」

ユーザーがビューアで確認する内容

「Outputs」タブには、一度に 1 つのテストケースが表示されます。

• プロンプト：与えられたタスク
• 出力：スキルが生成したファイル。可能な場合はインラインで表示されます
• 前回の出力（反復 2 以降）：前回の反復の出力を表示する折りたたみセクション
• 正式な採点結果（採点を実施した場合）：アサーションの合否を表示する折りたたみセクション
• フィードバック：入力中に自動保存されるテキストボックス
• 前回のフィードバック（反復 2 以降）：前回のコメントをテキストボックスの下に表示

「Benchmark」タブには統計の概要が表示されます。各設定の合格率、所要時間、トークン使用量に加え、評価ごとの内訳とアナリストの所見が含まれます。

前へ／次へボタンまたは矢印キーで移動できます。完了したら「Submit All Reviews」をクリックすると、すべてのフィードバックが feedback.json に保存されます。

ステップ 5：フィードバックを読む

ユーザーから完了したと連絡があったら、feedback.json を読み込みます。

{
  "reviews": [
    {"run_id": "eval-0-with_skill", "feedback": "the chart is missing axis labels", "timestamp": "..."},
    {"run_id": "eval-1-with_skill", "feedback": "", "timestamp": "..."},
    {"run_id": "eval-2-with_skill", "feedback": "perfect, love this", "timestamp": "..."}
  ],
  "status": "complete"
}

フィードバックが空の場合、ユーザーは問題ないと考えています。ユーザーから具体的な不満があったテストケースを中心に改善してください。

作業が終わったら、ビューアサーバーを停止します。

kill $VIEWER_PID 2>/dev/null

---

停止：次のスキルに進む前に

スキルを作成したら、必ず停止してテストとデプロイのプロセスを完了してください。

次のことはしないでください。

• テストせずに複数のスキルをまとめて作成する
• 現在のスキルの検証が済む前に次のスキルへ進む
• 「まとめて処理したほうが効率的」という理由でテストを省略する

テストされていないスキルのデプロイは、テストされていないコードのデプロイと同じです。

スキルの改善

ここが反復の要です。テストケースを実行し、ユーザーが結果を確認しました。次は、そのフィードバックに基づいてスキルを改善します。

改善の考え方

1. フィードバックから一般化する。 ここで起きていることの全体像は、多種多様なプロンプトに対して何百万回も使えるスキル（文字どおりかもしれませんし、もっと多いかもしれません）を作ろうとしている、ということです。ここでは、作業を速く進めるために、あなたとユーザーが何度も少数の例だけを使って反復しています。ユーザーはこれらの例を隅々まで把握しており、新しい出力をすばやく評価できます。しかし、あなたとユーザーが共同開発しているスキルがそれらの例でしか機能しないなら、役に立ちません。細かく過剰適合する変更や、過度に制約の厳しい「必ず〜する」という指示を加えるのではなく、なかなか解決しない問題があるなら、別の比喩を使ったり、異なる作業パターンを提案したりしてみてもよいでしょう。試すコストは比較的低く、素晴らしい方法が見つかるかもしれません。

2. プロンプトを簡潔に保つ。 役に立っていないものは削除してください。最終出力だけでなく、トランスクリプトも必ず読みましょう。スキルによってモデルが非生産的な作業に多くの時間を費やしているようなら、その動作を引き起こしているスキルの部分を取り除き、どうなるか試してみてください。

3. 理由を説明する。 モデルに求めていることの理由を、できる限り説明してください。今日のLLMは賢く、他者の意図をよく理解します。適切な枠組みを与えれば、定型的な指示に従うだけでなく、本当に物事を実現できます。ユーザーからのフィードバックがそっけなかったり、いら立ちを帯びていたりしても、タスクと、ユーザーがなぜそのように書いたのか、そして実際に何を書いたのかをしっかり理解し、その理解を指示に反映してください。大文字で「必ず」や「絶対に」と書いたり、極端に硬直した構造を使ったりしているなら、それは注意信号です。可能であれば、理由を言い換えて説明し、求めていることが重要な理由をモデルが理解できるようにしてください。そのほうが、より人間的で、強力で、効果的なアプローチです。

4. テストケース間で繰り返される作業を探す。 テスト実行のトランスクリプトを読み、サブエージェントがそれぞれ独立して似たようなヘルパースクリプトを書いていたり、同じ複数手順のアプローチを取っていたりしないか確認してください。3つのテストケースすべてで、サブエージェントがcreate_docx.pyやbuild_chart.pyを書いていたなら、それはスキルにそのスクリプトを含めるべきだという強い兆候です。一度書いてscripts/に置き、それを使うようスキルに指示してください。これにより、今後の実行で毎回同じものを作り直す必要がなくなります。

このタスクは非常に重要です（ここでは年間数十億の経済的価値を生み出そうとしています！）。考える時間がボトルネックではありません。時間をかけて、よく考えてください。改訂版の草稿を書き、それを改めて読み直して改善することをおすすめします。ユーザーの立場になって、何を望み、何を必要としているのかを理解するために、ぜひ最善を尽くしてください。

反復のループ

スキルを改善した後は、次の手順を行います。

1. スキルに改善を適用する
2. ベースライン実行を含むすべてのテストケースを、新しいiteration-<N+1>/ディレクトリで再実行します。新しいスキルを作成する場合、ベースラインは常にwithout_skill（スキルなし）です。これは反復を通じて変わりません。既存のスキルを改善する場合は、ユーザーが最初に提供した元のバージョンと前回の反復のどちらをベースラインにするか、状況に応じて判断してください。
3. --previous-workspaceに前回の反復を指定してレビュアーを起動する
4. ユーザーがレビューして完了したと伝えるまで待つ
5. 新しいフィードバックを読み、再度改善して繰り返す

次のいずれかに該当するまで続けます。

• ユーザーが満足したと伝える
• フィードバックがすべて空である（すべて問題ない）
• 意味のある進展が見られなくなった

上級編：ブラインド比較

2 つのスキルのバージョンをより厳密に比較したい場合（たとえば、ユーザーが「新しいバージョンのほうが本当に優れているのか」と尋ねた場合）は、グローバルエージェントの comparator と analyzer を使用します。基本的な流れは、どちらがどちらかを知らせずに 2 つの出力を comparator エージェントに渡し、品質を判定させます。その後、analyzer エージェントを使って、勝者が選ばれた理由を分析します。

これは任意の手順で、サブエージェントが必要です。ほとんどのユーザーには不要です。通常は、人間によるレビューのループで十分です。

---

説明の最適化

SKILL.md のフロントマターにある description フィールドは、エージェントがスキルを呼び出すかどうかを決める主要な仕組みです。スキルを作成または改善した後、呼び出しの精度を高めるために説明の最適化を提案してください。

ステップ 1：トリガー評価用クエリの生成

呼び出すべきものと呼び出すべきでないものを組み合わせて、評価用クエリを 20 個作成します。JSON として保存します。

[
  {"query": "the user prompt", "should_trigger": true},
  {"query": "another prompt", "should_trigger": false}
]

クエリは現実的で、opencode ユーザーが実際に入力しそうな内容にしてください。抽象的な依頼ではなく、具体的で詳細な依頼にします。たとえば、ファイルパス、ユーザーの仕事や状況に関する個人的な背景、列名と値、会社名、URL などを含めます。ちょっとした経緯も加えます。小文字だけのもの、省略形や誤字を含むもの、くだけた表現のものも含めてください。長さに幅を持たせ、明確に判断できる例よりも境界事例を重視します（ユーザーが内容を確認して承認できます）。

悪い例："Format this data"、"Extract text from PDF"、"Create a chart"

良い例："ok so my boss just sent me this xlsx file (its in my downloads, called something like 'Q4 sales final FINAL v2.xlsx') and she wants me to add a column that shows the profit margin as a percentage. The revenue is in column C and costs are in column D i think"

呼び出すべきクエリ（8～10 個）では、カバレッジを意識します。同じ意図を異なる表現で示すクエリを用意し、フォーマルなものとくだけたものを混ぜます。ユーザーがスキル名やファイル形式を明示していなくても、明らかにそのスキルを必要としているケースも含めてください。あまり一般的でないユースケースや、別のスキルと競合するものの、このスキルが選ばれるべきケースも加えます。

呼び出すべきでないクエリ（8～10 個）では、ニアミスが最も重要です。スキルとキーワードや概念が共通していても、実際には別のものが必要となるクエリを考えます。隣接する分野、単純なキーワード一致では呼び出されてしまいそうな曖昧な表現、スキルで扱う内容に触れていても別のツールのほうが適している状況などを想定します。

避けるべきなのは、呼び出すべきでないクエリが明らかに無関係なものになることです。PDF スキルの否定テストに「フィボナッチ関数を書いて」とするのは簡単すぎて、何のテストにもなりません。否定ケースには、本当に判断が難しいものを含めてください。

ステップ 2：ユーザーとレビューする

HTML テンプレートを使って、評価セットをユーザーに提示します。

1. assets/eval_review.html からテンプレートを読み込みます
2. プレースホルダーを置き換えます。
   • __EVAL_DATA_PLACEHOLDER__ → 評価項目の JSON 配列（JS 変数への代入なので、前後に引用符は付けません）
   • __SKILL_NAME_PLACEHOLDER__ → スキル名
   • __SKILL_DESCRIPTION_PLACEHOLDER__ → 現在のスキルの説明
3. 一時ファイル（例：/tmp/eval_review_<skill-name>.html）に書き込み、open /tmp/eval_review_<skill-name>.html で開きます
4. ユーザーはクエリを編集し、「呼び出すべき」の切り替えや項目の追加・削除を行ってから、「Export Eval Set」をクリックできます
5. ファイルは ~/Downloads/eval_set.json にダウンロードされます。複数ある場合（例：eval_set (1).json）に備えて、ダウンロードフォルダーで最新のファイルを確認します

この手順は重要です。評価用クエリの質が悪いと、説明の質も悪くなります。

ステップ 3：最適化ループを実行する

ユーザーに次のように伝えます。「これには少し時間がかかります。バックグラウンドで最適化ループを実行し、定期的に状況を確認します。」

評価セットをワークスペースに保存してから、バックグラウンドで実行します。

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

現在のセッションを動かしているシステムプロンプトのモデル ID を使い、トリガーテストがユーザーの実際の体験と一致するようにします。

実行中は定期的に出力の末尾を確認し、何回目の反復か、スコアがどのような状況かをユーザーに伝えます。

これにより、最適化ループ全体が自動的に実行されます。評価セットをトレーニング用 60％、保留テスト用 40％に分割し、現在の説明を評価します（各クエリを 3 回実行して、信頼できるトリガー率を取得します）。次に、失敗したケースに基づいて改善案を提示するようエージェントに依頼します。新しい説明をトレーニング用とテスト用の両方で再評価し、最大 5 回反復します。完了すると、反復ごとの結果を示す HTML レポートをブラウザーで開き、過学習を避けるためトレーニングスコアではなくテストスコアに基づいて選ばれた best_description を含む JSON を返します。

スキルのトリガーの仕組み

トリガーの仕組みを理解すると、より良い評価クエリを設計できます。スキルは、名前と説明とともにエージェントの available_skills リストに表示され、エージェントはその説明に基づいてスキルを参照するかどうかを判断します。重要なのは、エージェントがスキルを参照するのは、自力では簡単に処理できないタスクに限られることです。「この PDF を読んで」のような単純な 1 ステップのクエリは、説明が完全に一致していても、エージェントが基本的なツールで直接処理できるため、スキルがトリガーされないことがあります。複雑な複数ステップのクエリや、専門性の高いクエリでは、説明が一致すれば確実にスキルがトリガーされます。

つまり、評価クエリは、エージェントが実際にスキルを参照することでメリットを得られる程度に、内容のあるものにする必要があります。「ファイル X を読んで」のような単純なクエリは、説明の質にかかわらずスキルがトリガーされないため、テストケースとして適していません。

ステップ 4：結果を適用する

JSON 出力から best_description を取り出し、スキルの SKILL.md フロントマターを更新します。変更前と変更後をユーザーに示し、スコアを報告します。

---

パッケージ化して提示する

file output ツールを利用できるか確認します。利用できない場合は、このステップを省略します。利用できる場合は、スキルをパッケージ化し、.skill ファイルをユーザーに提示します。

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

パッケージ化したら、インストールできるように、生成された .skill ファイルのパスをユーザーに案内します。

---

サブエージェントのない環境

サブエージェントのない環境でも、基本的なワークフロー（下書き → テスト → レビュー → 改善 → 繰り返し）は同じですが、サブエージェントがないため、一部の仕組みが変わります。次の点を適宜変更してください。

テストケースの実行：サブエージェントがないため、並列実行はできません。テストケースごとに、スキルの SKILL.md を読み、その指示に従ってテストプロンプトを自分で実行してください。1件ずつ行います。独立したサブエージェントを使うより厳密さには欠けます（スキルを作成したのも、それを実行するのもあなたであり、すべての背景情報を把握しているため）が、有用な動作確認になります。また、人間によるレビューのステップで補えます。ベースラインの実行は省略し、スキルを使って要求どおりにタスクを完了してください。

結果のレビュー：ブラウザーを開けない場合（たとえば、ホストにディスプレイがない場合や、リモートサーバーを使っている場合）は、ブラウザーレビュアーを完全に省略してください。その代わりに、結果を会話内で直接提示します。テストケースごとに、プロンプトと出力を表示してください。.docx や .xlsx など、ユーザーが確認する必要のあるファイルが出力された場合は、ファイルシステムに保存し、ダウンロードして確認できるよう保存先を伝えてください。会話内でフィードバックを求めます。「こちらでいかがですか？変更したい点はありますか？」

ベンチマーク：定量的なベンチマークは省略してください。サブエージェントがない場合、ベースラインとの比較に意味がないためです。ユーザーからの定性的なフィードバックを重視してください。

反復サイクル：以前と同様に、スキルを改善し、テストケースを再実行して、フィードバックを求めます。途中にブラウザーレビュアーが入らないだけです。利用できる場合は、ファイルシステム上に反復ごとのディレクトリを作成して、結果を整理することもできます。

説明の最適化：このセクションでは、エージェント CLI ツール（具体的には agent CLI with prompt capability）が必要です。これはプロンプト機能を備えた CLI が必要です。環境にそのような CLI がない場合は省略してください。

ブラインド比較：サブエージェントが必要です。省略してください。

パッケージ化：package_skill.py スクリプトは、Python とファイルシステムがあればどこでも動作します。どこでも実行でき、生成された .skill ファイルをユーザーがダウンロードできます。

既存のスキルの更新：新しいスキルの作成ではなく、既存のスキルの更新を求められる場合があります。その場合は、次の点に従ってください。

• 元の名前を維持してください。 スキルのディレクトリ名と name フロントマターの値を確認し、変更せずに使います。たとえば、インストール済みのスキルが research-helper の場合、出力は research-helper-v2 ではなく research-helper.skill にします。
• 編集する前に、書き込み可能な場所にコピーしてください。 インストール済みのスキルのパスは読み取り専用の場合があります。/tmp/skill-name/ にコピーしてから編集し、そのコピーをパッケージ化してください。
• 手動でパッケージ化する場合は、まず /tmp/ にステージングしてから出力ディレクトリにコピーしてください。 直接書き込もうとすると、権限エラーが発生することがあります。

---

Cowork 固有の手順

Cowork を使っている場合、主に知っておくべきことは次のとおりです。

• サブエージェントを使えるため、メインのワークフロー（テストケースを並列で実行し、ベースラインを実行して採点するなど）はすべて機能します。（ただし、タイムアウトで深刻な問題が発生した場合は、テスト用プロンプトを並列ではなく順番に実行してもかまいません。）
• ブラウザーやディスプレイは使えないため、評価ビューアーを生成する際は、サーバーを起動する代わりに --static <output_path> を使って、単独で動作する HTML ファイルを書き出してください。その後、ユーザーがクリックしてブラウザーで HTML を開けるリンクを提示します。
• 注意：テストを実行した後は、必ずエージェントに評価ビューアーを生成させてください。念のため繰り返しますが、テストの実行後は、スキルを自分で改訂して修正を試みる前に、必ず評価ビューアーを生成して、例を人間に確認してもらってください。その際は、独自の HTML コードを書くのではなく、generate_review.py を使用します。重要：自分で入力を評価する前に、評価ビューアーを生成してください。人間にできるだけ早く確認してもらいましょう！
• フィードバックの仕組みは異なります。サーバーが起動していないため、ビューアーの「すべてのレビューを送信」ボタンを押すと、feedback.json がファイルとしてダウンロードされます。そのファイルをそこから読み取れます（先にアクセス権のリクエストが必要な場合があります）。
• パッケージ化は機能します。package_skill.py に必要なのは Python とファイルシステムだけです。
• 説明の最適化（run_loop.py／run_eval.py）は、ブラウザーではなく agent CLI with prompt capability をサブプロセス経由で使用するため、Cowork でも問題なく機能するはずです。ただし、スキルの作成が完全に終わり、ユーザーが十分な状態だと同意してから実行してください。
• 既存のスキルの更新：新しいスキルの作成ではなく、既存のスキルの更新を依頼されている場合があります。その場合は、上記の opencode セクションにある更新ガイダンスに従ってください。

---

参照エージェント

スキルの評価には、次のグローバルエージェントを使用できます。

• grader — スキルのテスト出力に対するアサーションを評価します
• comparator — 2 つのスキル出力をブラインド A/B 比較します
• analyzer — どちらのバージョンが優れていたか、その理由を分析し、ベンチマークのパターンを調べます

references/ ディレクトリには、追加のドキュメントがあります。

• references/schemas.md — evals.json、grading.json などの JSON 構造
• references/skill-authoring-best-practices.md — Anthropic の公式オーサリングガイダンス：簡潔さ、自由度、段階的な情報開示、説明文の作成、公開前チェックリスト
• references/persuasion-principles.md — 規律を徹底させるスキルで、強固な表現が有効な理由
• references/graphviz-conventions.dot — スキルのフローチャートにおけるスタイルルール

---

重要なので、基本のサイクルをもう一度繰り返します。

• スキルの目的を把握する
• スキルを作成または編集する
• スキルを利用できるエージェントで、テスト用プロンプトを実行する
• ユーザーと一緒に出力を評価する：
  • benchmark.json を作成し、eval-viewer/generate_review.py を実行して、ユーザーが出力を確認できるようにする
  • 定量評価を実行する
• ユーザーが納得するまで繰り返す
• 最終的なスキルをパッケージ化して、ユーザーに返す

忘れないように、TodoList がある場合は手順を追加してください。Cowork を使っている場合は、必ず「テストケースを人間が確認できるように、evals JSON を作成して eval-viewer/generate_review.py を実行する」を TodoList に追加してください。

頑張ってください！