skill-test

Databricks Skills Testing Framework

人間がレビューに参加し、スキルを対話的に改善できる、オフラインでの YAML ファーストな評価です。

クイックリファレンス

• スコアラー - 利用可能なスコアラーと品質ゲート
• YAML スキーマ - マニフェストとグラウンドトゥルースの形式
• Python API - プログラムからの使用例
• ワークフロー - 詳細なワークフロー例
• トレース評価 - セッショントレースの分析

/skill-test コマンド

/skill-test コマンドは、Databricks 上で実際に実行して Databricks スキルをテストするための、対話型 CLI を提供します。

基本的な使い方

/skill-test <skill-name> [subcommand]

サブコマンド

サブコマンド	説明
run	グラウンドトゥルースに対して評価を実行します（デフォルト）
regression	現在の結果をベースラインと比較します
init	新しいスキルのテスト用スキャフォールディングを初期化します
add	対話形式：プロンプト -> スキルを呼び出す -> テスト -> 保存
add --trace	トレース評価を含むテストケースを追加します
review	保留中の候補を対話形式でレビューします
review --batch	保留中の候補をすべて一括で承認します
baseline	現在の結果を回帰テストのベースラインとして保存します
mlflow	LLM ジャッジを使って MLflow 評価を完全に実行します
trace-eval	スキルの期待値に照らしてトレースを評価します
list-traces	利用可能なトレースを一覧表示します（MLflow またはローカル）
scorers	スキルに設定されたスコアラーを一覧表示します
scorers update	スコアラーの追加・削除、またはデフォルトのガイドラインの更新を行います
sync	YAML を Unity Catalog に同期します（フェーズ 2）

クイック例

/skill-test databricks-spark-declarative-pipelines run
/skill-test databricks-spark-declarative-pipelines add --trace
/skill-test databricks-spark-declarative-pipelines review --batch --filter-success
/skill-test my-new-skill init

各サブコマンドの詳しい例については、ワークフローを参照してください。

実行手順

環境のセットアップ

uv pip install -e .test/

Databricks MLflow 用の環境変数：

• DATABRICKS_CONFIG_PROFILE - Databricks CLI のプロファイル（デフォルト："DEFAULT"）
• MLFLOW_TRACKING_URI - Databricks MLflow の場合は "databricks" に設定します
• MLFLOW_EXPERIMENT_NAME - 実験のパス（例："/Users/{user}/skill-test"）

スクリプトの実行

すべてのサブコマンドに、.test/scripts/ 内の対応するスクリプトがあります：

uv run python .test/scripts/{subcommand}.py {skill_name} [options]

サブコマンド	スクリプト
run	run_eval.py
regression	regression.py
init	init_skill.py
add	add.py
review	review.py
baseline	baseline.py
mlflow	mlflow_eval.py
scorers	scorers.py
scorers update	scorers_update.py
sync	sync.py
trace-eval	trace_eval.py
list-traces	list_traces.py
_routing mlflow	routing_eval.py

利用可能なオプションを確認するには、各スクリプトで --help を使用してください。

コマンドハンドラー

/skill-test が呼び出されたら、引数を解析して適切なコマンドを実行します。

引数の解析

• args[0] = skill_name（必須）
• args[1] = subcommand（省略可能。デフォルト："run"）

サブコマンドのルーティング

サブコマンド	アクション
run	run(skill_name, ctx) を実行して結果を表示します
regression	regression(skill_name, ctx) を実行して比較結果を表示します
init	init(skill_name, ctx) を実行してスキャフォールディングを作成します
add	テスト入力を求め、スキルを呼び出し、interactive() を実行します
review	review(skill_name, ctx) を実行して保留中の候補をレビューします
baseline	baseline(skill_name, ctx) を実行して回帰テストのベースラインとして保存します
mlflow	mlflow_eval(skill_name, ctx) を MLflow ロギングとともに実行します
scorers	scorers(skill_name, ctx) を実行して設定済みのスコアラーを一覧表示します
scorers update	scorers_update(skill_name, ctx, ...) を実行してスコアラーを変更します

init の動作

/skill-test <skill-name> init を実行すると、次の処理が行われます。

1. スキルの目的を理解するため、スキルの SKILL.md を読み取ります
2. 適切なスコアラーと trace_expectations を含む manifest.yaml を作成します
3. 空の ground_truth.yaml と candidates.yaml のテンプレートを作成します
4. ドキュメントの例に基づいて、テスト用のプロンプトを推奨します

推奨されたプロンプトを使って、続けて /skill-test <skill-name> add を実行してください。

コンテキストのセットアップ

コマンドを呼び出す前に、MCP ツールを含む CLIContext を作成してください。詳しくはPython APIを参照してください。

ファイルの場所

重要： すべてのテストファイルは、スキルのディレクトリを基準とするのではなく、リポジトリのルートに保存されます。

ファイルの種類	パス
正解データ	{repo_root}/.test/skills/{skill-name}/ground_truth.yaml
候補	{repo_root}/.test/skills/{skill-name}/candidates.yaml
マニフェスト	{repo_root}/.test/skills/{skill-name}/manifest.yaml
ルーティングテスト	{repo_root}/.test/skills/_routing/ground_truth.yaml
ベースライン	{repo_root}/.test/baselines/{skill-name}/baseline.yaml

たとえば、このリポジトリで databricks-spark-declarative-pipelines をテストする場合：

/Users/.../ai-dev-kit/.test/skills/databricks-spark-declarative-pipelines/ground_truth.yaml

スキル定義を基準にするのではありません：

/Users/.../ai-dev-kit/.claude/skills/skill-test/skills/...  # WRONG

ディレクトリ構成

.test/                          # At REPOSITORY ROOT (not skill directory)
├── pyproject.toml              # Package config (pip install -e ".test/")
├── README.md                   # Contributor documentation
├── SKILL.md                    # Source of truth (synced to .claude/skills/)
├── install_skill_test.sh       # Sync script
├── scripts/                    # Wrapper scripts
│   ├── _common.py              # Shared utilities
│   ├── run_eval.py
│   ├── regression.py
│   ├── init_skill.py
│   ├── add.py
│   ├── baseline.py
│   ├── mlflow_eval.py
│   ├── routing_eval.py
│   ├── trace_eval.py           # Trace evaluation
│   ├── list_traces.py          # List available traces
│   ├── scorers.py
│   ├── scorers_update.py
│   └── sync.py
├── src/
│   └── skill_test/             # Python package
│       ├── cli/                # CLI commands module
│       ├── fixtures/           # Test fixture setup
│       ├── scorers/            # Evaluation scorers
│       ├── grp/                # Generate-Review-Promote pipeline
│       └── runners/            # Evaluation runners
├── skills/                     # Per-skill test definitions
│   ├── _routing/               # Routing test cases
│   └── {skill-name}/           # Skill-specific tests
│       ├── ground_truth.yaml
│       ├── candidates.yaml
│       └── manifest.yaml
├── tests/                      # Unit tests
├── references/                 # Documentation references
└── baselines/                  # Regression baselines

参考資料

• スコアラー - 利用可能なスコアラーと品質ゲート
• YAML スキーマ - マニフェストと正解データの形式
• Python API - プログラムによる使用例
• ワークフロー - 詳細なワークフロー例
• トレース評価 - セッショントレースの分析