skill-upper

use-skill-up-cli

skill-up CLI を使って、ユーザーが Agent Skills を評価し、進化させるのを支援します。

マニュアル：https://alibaba.github.io/skill-up/

言語ポリシー

ユーザーへの応答は、デフォルトで英語にしてください。ユーザーが中国語（またはほかの言語）で書いた場合は、その言語に切り替え、セッションを通じてユーザーの入力言語に統一してください。

判定ルール（優先度の高い順）：

1. ユーザーが現在のメッセージで言語を明示的に指定している場合（例：「英語で回答して」や「中国語で返信して」）→ ユーザーの指示に従います。
2. ユーザーが現在のメッセージで使っている自然言語 → その言語に合わせます。
3. 上記のいずれにも該当しない場合 → デフォルトの英語を使用します。

応答言語にかかわらず、この SKILL 内の技術的な識別子（CLI コマンド、eval.yaml / case.yaml のフィールド名、レポートのフィールド名など）は、元の英語表記のままにする必要があります。翻訳しないでください。

生成する成果物の言語ルール

返信、新たに作成する説明文、 YAML コメントには、ユーザーの現在の言語を使用してください。テスト入力、期待される 出力のリテラル、識別子、コマンド、パス、既存の回帰ケースについては、言語と意味を維持してください。 会話の言語が変わったというだけで、決定的なアサーションを翻訳しないでください。ローカライズされた動作をテストする場合は、会話が英語でも元の業務テキストを維持してください。

assets/*.tmpl は構造上の参照として扱ってください。プレースホルダーの説明文やコメントは、指定された言語に合わせてください。このタスクで作成または変更したファイルのみを確認してください。言語の統一を強制するために、無関係なケースを書き換えないでください。

生成する YAML には、フィールド名を先頭に置いた短いコメントを使用してください。実際に設定されているフィールドについて説明してください。eval.yaml では schema_version、environment.type、engine.name、cases.files、report.formats を、case YAML では id、title、input.prompt、judge.type を説明します。ネストされたフィールドでは、親マッピングの内部で子フィールドの直前にコメントを置き、親の前に置くだけにしないでください。 たとえば、prompt と type の両方に、それぞれのインデント位置でコメントを付けます。

input:
  # User request sent to the agent.
  prompt: Review this code.
# Cheap prerequisites checked before the judge.
expect:
  must_contain: ["suggestion"]
judge:
  # Deterministic grading strategy for this case.
  type: rule_based

expect と、存在する場合はトップレベルの judge にコメントを付けてください。コメントチェックを満たすためだけに、任意のフィールドを追加しないでください。フィールド名と列挙値は変更しないでください。skill-up import はテンプレートのコメントを保持しません。

skill-up とは

skill-up は Agent Skill の作成者向けの評価 CLI です。Skill を実際の Agent Engine（Claude Code、Codex、qodercli など）にインストールし、各ケース用の実行環境を起動してプロンプトを実行した後、定義されたルール／LLM ジャッジ／カスタムスクリプトで結果を評価し、最終的にレポートを生成します。

一般的なレイアウト：

my-skill/
  SKILL.md
  evals/
    eval.yaml
    cases/
      <case-id>.yaml
    fixtures/

使用するタイミング

以下のいずれかに該当する場合は、このスキルを使用してください。

• ユーザーが「このスキルを実行／評価／検証／テストして」と依頼した場合。
• ユーザーが評価の失敗を受けて「このスキルを修正／改善／反復／進化させて」と依頼した場合。
• ユーザーが「スキルに評価、テストケース、または回帰ケースを追加したい」と希望する場合。
• ユーザーが、明示的に帰属を示した Skill の使用状況、証拠、またはフィードバックの記録を求めた場合。
• ユーザーが、記録された Skill の観察結果を確認するか、承認済みのフィードバックを回帰ケースにすることを希望する場合。
• ユーザーが eval.yaml / case.yaml の編集を希望するか、適切な judge タイプの選択を求めた場合。
• ユーザーが skill-up run/validate/list-cases/report/import/init に言及した場合。
• ユーザーが Anthropic の evals.json から skill-up への移行を希望する場合。
• 現在の作業ディレクトリに evals/eval.yaml または evals/evals.json があり、ユーザーがそれを実行したい場合。

要求されたワークフローを選択する

• 診断または計画： 対象の Skill と提供された証拠を確認し、具体的な問題を特定して、変更案やケースを提案します。依頼がない限り、ツールのインストール、評価ファイルの作成、設定の変更、評価の実行は行いません。
• ケースの作成または編集： Steps 1–4 を使用してスイートを作成または更新し、その設定を検証します。ユーザーから実行も依頼されていない限り、認証情報の設定と実行に進まずに終了します。最終回答では、実際の設定ファイルとケースのパス、検証状況を報告します。
• 評価： 依頼されたスイートについて Steps 0–7 に従います。Skill を自動編集せずに、失敗を報告します。
• 改善： 評価ワークフローと Step 8 に従い、依頼された範囲内で作業します。有効な既存のケースとアサーションを維持します。

評価ワークフロー

観察の記録モード（任意）

ユーザーが現在の Skill のやり取りやフィードバックの記録を依頼し、観察ツールを利用できる場合は、このモードを使用します。このモードには、codex-skill-up プラグインとライフサイクルフックのサポートがある現行の Codex リリース、または skill-up プラグインのオブザーバーが明示的に有効化された DSH のいずれかが必要です。固定された Codex 0.80.0 評価アダプターに観察の記録を後付けしないでください。

ユーザーからどちらかのホストプラグインのインストール方法を尋ねられた場合、または必要な観察ツールがなく有効化を依頼された場合は、references/install.md の「Install an observation host plugin (optional)」を確認します。ユーザーから依頼されない限り、プラグインをインストールまたは有効化しないでください。

Claude Code、qodercli、Qwen Code、その他の Agent Engines は、この観察ワークフローではサポートされていません。この制限は通常の skill-up 評価実行には適用されず、通常の評価は引き続き複数のエンジンで実行できます。

1. ユーザーが Skill（例：$my-skill）を明示的に参照した場合、または担当する Skill が確実に判明している場合に限り、やり取りを帰属させます。
2. Codex では、明示的な帰属がなくても Skill が確実に判明している場合は、Skill 名と任意のバージョンを指定して mark_skill_invocation を一度呼び出します。DSH では、永続的な /skill の注入、または成功した skill ツールの結果から正確な帰属が導出されます。推測による帰属を追加しないでください。
3. Codex では、動作の再現または評価に役立つ参照に限り、attach_skill_evidence を使用します。コピーしたファイルの内容よりも、パスと簡潔な要約を優先します。
4. Codex では、観察対象のターン中に record_skill_feedback を使用します。DSH では、オブザーバーが同じセッションにおける次のユーザーターンを、未分類のフォローアップ候補として保存します。明示的なフィードバックには、完了した観察の ID を指定して record_observation_feedback を使用します。感情やコメントを捏造しないでください。

どちらのアダプターも、一般的な認証情報の形式をローカルに保存する前にマスキングしますが、マーカーツールにシークレットを送信しないようにしてください。記録のみの依頼の場合は、記録後に終了します。ユーザーから追加で依頼されていない限り、Skill の編集、評価、コミット、公開は行いません。

観察入力モード（任意）

依頼の起点が記録済みの Skill の観察である場合は、最初に references/observations.md を確認します。利用可能な観察ツールを使って観察を調査し、プレビューを確認します。対象候補への明示的な承認を得たうえで書き込みを行い、その後 Step 4 に進みます。依頼が観察を起点としていない場合は、以下の通常のフローを使用します。

Step 0：skill-up がインストールされていることを確認する

何かを行う前に、skill-up が利用可能か確認します。

command -v skill-up && skill-up --version

バージョンが表示された場合は続行します。command not found と表示された場合は、macOS / Linux で次を実行します。

curl -fsSL https://raw.githubusercontent.com/alibaba/skill-up/main/install.sh | bash

export SKILL_UP_VERSION=v0.1.0
curl -fsSL https://raw.githubusercontent.com/alibaba/skill-up/main/install.sh | bash

export INSTALL_DIR="$HOME/bin"
curl -fsSL https://raw.githubusercontent.com/alibaba/skill-up/main/install.sh | bash

プラットフォーム： skill-up が現在サポートしているのは macOS / Linux のみです。Windows はサポートされていません。

インストール後、再度 skill-up --version を実行します。それでもコマンドが見つからない場合は、~/.local/bin を PATH に追加します。

任意の Codex および DSH 観察ホストプラグインを含む詳細については、references/install.md を参照してください。

ステップ 0.5（任意）：ユーザー設定とテレメトリー

OTLP のデフォルト設定、runtime_kwargs（例：OpenSandbox の base_url）などについて：

skill-up init
skill-up init --local
skill-up init --print
skill-up init --force

優先順位（低 → 高）：埋め込みの空のデフォルト設定 < ユーザー設定 < プロジェクトの .skill-up.yaml < --config。SKILL_UP_CONFIG でユーザー設定ファイルを指定できます（環境変数名は歴史的なものです）。上流の README の「User config」を参照してください。

ステップ 1：対象の Skill を特定する

1. 対象の Skill のルートディレクトリ（SKILL.md を含むディレクトリ）を特定します。次の優先順位で検索します：ユーザー指定のパス → CWD から上位へさかのぼって最も近い SKILL.md → 最近表示したファイル。
2. 対象の SKILL.md を読み、適用範囲、トリガー、依存関係を確認します。ケースを設計する際は、ローカライズされた動作と想定されるリテラルを維持してください。
3. evals/ を確認します：
   • evals/eval.yaml が存在する → ステップ 4（ステップ 3 も任意で実施）。
   • evals/evals.json のみ存在する → references/migrate-anthropic.md（skill-up run --auto または skill-up import）。
   • 何もない → ステップ 2。

ステップ 2：evals をひな形から作成する（存在しない場合のみ）

• assets/eval.yaml.tmpl を <skill-root>/evals/eval.yaml にコピーします。
• assets/case.yaml.tmpl を <skill-root>/evals/cases/<case-id>.yaml にコピーします。

ユーザーが求める最小限の完全なひな形から始めます。より広い範囲を求められていない限り、代表的なケースを 1 つ作成し、異なる要件がある場合にのみ追加します。スクリプト判定を使う場合は、必要な出力契約を短いスクリプトで実装し、同じ契約のケース間で再利用します。ひな形の作成にあたり、汎用的なレポートパーサーや大規模なスクリプトテストマトリックスは作成しないでください。JSON のみの契約では、json.loads と明示的なフィールドチェックを使います。契約で許可されている場合に限り、散文や Markdown によるラッパーに対応します。

「生成アーティファクトの言語ルール」に従って言語を調整します。テンプレート内の汎用的な英語のプレースホルダーを、指定された出力言語のケース固有の文章に置き換えます。生成する YAML のフィールド冒頭の短いコメントは維持し、出力言語が英語以外の場合は翻訳します。ただし、フィールド名と列挙値は英語のままにしてください。

選択の指針：

• environment.type：テキストのみの Skill には none を使用します。リモートサンドボックスが必要な場合は opensandbox を使用します（OPENSANDBOX_API_KEY を設定し、秘密情報以外は environment.kwargs に指定します）。
• engine.name + engine.model：デフォルトは claude_code です。model は任意です。qodercli では、model を省略することがよくあります。
• judge.type：rule_based（推奨）、script、agent_judge（高コスト）から選びます。references/judge-types.md を参照してください。
• ケース ID は .yaml を除いたファイル名です。プロンプトでは Skill の実際の価値を試してください。
• 対話型のケースでは、ユーザーメッセージが既知の場合、固定の input.turns[].content を維持します。エージェントの応答を受けて返答する必要がある場合にのみ input.turns[].respond を使用します。また、シミュレーターが以降のすべての返答と終了タイミングを選ぶ場合は、input.prompt とケースレベルの user_simulator.scenario を使用します。評価レベルで独立した user_simulator モデルを設定し、max_turns に上限を設けます。両方の YAML リファレンスを参照してください。engine.model や judge.model を暗黙のシミュレーターモデルとして再利用しないでください。

references/eval-yaml.md と references/case-yaml.md を参照してください。

ステップ 3：不足を補う（evals がすでに存在する場合）

• skill-up list-cases <path>
• eval.yaml と代表的なケースを確認し、agent_judge の過剰な使用を避けます。
• 必要に応じて cases/ の下に YAML を追加または編集します。
• バイト単位での保持を確認するには、ユーザーが許可したコマンドの範囲内で、編集前後に sha256sum <file>（または shasum -a 256 <file>）を比較します。
• シミュレートしたユーザーターンを追加する場合は、選択したエンジンがセッション再開に対応していることを確認し、別個のシミュレーター接続を設定します。可能な限り、決定的な固定ターンと判定条件を維持してください。

ステップ 4：設定を検証する

skill-up validate <skill-root>/evals/eval.yaml

次のように表示されることを確認します：✓ eval.yaml is valid (loaded N case(s))。

ケース作成の依頼の場合は、設定ファイルとケースのパス、および検証状況を伝えて、ここで終了します。スキャフォールディングの一環としてバックグラウンド評価を開始しないでください。返信する前に、生成した YAML を開き直し、設定されている場合は、ネストされた input.prompt、judge.type、report.formats の直前にコメントがあることを確認します。input、judge、report の前にあるコメントは、その子フィールドの説明にはなりません。生成したケースを一つずつ確認し、実際の judge: ブロックを読み、説明コメントが judge: と type: の間にあり、type: と同じインデントになっていることを確認します。コメントが judge: より上にある場合は、マッピング内に移動して、もう一度検証します。YAML の検証に成功したことや、書くつもりだった内容から、コメントが適切に付いていると判断しないでください。 expect ブロックの場合は、説明コメントを expect: の直前に置きます。その中の must_contain の上にあるコメントは、親のゲートの説明にはなりません。 新しい採点スクリプトを作成する場合は、可能であれば成功するサンプルと失敗するサンプルを一つずつ確認してから、確認内容を報告して終了します。ユーザーから依頼されない限り、関係のないスクリプト機能や大規模なテストマトリックスに手を広げないでください。

ステップ 5：認証情報を準備する

選択したエンジンとプロバイダーの認証を確認します。プロバイダーの API キーは、--api-key、環境変数、または ~/.skill-up/credentials.yaml から解決されます。エンジン固有のトークンと保存済みのログインセッションは、各エンジンの認証ルールに従います。環境変数や認証情報ファイルの内容を出力したり、ツールの出力、ログ、会話にシークレット値を表示したりしないでください。関連する変数に空でない値が設定されているかどうかだけを確認します。たとえば、OpenAI API キーを使用するワークフローの場合：

if printenv OPENAI_API_KEY | grep -q .; then
  printf '%s\n' 'OPENAI_API_KEY: configured'
else
  printf '%s\n' 'OPENAI_API_KEY: not configured in the environment'
fi

環境変数が存在しなくても、ファイルベースの認証情報や、すでにログイン済みのエンジンが利用できないとは限りません。選択した認証方法が利用できない場合は、停止してユーザーに依頼し、ローカルで設定してもらいます。シークレットを会話に貼り付けるよう求めたり、同意なくシークレットを YAML に書き込んだりしないでください。

認証情報の確認スクリプトを作成するよう求められた場合は、検証時にもユーザーが許可したコマンドの範囲を守ってください。スクリプトを書いたからといって、スクリプト実行が許可されていないプロファイルで sh、sh -x を使って起動したり、スクリプトを読み込んだりしてよいことにはなりません。作成した確認スクリプトを調べ、実行していないことを報告してください。テストのためだけに、許可されていない起動方法を追加しないでください。シェルトレースの動作を確認する場合は、合成した認証情報を使った、明示的に許可された隔離テストでのみ行ってください。

ユーザーシミュレーターは、独自の user_simulator.provider に基づいて認証情報を解決します。provider: simulation の場合は、SIMULATION_API_KEY と SIMULATION_BASE_URL を設定するか、~/.skill-up/credentials.yaml で simulation プロバイダーを設定します。provider: openai の場合は、OPENAI_API_KEY と、必要に応じて OPENAI_BASE_URL を使用します。標準エンドポイントはフォールバックとして使用されます。Chat Completions には protocol: openai を、Messages には protocol: anthropic を選択します。カスタムのベース URL は、使用するプロトコルに一致させる必要があります。protocol: anthropic の provider: anthropic の場合は、ANTHROPIC_API_KEY と、必要に応じて ANTHROPIC_BASE_URL を使用します（公式エンドポイントがフォールバックとして使用されます）。エージェントに指定する --api-key は、シミュレーターの接続には使用されません。eval YAML に未加工のキーを記載しないでください。

opensandbox の場合は、必要に応じて OPENSANDBOX_API_KEY（および関連する環境変数）も設定してください。

ステップ 6：評価を実行する

skill-up run <skill-root>/evals/eval.yaml

シナリオ	コマンド
サブセット	--include-case-name "basic-*"
除外	--exclude-case-name "*-flaky"
HTML レポート	--format html
エンジンの上書き	--engine codex --model openai/gpt-4
並列実行数	--parallelism 4 (1–256)
Anthropic JSON	--auto
安定性／不安定性のサンプリング	--iteration 3
最後の反復後に自動追加	--iteration 0（デフォルトの動作）
詳細	-v、-vv

終了コード 0 = すべて成功、1 = 失敗またはエラーです。CI に適しています。明示的に正の値を指定した --iteration N で複数のサンプルを実行した場合は、端末に表示されるシンプルな現在のコマンドの要約で、次のような行を確認してください。 case_a: 3 trials, 2 PASS, 1 FAIL -> flaky

ステップ 7：レポートを解釈する

成果物の保存先：<skill-root>/<skill-name>-workspace/iteration-N/：

• result.json、benchmark.json、任意で report.html
• <case-id>/with_skill/grading.json、outputs/

成功率と所要時間を要約します。失敗については、ケース ID、アサーションの text、evidence を示します。ベンチマークが有効な場合は差分も示し、HTML のパスまたは skill-up report result.json --format html を案内します。 シミュレーションケースでは、トランスクリプトと併せて、各ターンの source と stop_reason があれば確認してください。max_turns に達した場合は実行エラーです。シミュレーターの停止だけで PASS になるわけではありません。設定された判定器が引き続き結果を評価します。

ステップ 8：要求に応じて Skill を改善する

このループに入るのは、ユーザーが対象の Skill の修正、改善、反復、または進化を求めた場合に限ります。ユーザーが評価または結果の報告のみを求めた場合は、変更を加えずにステップ 7 で終了します。

1. result.json、grading.json、出力のエビデンスを確認して、失敗の原因を特定します。
2. Skill の動作が正しくない場合は、SKILL.md またはサポートファイルを修正します。
3. テスト範囲が不足している場合は、評価ケースを追加または改善します。
4. 失敗を成功にするためだけに、有効なアサーションを弱めないでください。
5. まず失敗したケースを再実行し、その後、評価スイート全体を実行します。
6. 評価に合格するまで続けるか、残っているブロッカーを明確に報告します。

コマンド早見表

コマンド	目的
skill-up validate <eval.yaml>	run の前に検証します。
skill-up list-cases <eval.yaml>	ケースを一覧表示します。
skill-up run [eval.yaml]	評価を実行します。
skill-up run --auto	evals/evals.json から実行します。
skill-up report <result.json> --format html	レポートを再生成します。
skill-up import <evals.json>	Anthropic 形式を YAML に変換します。
skill-up init	ユーザー設定テンプレートを書き込みます。
skill-up debug judge <input.json>	判定器をデバッグします。
skill-up debug report <input.json>	レポートをデバッグします。

すべてのフラグについては、references/cli.md を参照してください。

よくある落とし穴

• モデル ID とプロキシのエイリアスの違いに注意し、ユーザーの base_url で動作する設定を維持します。
• OPENSANDBOX_API_KEY を設定せずに opensandbox を使うと、認証に失敗します。
• 決定的なアサーションの言語は、会話の言語だけで判断せず、テスト対象の動作に合わせます。
• agent_judge の乱用に注意します。
• Anthropic の evals.json の期待値は、既定で agent_judge に変換されます。決定的なチェックには import と手動編集を使います。
• パスは Skill のルート（SKILL.md のディレクトリ）からの相対パスです。
• シミュレーターの応答は、{{placeholders}} を含めて文字どおりのユーザーテキストです。キャプチャした変数の置換は、設定済みの固定ターンと respond の指示でのみ行います。
• --iteration 0 は、履歴を要約せず、既存の最新イテレーションの後に 1 回の実行を追加します。正の値の --iteration N は、選択したケースを N 個サンプル実行し、N > 1 の場合は、現在のコマンドのサンプルのみを対象に、単純な安定性／不安定性の要約を出力します。

参考資料

• references/install.md
• references/eval-yaml.md
• references/case-yaml.md
• references/judge-types.md
• references/cli.md
• references/migrate-anthropic.md
• references/observations.md
• assets/eval.yaml.tmpl、assets/case.yaml.tmpl