Claude Code の skill-creator で既存 skill を検証してみた

概要

Anthropic が公開している Agent Skills 向けの公式リポジトリです。
サンプル skill の構成や Claude Code からのプラグイン利用の手順などが README にまとまっています。

https://github.com/anthropics/skills

以前作成した zenn-blog-writing の skill をきちんと計測したかったので、Claude Code で使える skill-creator に注目しました。
検証フローを踏まえつつ benchmark で既存 skill の精度がどう見えるか試し、計測してみました。
本記事では、その結果から読み取れる skill の効果と、実際に行った改善までをまとめています。

なぜ検証しようと思ったか

skill を用意すること自体は比較的かんたんです。
一方で「ちゃんと効いているか」を確認する手段が乏しいこともあります。
textlint のようにルールを定義して機械的にパスできるか確認できるわけでもなく、
skill を挟んだ出力の良しあしは主観での判断になりがちでした。
再現できるタスクとスコアで効き具合を押さえたかった、というのが出発点です。

skill-creator とは

そのひとつの手段として、Claude Code には skill-creator という skill が用意されています。

Claude Code の skill（.claude/skills/ 配下の SKILL.md）を作成・改善・評価するための skill です。

主な機能は次の 3 つです。

• 「作成」機能では、要件から新しい skill を生成します。
• 「改善」機能では、既存 skill の記述を精査・修正します。
• 「評価」機能では、eval を実行して skill の有無で品質差を数値化します。

eval は「タスク定義」「期待する出力条件」「採点ロジック」をセットで管理します。
1 回の benchmark で複数の eval を実行し、with / without skill の差分をスコアで比較します。

skill-creator がベンチマーク結果を返すまで

skill-creator を利用すると、一時フォルダにベンチマーク結果が出力され、HTML で確認できる状態になります。
実行ログやレポート画面のイメージは次のとおりです。

検証対象：zenn-blog-writing skill

今回検証した zenn-blog-writing skill は、Zenn の技術記事を書く際のガイドライン集です。

カバーしているのは主に次の内容です。

• frontmatter の形式（topics の記号不可ルールなど）
• 文章品質の基準（文長・能動態・AIっぽい表現の回避）
• コードブロックの言語指定
• textlint チェックとの連携

技術記事を書くたびに自分でルールを思い出すのが面倒だったので作りましたが、
どれだけ出力品質に影響しているかは計測したことがありませんでした。

skill の経緯やプロジェクトでの運用、SKILL.md の構成については次の記事にまとめています。

Zennブログ執筆用のAgent Skillを自作して運用してみた

検証の手順

/skill-creator を呼び出し、benchmark モードで実行します。

# Claude Code の REPL 上で
/skill-creator benchmark zenn-blog-writing

skill-creator が eval タスクを自動生成し、with / without の 2 条件で実行します。
各 eval に採点基準（rubric）が設定されており、スコアが返ってきます。

今回は 2 イテレーション実施しました。
iter-1 の結果から skill を改善し、iter-2 で再計測するという流れです。

iteration-1 の結果

3 つの eval を実行しました。タスクの概要と結果は次のとおりです。

eval	タスク概要	skill あり	skill なし
eval-1	AI表現のレビュー	5/5（100%）	4/5（80%）
eval-2	新規記事の作成	5/6（83.3%）	5/6（83.3%）
eval-3	frontmatter の修正	7/7（100%）	5/7（71.4%）
平均	—	94.4%	77.8%

skill の有無による差は 16.7% でした。
一貫してスコアに差が出ています。

コストは skill ありが約 3300 tokens 多く、処理時間は約 4 秒遅かったです。

どこで差が出たか

eval-1（AI表現レビュー）

唯一落としたのは topics-lowercase でした。
skill なしは ["React", "TypeScript", "JavaScript"] を大文字のまま出力しました。
Zenn は topics に記号やスペースを禁止していますが、大文字／小文字については明示的なエラーになりません。
そのためモデルが「なんとなく正しそう」な表記をそのまま使ってしまったと考えられます。

eval-2（新規記事作成）

スコアは同率ですが、落とした項目が違いました。

skill なしの FAIL は topics に "Node.js" と "GitHub Actions" を使ったことです。
ピリオドとスペースが入っており Zenn に投稿するとエラーになる、実害のある問題でした。

skill ありの FAIL はコードブロックの言語指定漏れです。
ただしこれは skill の設計というより実行コンテキストに近い問題でした。
キャッシュ確認のログを詳しく書こうとした結果、プレーンテキストのブロックが生まれました。
skill にはターミナル出力の言語指定（text / console）が未定義だったため対処できませんでした。
skill なしは短い記事を書いたので偶然 PASS になっただけで、同じ状況になれば同様に漏れると思います。

eval-3（frontmatter 修正）

最も差が出た eval でした。
skill なしは「報告された問題（topics）は直したが、指示されていない細部（emoji と type のクォート）は見落とした」という結果になりました。

# skill なしの出力例（クォートなし）
emoji: 🔧
type: tech

# skill ありの出力例（クォートあり）
emoji: "🔧"
type: "tech"

どちらも YAML としては動きますが、Zenn の公式サンプルはクォートを付けるスタイルを採用しています。
skill の記述に明示的に書いてあったため、skill ありは副次的な修正もカバーしました。

skill の改善（iteration-1 → iteration-2）

iter-1 の結果から次の 3 点を修正しました。

1. frontmatter テンプレートを skill 冒頭に明示

クォートルールが skill の本文に散在していました。
title・emoji・type の 3 フィールドにダブルクォートが必須であることを強調し、
正解テンプレートを skill の冒頭に集約しました。

2. topics 変換パターン表を拡充

GitHub Actions → githubactions、CI/CD → cicd、VS Code → vscode など、
スペース・スラッシュを含む技術名の変換ルールを追加しました。

3. ログ出力のコードブロック言語指定を明記

ターミナル出力・ログ表示には text または console を使うよう追記しました。

iteration-2 の結果

	iter-1 with	iter-2 with	iter-1 without	iter-2 without
総合通過率	94.4%	100%	77.8%	83.3%
eval-1	5/5	5/5	4/5	4/5
eval-2	5/6	6/6	5/6	6/6
eval-3	7/7	7/7	5/7	5/7

skill ありが 全 18 アサーションで満点（100%） を達成しました。

skill なしも Eval 2 が 5/6 → 6/6 に改善しましたが、これは偶然だと捉えています。
iter-2 では topics を正しい形式で書けたものの、Markdown で「重要」を太字にしてコロンで終えるような強調が残存していました。
このアサーションは現 eval の範囲外だったため PASS になりましたが、本来は問題がある出力です。

Eval 1 と Eval 3 は 2 イテレーション連続して同じ項目で落ちました。
「topics の大文字小文字」「emoji・type のクォート」はモデルが自発的に学習するものではなく、
skill に書いてあるからこそ一貫して守られると感じました。

コストは iter-2 で skill ありが約 +3,027 tokens・処理時間が約 +7.4 秒と微増しました（テンプレートと変換表の追記分です）。

2イテレーションを通じた気づき

仮説との照合

• 「frontmatter の形式は skill なしでもある程度は守れる」→ 半分正解です。必須フィールドの有無は守れる一方で、クォートのスタイルや topics の小文字規則は 2 イテレーション連続で見落としました。
• 「AIっぽい表現の回避は skill が明示的に効く」→ 外れでした。AI 表現の排除はどちらもクリアしており、モデルがすでに持っている能力だったと思います。
• 「skill が長いと制約が薄まる可能性がある」→ 今のところ否定的です。テンプレートを冒頭に集約したことで 100% を達成しました。長さより整理の仕方が効いた可能性があります。

skill の価値は「Zenn 固有の慣習を毎回確実に適用する」こと

topics の小文字規則、frontmatter のクォートスタイルは、一般的な Markdown 知識だけでは拾えません。
モデルが「なんとなく正しそう」と判断する表記と、Zenn が要求する表記にはギャップがあります。
このギャップを明文化したのが skill の本質的な価値でした。

benchmark で FAIL の「性質」を区別できる

iter-1 の Eval 2 で skill ありが FAIL した件は「skill のルール漏れ」でした。
skill なしの FAIL は「Zenn 仕様を知らない」問題でした。
スコアが同じ 5/6 でも、対処すべき内容はまったく違います。
benchmark はこの区別を可視化してくれます。

残る改善余地

• topics-lowercase アサーションが Eval 1 without_skill で 2 回連続 FAIL しました。skill の description 最適化でトリガー精度を上げる余地があります。
• 「太字の『重要』にコロンを続ける」パターンが現 eval では検出できていません。no-ai-expressions の検出範囲を拡充する価値があります。

skill の評価を習慣にすることの意味

skill は書いたら終わりではありません。
モデルのバージョンが変われば挙動も変わります。
プロジェクトの要件が変われば、skill に書いてあることが実情とずれることもあります。

benchmark を定期的に走らせる習慣を作ることで、
「なんとなく使っている skill」から「動いているとわかっている skill」に変わります。

コードでいうテストに近い感覚です。
diff を見て何が変わったかを把握するのと同じように、
skill の品質変化も追跡できます。

まとめ

2 イテレーションで skill ありが 94.4% → 100%、skill なしが 77.8% → 83.3% という結果になりました。
両方スコアが上がっていますが、理由が違います。
skill ありは意図的な改善（テンプレート整理、変換表追加）の結果です。
skill なしの改善は eval の確率的なばらつきであり、2 回連続で落としたアサーションは変わっていません。

skill の価値は「モデルが知らないことを教える」より、「Zenn 固有の慣習を毎回確実に適用させる」側にありました。
topics の小文字規則、frontmatter のクォートスタイルは、モデルが自発的に守ることは稀です。
「なんとなく正しそう」な表記と「Zenn が要求する表記」のギャップを埋めるのが skill の仕事だと整理しました。

benchmark は「スコアを出す」ためというより、「FAIL の性質を区別する」ために使うものだと感じました。
スコアが同じでも、なぜ落ちたかが違えば対処も違います。
この区別なしに skill を改善しようとすると、効果のない変更を重ねやすくなります。