skill-creator

スキルクリエーター

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

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

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

このスキルを使う際のあなたの役割は、ユーザーがこのプロセスのどの段階にいるのかを把握し、次の段階に進めるよう支援することです。たとえば、「X のためのスキルを作りたい」と言われた場合、意図を絞り込んだり、ドラフトを書いたり、テストケースを作成したり、評価方法を一緒に決めたり、すべてのプロンプトを実行したり、改善を繰り返したりできます。

一方、すでにスキルのドラフトがある場合は、評価と反復の段階から始めることもできます。

もちろん、常に柔軟に対応してください。たとえば、ユーザーが「たくさん評価を実行する必要はないので、気軽に一緒に考えてほしい」と言うなら、そのように対応できます。

スキルが完成したら（ただし、順序は柔軟に変えられます）、専用のスクリプトが用意されているスキル説明改善ツールを実行して、スキルのトリガー条件を最適化することもできます。

いいですか？ いいですね。

ステップ完了レポート

主要なステップを完了するたびに、次の形式でステータスレポートを出力します。

◆ [Step Name] ([step N of M] — [context])
··································································
  [Check 1]:          √ pass
  [Check 2]:          √ pass (note if relevant)
  [Check 3]:          × fail — [reason]
  [Check 4]:          √ pass
  [Criteria]:         √ N/M met
  ____________________________
  Result:             PASS | FAIL | PARTIAL

チェック項目名は、そのステップで実際に検証する内容に合わせてください。合格には √、不合格には ×、簡単な補足には — を使います。「Criteria」の行には、達成した受け入れ基準の数をまとめます。「Result」の行には、全体の判定を記載します。

意図の把握フェーズのチェック項目: Goal defined、Triggers identified、Output format agreed

スキル作成フェーズのチェック項目: SKILL.md written、README generated、Subagents designed

テストフェーズのチェック項目: Evals created、Runs completed、Viewer launched

反復改善フェーズのチェック項目: Feedback incorporated、Benchmarks improved、Description optimized

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

スキルクリエーターは、コーディング用語への習熟度が幅広い人々に使われる可能性があります。もし聞いたことがなくても（つい最近始まったことなので、当然かもしれませんが）、今では Claude の能力に刺激を受けた配管工がターミナルを開き、親や祖父母が「npm のインストール方法」を Google で検索するような傾向があります。一方で、ユーザーの多くは、コンピューターに関する知識をある程度持っているでしょう。

そのため、どのように表現するかは、文脈から判断してください。標準的な場合の目安を以下に示します。

• 「evaluation」と「benchmark」は、使っても問題ないかどうかの境界にある用語です
• 「JSON」や「assertion」は、ユーザーがそれらを知っているという明確な手がかりがない限り、説明なしで使わないようにしてください

不確かな場合は、用語を簡単に説明してもかまいません。ユーザーに伝わるか分からない場合は、短い定義を添えてください。

---

リポジトリを変更するスキルに必須のルール

Git リポジトリ内のファイル（コード、ドキュメント、設定、コミット、公開）を変更するスキルを作成または更新する場合は、そのスキルの SKILL.md に次のルールを含めてください。

• 冒頭近くに 「編集前のリポジトリ同期（必須）」 セクションを追加します。
• 変更を加える前に、リモートの最新ブランチを取得するよう求めます。
  • branch="$(git rev-parse --abbrev-ref HEAD)"
  • git fetch origin
  • git pull --rebase origin "$branch"
• 作業ツリーに変更がある場合は、スタッシュして同期し、その後にスタッシュを適用します。
• origin がない場合、または競合が発生した場合は、作業を止めて、続行する前にユーザーに確認します。

この事前同期の安全策を設けずに、リポジトリを変更するスキルをリリースしてはいけません。

バージョン管理（必須）

すべてのスキルの YAML フロントマターには、セマンティックバージョニング（MAJOR.MINOR.PATCH）を使った metadata.version フィールドが必要です。このバージョンはスキル自体の進化を示すもので、ユーザーやツールがどのイテレーションを実行しているかを把握するためのものです。

新しいスキルを作成する場合、フロントマターに metadata.version: 1.0.0 を設定します。

---
name: my-skill
description: ...
metadata:
  version: 1.0.0
---

既存のスキルを更新または変更する場合は、保存する前に必ずバージョンを上げます。フロントマターから現在のバージョンを読み取り、次のルールに従って増やしてください。

• パッチ（x.y.Z）：バグ修正、誤字修正、動作を変更しない軽微な文言の調整
• マイナー（x.Y.0）：新機能、セクションの追加、新しいサブエージェント、トリガーフレーズの拡張
• メジャー（X.0.0）：スキルのワークフローに対する破壊的変更、出力形式の変更、アーキテクチャの再構成

フロントマターに metadata.version フィールドがない場合は、1.0.0 から追加します。

このルールは、SKILL.md を作成または編集するたびに適用されます。ゼロからの作成、評価フィードバックを受けた改善、説明の最適化、その他あらゆる変更が対象です。バージョンの更新は編集の一部であり、別の作業ではありません。

YAML フロントマターの安全性（必須）

YAML は意外と簡単に壊れます。引用符で囲まれていない値にコロン（:）が含まれていると、多くのパーサーは行の残りを新しいマッピングとして扱い、誤った出力を生成したり、解析エラーを発生させたりします。実際にこの問題により、cli-builder と code-review の両方で、壊れたフロントマターがリリースされました。

ルール：フロントマター内の文字列に次の文字が1つでも含まれている場合は、すべて引用符で囲んでください：:、#、{、}、[、]、,、&、*、?、|、-、<、>、=、!、%、@、`。

実際には、フロントマター内の複数語からなる文字列値は、すべてデフォルトで引用符で囲むのが最も安全です。手間はかからず、この種のバグをまとめて防げます。

問題の例と修正例：

# BROKEN — the : after "workflow" starts a new mapping in strict parsers
description: Follows a 5-step workflow: Analyze -> Design -> Plan -> Execute -> Summarize.

# FIXED
description: "Follows a 5-step workflow: Analyze -> Design -> Plan -> Execute -> Summarize."

# BROKEN — the : after "B+C" breaks strict parsers
architecture: subagent (Pattern B+C: Parallel Workers + Review Loop)

# FIXED
architecture: "subagent (Pattern B+C: Parallel Workers + Review Loop)"

SKILL.md のフロントマターを作成または編集する際は、すべての値にコロンやその他の特殊文字が含まれていないか確認し、含まれている場合はその値を二重引用符で囲んでください。値自体に二重引用符が含まれている場合は、\" でエスケープします。

スキルの作成

意図の把握

まず、ユーザーの意図を把握します。現在の会話に、ユーザーがキャプチャしたいワークフローがすでに含まれている場合があります（たとえば、「これをスキルにして」と言われた場合など）。その場合は、まず会話履歴から、使用したツール、手順、ユーザーによる修正、確認できた入力／出力形式などの回答を抽出します。ユーザーに不足分を補ってもらい、次のステップに進む前に内容を確認してもらいます。

1. このスキルによって、Claude は何ができるようになりますか？
2. どのような場合にこのスキルを起動しますか？（ユーザーが使うフレーズや状況）
3. 期待する出力形式は何ですか？
4. スキルの動作を検証するテストケースを用意しますか？客観的に検証できる出力（ファイル変換、データ抽出、コード生成、固定されたワークフローの手順など）があるスキルでは、テストケースが役立ちます。主観的な出力（文体、アートなど）のスキルでは、必要ないことが多いです。スキルの種類に応じた適切な既定値を提案しますが、最終的にはユーザーに決めてもらいます。
5. **このスキルでサブエージェントを使いますか？**Agent ツールを使ってサブエージェントに作業を委任すると効果的かどうかを評価します。詳しいガイドは references/subagent-patterns.md を参照してください。主な判断材料は次のとおりです。
   • 多数のファイルを読み込んだり、大規模なコードベースをスキャンしたりしますか？→ Explorer サブエージェント
   • 作業の一部を並行して実行できますか？→ 並行作業用サブエージェント
   • 独立した品質レビューが必要ですか？→ 新しいサブエージェントによるレビューループ
   • 集中した推論を必要とする大規模な成果物を作成しますか？→ Executor サブエージェント いずれかに当てはまる場合は、メインエージェントがユーザーとのやり取りと調整を担当し、サブエージェントが負荷の高い作業を担当する、オーケストレーター型のアーキテクチャでスキルを設計します。これにより、メインの会話コンテキストをすっきり保てます。

インタビューと調査

エッジケース、入出力形式、サンプルファイル、成功基準、依存関係について、積極的に質問します。こうした点を固めてから、テスト用プロンプトの作成に進みます。

利用可能な MCP を確認します。調査（ドキュメントの検索、類似するスキルの検索、ベストプラクティスの確認）に役立つ場合は、利用可能なサブエージェントがあれば並行して調査し、なければ会話内で調査します。ユーザーの負担を減らせるよう、あらかじめ必要な情報を用意しておきます。

SKILL.md の作成

ユーザーへのインタビューに基づき、次の項目を記入します。

• name：スキルの識別子です。1～64 文字で、小文字、数字、ハイフンのみを使用し、ハイフンを連続させず、親ディレクトリ名と完全に一致させる必要があります。例：skills/my-skill/SKILL.md にあるスキルの name: my-skill。このルールは scripts/quick_validate.py で検証されます。不一致があると検証に失敗します。
• description：起動する状況と、スキルの機能を記述します。これは主な起動条件となるため、スキルの機能と、使用する具体的な状況の両方を含めます。「いつ使うか」に関する情報はすべて、本文ではなくここに記載します。description は必ず 1 行にしてください（改行や行区切りを入れないでください）。これは、スキルのメタデータを処理する外部ツールや自動化で正しく解析するために必要です。Claude は現在、スキルが役立つ場面でもスキルを使わない「起動不足」になりがちです。そのため、description はやや「積極的」にしてください。ただし、積極性には補完要素があります。それが除外条件です（以下を参照）。
• effort（任意）：スキルに必要な推論の労力です。有効な値は low、medium、high、max です。省略時の既定値は high です。簡単な検索やテンプレートへの記入には low、適度に複数の手順を要するタスクには medium、深い推論を要する複雑なワークフローには high、網羅的な分析を要するタスクには max を使用します。これは任意の属性であり、まだ対応していないツールもあります。
• metadata.version：セマンティックバージョン文字列（例：1.0.0）です。前述の「バージョン管理」を参照してください。作成時に設定し、更新のたびに値を上げる必要があります。
• compatibility：必要なツールや依存関係を記載します（任意。必要になることはまれです）。
• その他のスキルの内容 :)

適切な説明を書く：強いトリガーと除外トリガー

説明には2つの役割があります。スキルを使うべきクエリを引き込み、隣接する分野のうちスキルを使うべきでないクエリを遠ざけることです。ほとんどのスキル作成者は前半（「強く引き込む」部分）はうまく書けますが、後半を忘れてしまいます。その結果、誤検知が起きます。たとえば、Vue プロジェクトで Tailwind スキルが起動したり、シェルスクリプトに関する質問で Python スキルが起動したりします。

解決策は「次の場合には使用しないでください」という一文を加えることです。 キーワードや意図は共通していても、対象外となる隣接分野を挙げます。これは、マーケットプレイス内の他のスキルに近い分野を扱う場合や、広いトピックの一部だけを扱うスキルの場合に特に重要です。

例1 — 肯定的なトリガーのみ（不十分）：

Tailwind CSS を使って React コンポーネントを作成します。

例1 — 除外トリガーを追加（より適切）：

Tailwind CSS を使って React コンポーネントを作成します。ユーザーが新しい React コンポーネント、UI 要素、またはスタイル付きレイアウトを求めた場合は、必ず使用してください。次の場合には使用しないでください： Vue、Svelte、バニラ CSS、またはプレーンな HTML のプロジェクト。

例2 — 肯定的なトリガーのみ：

Postgres スキーマ用の SQL マイグレーションを生成します。

例2 — 除外トリガーを追加：

Postgres スキーマ用の SQL マイグレーションを生成します。ユーザーがスキーマの変更、新しいテーブル、またはインデックスを必要とする場合は必ず起動してください。次の場合には使用しないでください： MySQL、SQLite、MongoDB、または単発のアドホックなクエリ。

肯定的な部分と否定的な部分は、1つの連続した文、または続けて書く2つの文にします。構造化されたリストにはしないでください。説明フィールドは、トリガー判定時にモデルが読む文章です。契約のように感じさせず、対象外のケースを自然に除外することが目的です。

scripts/quick_validate.py は、説明に除外トリガーの節がないように見える場合、致命的ではない警告を出力します。これは注意を促すもので、処理を止めるものではありません。スキルの分野に近接する領域が本当にない場合もありますが、それで問題ありません。

スキル作成ガイド

スキルの構成

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter (name, description required)
│   └── Markdown instructions
├── docs/ (optional — human-only, never auto-loaded)
│   └── README.md (optional — catalog-browsing docs with AI-skip notice)
├── references/ (optional — loaded into agent context when SKILL.md points to them)
│   └── *.md (optional — additional docs loaded as needed)
├── agents/ (optional — subagent prompt files)
│   ├── explorer.md   - Codebase analysis subagent
│   ├── executor.md   - Implementation subagent
│   └── reviewer.md   - Quality review subagent
└── Bundled Resources (optional)
    ├── scripts/    - Executable code for deterministic/repetitive tasks
    └── assets/     - Files used in output (templates, icons, fonts)

agents/ ディレクトリは、Agent ツールを使ってサブエージェントに作業を委任するスキル用です。各ファイルには、特定のサブエージェントの役割について、実行内容、受け取る内容、返す内容を含む完全なプロンプトテンプレートが記載されています。メインのスキルはこれらのファイルを参照します。たとえば、「完全な explorer プロンプトについては agents/explorer.md を読んでください」のように記述します。これにより、メインのスキルを簡潔に保ちながら、サブエージェントには詳細な指示を与えられます。このパターンを使うタイミングと方法については、references/subagent-patterns.md を参照してください。

段階的な情報開示

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

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

主なパターン：

• SKILL.md は500行未満にしてください。これは、ここで作成するスキルに適用される必須ルールであり、単なる推奨ではありません。長い SKILL.md ファイルは呼び出しのたびにトークンを消費し、重要なガイダンスが埋もれがちです。上限に近づいたら、階層をもう1段追加し（詳細なセクションを references/ に移動し）、代わりに「X が必要な場合は references/foo.md を読んでください」のような1行の参照を入れます。
• SKILL.md から参照ファイルを明確に示し、読むタイミングも記載してください
• 大きな参照ファイル（300行超）には目次を含めてください

分野ごとの構成：スキルが複数の分野／フレームワークに対応する場合は、バリエーションごとに整理します：

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

Claude は関連する参照ファイルのみを読みます。

意外性を避ける原則

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

ライティングパターン

指示では命令形を使うことをおすすめします。

出力形式の定義 — 次のようにできます：

## 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

バンドルされたスクリプトとエラーメッセージ

スキルに scripts/ 以下のスクリプトが含まれている場合、そのスクリプトはエージェントの実行対象になります。エージェントはスクリプトを実行し、出力に応じて動作します。つまり、説明のない簡潔な exit 1 は実質的に行き止まりです。エージェントにはゼロ以外の終了コードが返されたことしか分からず、何が問題だったのか、どう復旧すればよいのか判断できません。

ルール：スクリプトは終了前に、説明的で人が読めるエラーメッセージを stderr（または stdout）に出力する必要があります。 スクリプトを実行したエージェントは、ユーザーの介入なしに自ら問題を修正できる必要があります。

悪い例：

if [ -z "$FIELD" ]; then
  exit 1
fi

if not frontmatter.get('name'):
    sys.exit(1)

良い例：

if [ -z "$FIELD" ]; then
  echo "Error: missing required field 'name' in SKILL.md frontmatter." >&2
  echo "Expected format: name: my-skill-name" >&2
  exit 1
fi

if not frontmatter.get('name'):
    print(
        "Error: missing required field 'name' in SKILL.md frontmatter. "
        "Expected format: name: my-skill-name",
        file=sys.stderr,
    )
    sys.exit(1)

良いエラーメッセージでは、次の3点を伝えます。何が問題だったのか、どの入力が原因なのか、どう修正すればよいのか。 修正にファイル名、設定キー、またはコマンドが必要な場合は、具体的に記載してください。エージェントがそのままコピーできるようになります。

ステップ完了レポート（必須）

すべてのスキルは、主要な各フェーズの終了後に、構造化されたステータスレポートを出力する必要があります。チェックマーク付きの行と要約結果の行を含む簡潔な等幅フォントのブロックにして、合否をひと目で確認できるようにします。このファイルの上部にある「Step Completion Reports」セクションの形式に合わせてください。各ステップで実際に検証する内容に応じてチェック項目を調整します（たとえば、コードレビューのスキルなら Correctness、Test coverage、Security、Edge cases、デプロイのスキルなら Build、Tests、Lint、CI status などを使用します）。

ライティングスタイル

堅苦しく「必須」を連発するのではなく、なぜ重要なのかをモデルに説明するようにしてください。心の理論を意識し、特定の例に極端に限定されない、汎用的なスキルを目指してください。まず下書きを作成し、あらためて読み直して改善してください。

README.md の生成

スキルに README.md が含まれる場合は、専用の docs/ ディレクトリに配置してください。README.md は人がカタログを参照するためのものです。.skill パッケージには含まれますが、エージェントのコンテキストに自動で読み込まれることはありません。 ランタイムローダーが読み込むのは、フロントマターの name と description（常時）、SKILL.md の本文（トリガー時）、および scripts/、references/、assets/ 以下のファイル（SKILL.md で読み込むよう指示された場合のみ）です。docs/ はこれら4つの対象外なので、そこに README を置いてもランタイムトークンを消費しません。スキルのインストールを検討する人に必要な情報、つまり機能、トリガー、ワークフロー図、使い方に内容を絞ってください。

つまり、「トークンを無駄にする人向けの文章を詰め込まない」というルールが当てはまるのは、読み込まれる SKILL.md と references/ であり、docs/README.md ではありません。

重要： AI エージェントが誤って README.md を読み込まないように、すべての README.md ファイルの先頭に次の警告コメントを追加してください。

次のテンプレートを使用してください。

# [Skill Display Name]

> [One-line description of what the skill does]

## Highlights

- [Key capability 1]
- [Key capability 2]
- [Key capability 3]
- [Key capability 4]

## When to Use

| Say this... | Skill will... |
|---|---|
| "[trigger phrase 1]" | [What happens] |
| "[trigger phrase 2]" | [What happens] |
| "[trigger phrase 3]" | [What happens] |

## How It Works

` ` `mermaid
graph TD
    A["[First Step]"] --> B["[Second Step]"]
    B --> C["[Third Step]"]
    C --> D["[Final Step]"]
    style A fill:#4CAF50,color:#fff
    style D fill:#2196F3,color:#fff
` ` `

## Usage

` ` `
/[skill-name]
` ` `

## Resources

| Path | Description |
|---|---|
| `references/` | [What the references contain] |
| `scripts/` | [What the scripts do] |

## Output

[Description of what the skill produces — files, reports, etc.]

README のルール：

• タイトル：人が読んで分かる表示名を使用します（例：「code-optimizer」ではなく「Code Optimizer」）
• キャッチフレーズ：ブロック引用形式（> 接頭辞）の1文
• 主な機能：主要な機能を3～5項目の箇条書きで記載
• 使用するタイミング：トリガーフレーズとアクションを対応付けた3～4行の表
• 動作の仕組み：主なワークフローの手順を示す Mermaid の graph TD 図。最初のノードは緑（#4CAF50）、最後のノードは青（#2196F3）
• 使用方法：スラッシュコマンドの呼び出しを含むコードブロック
• 出力：スキルが生成するものを簡潔に説明
• 任意の Resources セクション：スキルに scripts/、references/、または assets/ ディレクトリがある場合は、| Path | Description | 列を持つ表

テストケース

スキルのドラフトを書いたら、現実的なテストプロンプトを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 を参照してください。

スキルの出力形式やファイル書き込み動作を設計する際は、references/output-patterns.md を読んでください。 スキルで複数フェーズのワークフローや反復ループを構成する際は、references/workflows.md を読んでください。 スキルに大規模な調査、並列タスク、レビューループ、大量の成果物の生成が含まれる場合は、メインエージェントのコンテキストを整理しておけるサブエージェントのアーキテクチャを設計するために、references/subagent-patterns.md を読んでください。

オプション：評価前の LLM 検証

本格的な評価の実行にトークンを費やす前に、より低コストな4フェーズの LLM 検証を実施して、トリガーの失敗、曖昧なロジック、エッジケースの見落とし、アーキテクチャの肥大化を検出できます。次のコピー＆ペースト用プロンプトについては、references/validation-prompts.md を読んでください。

1. 検出の検証 — フロントマターは単独で正しくトリガーされますか？
2. ロジックの検証 — 手順を段階的にシミュレーションし、曖昧な指示を見つけます
3. エッジケースのテスト — 敵対的なプロンプトで失敗状態を探します
4. アーキテクチャの改善 — 段階的な情報開示とトークン使用の規律を徹底します

これは任意です。スキルのドラフト作成後、大規模な書き換え後、または説明できない評価の失敗が発生した際に役立ちます。

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

5ステップの全手順（実行の開始、アサーションの作成、時間の記録、採点・集計・表示、フィードバックの確認）については、references/eval-loop.md を読んでください。このファイルでは、with-skill とベースラインのサブエージェントパターン、eval_metadata.json の形式、timing.json の記録、generate_review.py の呼び出し、ユーザーが完了した後の feedback.json の確認方法について説明しています。

/skill-test やその他のテスト用スキルは使用しないでください。このスキルでは、references/eval-loop.md のフローを使用します。

スキルの改善

改善ループについては、references/iteration.md を読んでください。このファイルでは、フィードバックに基づいてスキルを改訂するための5つの原則（一般化する、簡潔さを保つ、理由を説明する、繰り返し作業を見つける、サブエージェントを検討する）に加えて、反復ループ自体と任意のブラインド比較システムについて説明しています。

説明の最適化

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

4ステップの全手順（トリガー評価用クエリの生成、HTML テンプレートを使ったユーザーとの確認、run_loop.py による最適化ループの実行、最適な説明の適用）については、references/description-optimization.md を読んでください。このファイルでは、トリガーの仕組み自体と、些細なクエリよりも内容のあるクエリが評価素材として適している理由についても説明しています。

パッケージ化して提示する（present_files ツールが利用可能な場合のみ）

present_files ツールを利用できるか確認してください。利用できない場合は、この手順をスキップしてください。利用できる場合は、スキルをパッケージ化して .skill ファイルをユーザーに提示してください。

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

パッケージ化したら、インストールできるよう、生成された .skill ファイルのパスをユーザーに伝えてください。

環境固有の注意事項

Claude.ai（サブエージェントなし）または Cowork（サブエージェントはあるがブラウザーなし）を使用している場合は、一部の手順が変わります。各環境に合わせたフローについては、references/environment-modes.md を読んでください。基本のループ（ドラフト → テスト → レビュー → 改善）はどの環境でも同じですが、実行方法のみが異なります。

---

参考ファイル

agents/ ディレクトリには、専門サブエージェント向けの指示が含まれています。該当するサブエージェントを起動する必要がある場合は、指示を読んでください。

• agents/grader.md — 出力に対するアサーションの評価方法
• agents/comparator.md — 2つの出力をブラインドでA/B比較する方法
• agents/analyzer.md — 一方のバージョンが他方より優れていた理由を分析する方法

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

• references/schemas.md — evals.json、grading.jsonなどのJSON構造
• references/subagent-patterns.md — Agentツールを使ってサブエージェントに作業を委任するスキルを設計するタイミングと方法
• references/workflows.md — Subagent Orchestrationパターン（パターン8）を含む、スキルの指示を構成するワークフローパターン
• references/output-patterns.md — 出力形式とファイル書き込みのパターン
• references/validation-prompts.md — スキルのドラフトに対する、任意の4フェーズLLM検証パス
• references/eval-loop.md — 評価の実行／採点／ビューアーの完全な5ステップのフロー
• references/iteration.md — フィードバックに基づいてスキルを改善する原則。ブラインド比較
• references/description-optimization.md — 説明を調整する4ステップのワークフロー
• references/environment-modes.md — Claude.aiとCowork固有の調整

---

重要なので、コアループをもう一度ここに記載します。

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

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

頑張ってください！