Elites Skills Architect
大まかなアイデアを、実際に動作するスキルに変えます。発見、仕様策定、検証、テスト実行、 人間によるレビュー、説明文の調整、そしてパッケージ化まで。スキルに関するすべての主張は、 スクリプトまたは採点済みの実行結果によって裏付けられます。一度読んで良さそうだからと判断するだけではありません。
どこから始めるか
8つの段階があります。ユーザーがどこにいるかを見極めて、そこから始めてください：
- 発見（Discovery）：具体的な問題と、仕様を書くために必要な事実を収集する
- 問題の特定（Flag problems）：単純すぎる、広すぎる、重複、矛盾を指摘する
- 分類（Categorise）：ドキュメント作成、ワークフロー自動化、MCP拡張のいずれかに分類する
- 構築と検証（Build and validate）：frontmatter、本文、フォルダ、eval、
scripts/validate_spec.pyを実行する - テストとレビュー（Test and review）：evalを実行し、出力を表示し、採点し、スキルが適用するルールを徹底的に検証する
- 改善（Improve）：個々のケースではなく、フィードバックの背後にあるパターンを修正する
- 説明文の調整（Description tuning）：トリガーテストと
scripts/optimize_description.pyを実行する - パッケージ化（Package）：
scripts/package_skill.pyを実行する
ペースはユーザーに合わせて調整してください。「MCPサーバー」や「frontmatter」といった用語を自発的に使う人はスピードを求めています。「Claudeに私の請求書を処理してほしい」と言う人は、一つ一つ質問しながら導く必要があります。平易な英語で、相手が先に使っていない専門用語は避けてください。
すべてのスクリプトは、Python 3.9以降の標準ライブラリのみを使用し、スキルのルートディレクトリから実行します：
cd <elites-skills-architectへのパス>
python3 scripts/validate_spec.py <スキルフォルダ>
ステージ1: 発見
references/discovery-questions.mdを読んで、質問バンクと弱い回答に対するフォローアップを確認します。質問は2～3個ずつまとめて行い、回答に基づいて質問を積み重ね、決してリストを一度にすべて提示しないでください。
バッチ1、問題点：スキルが必ず生み出すべき一つの成果物。ユーザーが実際に言いそうな5～10のフレーズ。スキルが扱ってはならないもの。 バッチ2、データ：入力とその形式。うまくいった時にユーザーが手にしているもの。入力に関してよくある問題。 バッチ3、ワークフロー：手順の順序。依存関係。if/thenの分岐。ステップ3が失敗した場合、ステップ1と2はどうなるか。 バッチ4、統合：MCPサーバー、API、Claudeビルトイン機能、認証とレート制限。 バッチ5、回復力：実行時に発生する可能性が高い3つの障害。完全な障害時のメッセージ。
以下の4つすべてを推測せずにできるようになった時点で、質問をやめてください：実際のトリガーフレーズを含む説明文を書き、すべての手順を順序立ててリストし、3つの障害モードとその対処方法を挙げ、別の開発者が構築できるほどスキルをうまく説明できること。
ユーザーが既に知識を文書化している場合（ハンドブック、APIドキュメント、スタイルガイド、保存したWebページなど）、それを再入力する代わりにインポートします：
python3 scripts/import_sources.py <ファイルまたはフォルダ> --skill <スキルフォルダ> --dry-run
これはMarkdown、テキスト、保存されたHTMLを参照ファイルに変換し、長いものは見出しで分割し、それらの隣にsources-index.mdを書き込み、本文用の「Xを読むのはYの時」という行を出力します。何もダウンロードしません。事前にページを保存しておいてください。
ステージ2: 構築前に問題を特定する
- 単純すぎる：Claudeが既に実行できること。スキルが存在する意味は、毎回適用すべきドメインロジックやフォーマットがある場合です。それが本当にあるかどうかを尋ねてください。
- 広すぎる：無関係な複数のワークフローが含まれている。分割を提案してください。小さなスキルの方がより確実にトリガーされます。どれを最初にやるか尋ねてください。
- 重複：docx、pptx、xlsx、pdf、frontend-designに近い。その旨を伝え、拡張するのか、別のものを作るのかを尋ねてください。
- 不可能または危険：率直にその旨を伝え、実現可能な最も近いバージョンを提案してください。
- 矛盾：以前は「完全自動」と言っていたのに、今は「最初に私に確認する」と言っている。1行も書く前に解決してください。
ステージ3: 分類
references/categories-and-patterns.mdを読んでください。一つ選びます：
- カテゴリ1、ドキュメントとアセットの作成：Claudeビルトイン機能を使用してファイルを作成する。発見のバッチ1と2で十分です。
- カテゴリ2、ワークフロー自動化：ツール間での順序付けられたステップ、検証ゲート、部分的な失敗またはロールバック。全5バッチが必要です。
- カテゴリ3、MCP拡張：既存のMCPサーバーを判断とデフォルト設定でラップする。バッチ1、2、4が必要です。
カテゴリとその理由をユーザーに伝えてください。混在しても構いません。説明文とフォルダレイアウトの主要なカテゴリを一つ選んでください。
ステージ4: 構築と検証
何かを生成する前に、references/worked-example.mdを一度読んで、出力がその詳細レベルと一致するようにしてください。references/spec-output-template.mdを骨組みとして使用します。
4a: Frontmatter
references/yaml-rules.mdを読んでください。バリデーターがチェックする内容（特に記載がない限りエラー）：
- name: kebab-case形式で、「claude」や「anthropic」を含まない。フォルダ名と一致すること（警告、
--portableの場合はエラー） - description: 1～1024文字。アクション動詞、何を作るか、いつ使うか、二重引用符で囲んだ3～8個のトリガーフレーズ、否定的なスコープ（長さはエラー。動詞、フレーズ、否定的スコープは警告）
- 山かっこ、タブ、スマート引用符、ハイフン以外のダッシュを使用しない
- description内にアポストロフィを使用しない（警告。一部のアップロードパーサーが拒否したことがある）
- タグは一つの文字列として、
tags: "a, b, c"と指定し、[a, b, c]とはしない（警告）。数値のように見えるメタデータ値は引用符で囲む、version: "1.0"
descriptionは積極的に作りましょう。テストでは、Claudeが間違ってスキルを選択するよりも、スキルを使用しないままにしておくことの方が多いため、「誰かが...に言及したときにもトリガーする」を間接的なリクエストのために追加してください。
4b: 本文
最大500行、命令形で、何をするかだけでなくなぜそうするのかを説明します。順序：1行の目的。いつ使うべきか、いつ使うべきでないか。各ステップの後にチェックが入った番号付きステップ。2～3の例（フレーズ、アクション、結果）。原因と対応を含むエラーハンドリング。簡単なベストプラクティス。より大きなものはreferences/に移動し、「Xを読むのはYの時」でそれを指し示します。
4c: フォルダ
skill-name/
SKILL.md
evals/evals.json テストケース、詳細はreferences/schemas.mdを参照
scripts/ モデルが再導出すべきでない決定論的ロジック
references/ 必要に応じてロードされる詳細な資料
assets/ テンプレートとサンプル
スキルフォルダ内にREADME.mdは置かないでください。ドキュメントはSKILL.mdとreferences/にあります。
4d: テスト計画とeval
5つ以上のトリガーすべきクエリと、5つ以上のトリガーすべきでないクエリを作成します。良いクエリは具体的で、人が言いそうな言葉であること：「よし、チェックアウトのリデザインを月曜日に開始、Linearでスプリントを設定、2週間、フロントエンドチーム」。最良の否定クエリは肯定クエリと単語を共有しながらも、別のものを求めるものです。アクションではなくアドバイス、作成ではなく報告など。
2～3個のevalをevals/evals.json（フォーマットはreferences/schemas.md）に書きます。各期待値は、チェック可能な一文です。何かを実行する前に、それらをユーザーに提示してください。
4e: 検証
python3 scripts/validate_spec.py <スキルフォルダ>
python3 scripts/validate_spec.py <スキルフォルダ> --json # ツール用
python3 scripts/validate_spec.py <スキルフォルダ> --strict # 警告も失敗として扱う
python3 scripts/validate_spec.py <スキルフォルダ> --portable # Claude以外のエージェント用
これは、frontmatterルール、本文の長さ、上記のセクション、残されたプレースホルダー、evals.json、存在する場合はpressure-evals.json、そして本文が言及するすべてのscripts/...またはreferences/...パスが存在することをチェックします。すべてのエラーを修正してください。失敗するスペックを決して表示しないでください。--portableは、他のエージェントでも実行されるスキルに対して、オープンAgent Skillsスペックルール（フォルダ名が一致する必要がある、メタデータ値はテキストである必要がある）を追加します。
ステージ5: テストとレビュー
一連の流れです。途中で止めないでください。
5a: Evalを実行する
ワークスペースレイアウト（完全なツリーはreferences/schemas.md）：
<スキル名>-workspace/iteration-1/eval-<id>/<設定>/run-<k>/outputs/
eval_metadata.jsonを各eval-<id>/フォルダに書き込みます。次に各evalを実行します：
- サブエージェントを使用する場合（Claude Code、Cowork）：すべてのevalについて、スキルありとなしの実行を同じターンで開始します。各実行エージェントはスキルを読み、プロンプトを実行し、ファイルを
outputs/に保存し、不明な点があればoutputs/user_notes.mdに書き込み、outputs/metrics.jsonに書き込みます。タスク通知からtiming.jsonをすぐに保存します。数値は他のどこにも保持されません。 - サブエージェントを使用しない場合（claude.ai）：SKILL.mdを読み、各プロンプトを自分で一つずつ、同じフォルダに対して実行します。
5b: 実行中にアサーションを作成する
測定可能な期待値をeval_metadata.jsonとevals/evals.jsonに追加します。それぞれを一文でユーザーに説明します。好みに関するアサーションはスキップしてください。それは人間が判断します。
5c: 判断する前に出力を表示する
python3 eval-viewer/review.py <スキル名>-workspace/iteration-1 --skill-name <名前>
ページはブラウザで開き、オフラインで動作し、ユーザーが入力する際にフィードバックをワークスペース内のfeedback.jsonに保存します。Cowork、またはサーバーが利用できない場合は、--static review.htmlを追加します。その場合、フィードバックはファイルとしてダウンロードされます。最初にビューアーを開き、次に自分で出力を確認してください。ユーザーが反応する前にスキルを変更しないでください。
5d: 採点とベンチマーク（サブエージェント）
agents/grader.mdを使用して各実行を採点します。可能であれば、evalを実行したモデルとは異なるモデルを使用してください。モデルは自身の作業を適切に判断できません。- 集計：
python3 scripts/aggregate_benchmark.py <スキル名>-workspace/iteration-1 --skill-name <名前> - ビューアーを
--benchmark <イテレーション>/benchmark.jsonとともに再度開き、ベンチマークタブを表示します。平均値が隠してしまうパターンについては、agents/analyzer.mdのジョブ2を実行します。
5e: プレッシャーテスト（ルールを適用するスキル）
スキルの価値が、維持しなければならないルール（フォーマット、チェック、承認ステップ）である場合、references/pressure-tests.mdを読み、3～5のシナリオをevals/pressure-evals.jsonに作成します。具体的な状況、2つ以上のプレッシャー（納期、上司、クライアントからの依頼、既に費やした時間）、そして魅力的な妥協案を含む強制選択を記述します。
python3 scripts/pressure_eval.py --skill-path <スキルフォルダ> \
--scenarios <スキルフォルダ>/evals/pressure-evals.json --runs 3 --model <モデルID> \
--output <スキル名>-workspace/pressure-results.json \
--report <スキル名>-workspace/pressure-report.md --dry-run
ユーザーが呼び出し回数を承認したら、--dry-runを外します。各シナリオは、スキルなしとスキルありで実行されます。「スキルが保持されない」場合、レポートはClaudeが述べた言い訳を保持します。スキル内でそれぞれに対抗します（名前を付け、なぜ間違っているかを説明し、何をすべきかを述べる）。その後、再度実行します。「合格だが、ベースラインも合格する」場合、シナリオが何かを証明するには簡単すぎることを意味します。
ステージ6: 改善
フィードバックの背後にあるパターンを見つけて修正します。3つのテストプロンプトは全体ではありません。出力だけでなくトランスクリプトも読み、モデルが無駄なステップを踏ませた指示は削除します。ALWAYSやNEVERを大文字で書いている場合は、やめて代わりに理由を説明してください。理由があるモデルは、ルールだけがあるモデルよりも優れた結果を出します。すべての実行が同じヘルパーを書いた場合は、それをscripts/に配置し、その旨を明記します。自分の3つのevalにしか合格しないスキルに注意してください。
次に：変更を適用し、すべてのevalをiteration-2/に再実行し、--previous-workspace iteration-1を付けてビューアーを開き、ユーザーが新旧を並べて見られるようにし、フィードバックを読み、繰り返します。ユーザーが満足したか、フィードバックがなくなったか、進捗が停滞したら停止します。
厳密な新旧比較を行うには、agents/comparator.md（スワップチェック付きの盲検A/B評価）を使用し、その後agents/analyzer.mdのジョブ1で結果を説明します。オプションです。通常はレビューループで十分です。
ステージ7: 説明文の調整
説明文は、Claudeにスキルを選択させるためのものです。スキル自体が機能するようになったら、一度調整します。
7a: トリガークエリ
20個のクエリをevals/trigger-evals.jsonに作成します。約半数がトリガーし、半数がトリガーしないようにします。カジュアルな会話、ファイル名、個人のコンテキストを含めます。価値のある否定クエリはニアミスです。リストをユーザーに表示し、変更を求められたら変更します。悪いクエリは悪い説明文を生み出します。
7b: 実行前に数を確認する
python3 scripts/trigger_eval.py --skill-path <スキルフォルダ> --eval-set <スキルフォルダ>/evals/trigger-evals.json --dry-run
各実行はclaude -p呼び出しです。ユーザーに数を伝え、許可を得てください。
7c: 測定
python3 scripts/trigger_eval.py --skill-path <スキルフォルダ> \
--eval-set <スキルフォルダ>/evals/trigger-evals.json \
--runs-per-query 3 --workers 4 --model <モデルID> \
--output <スキル名>-workspace/trigger-results.json --verbose
このスクリプトは、スキルを使い捨てプロジェクトにインストールし、そのプロジェクトの設定のみでClaudeを実行するため、ユーザーの実際のプロジェクトに影響を与えたり、他のスキルが干渉したりすることはありません。サマリーを読んでください：見逃されたクエリ（偽陰性）は説明文が狭すぎることを意味し、誤って発火したクエリは広すぎることを意味します。すべての実行がエラーになったクエリは、不合格としてではなく、不明として報告されます。
7d: 最適化（Claude Codeのみ）
python3 scripts/optimize_description.py --skill-path <スキルフォルダ> \
--eval-set <スキルフォルダ>/evals/trigger-evals.json --model <モデルID> \
--max-iterations 4 --results-dir <スキル名>-workspace/description-runs --verbose
これはクエリを一度トレーニングセットとホールドアウトセットに分割し、評価し、トレーニングの失敗のみを使用してClaudeにより良い説明文を依頼し、validate_spec.pyと同じルールで候補を検証し、繰り返します。勝者は最も良いトレーニングスコアを得たイテレーションです。同点の場合は、より短いテキストが優先されます。ホールドアウトスコアは報告されますが、選択には使用されないため、正直なチェックとして機能します。トレーニングスコアよりもはるかに低い場合、説明文がトレーニングクエリに過適合していることを意味します。results.json、report.md、best-description.txtを書き込み、勝者がすべてのトレーニングクエリに合格した場合のみ終了コード0で終了します。claude.aiでは、代わりに失敗を読んで手動で書き直してください。
7e: 適用
勝者をSKILL.mdに貼り付け、スコアと共に新旧をユーザーに表示し、scripts/validate_spec.pyを再度実行します。
ステージ8: パッケージ化
python3 scripts/package_skill.py <スキルフォルダ> --output dist/
python3 scripts/package_skill.py --inspect dist/<スキル名>.skill
パッケージ化は最初に検証を行い、エラーがある場合は拒否します（警告がある場合は、--allow-warningsが指定されていない限り拒否します）。アーカイブは再現可能で、SHA-256を出力します。ユーザーにパス、またはファイル自体を提供します。
…
[翻訳のため一部省略]