10分のスキルより10時間のスキルが毎回勝る

スキルを書くとは、SKILL.mdファイルをフォルダに置いて終わりにすることだと思っていました。10分で完成。それで問題なかったのですが、同じミスが呼び出しのたびに繰り返されるのを見て、スキルが本当に意図した通りに動いているかどうか確かめる手段がないことに気づきました。

そんなとき、AnthropicでClaude Codeを開発しているエンジニアのThariqが、物事の見方を変える一言を投稿しました。「スキルをうまく使うのも、スキルのうちだ。」

この言葉が刺さったのは、自分が見ていた現実と一致していたからです。手早く作ったマークダウンファイルと、きちんと構成されたスキルフォルダとの差は、理論上だけでなく、実際のアウトプットの質に如実に現れていました。

スキルはファイルではなく、フォルダである

最もよくある誤解は、スキルとはSKILL.mdファイル一枚のことだという考え方です。実際には、スキルとはスクリプト、参照コード、設定ファイル、そしてそれらをまとめるマークダウンファイルを含むフォルダです。

Anthropic社内のアプローチでは、「段階的開示」と呼ばれる手法が使われています。すべてを一つのプロンプトに詰め込む代わりに、Claudeが必要なタイミングで必要な情報だけを読めるようにファイルを配置します。references/api.mdファイルにはオンデマンドで参照する関数シグネチャが格納されています。assets/ディレクトリには出力テンプレートが含まれているため、プロンプトでフォーマットを説明する必要がありません。バリデーションスクリプトによって、Claudeは返答前に自身の出力をテストできます。

skill-creatorリポジトリを開くと、この原則が実践されているのがわかります。agents/、references/、scripts/の各ディレクトリがSKILL.mdと並んで配置されています。スキルを構築するツール自体が、スキルとして作られているのです。

本文よりも「注意点」のほうが重要

Thariqは、スキルにおける「Gotchas（注意点）」セクションを「最も情報密度の高いコンテンツ」と呼んでいます。メインの指示でも、使用例でもなく、注意点が最重要なのです。

これは自分の経験とも一致します。Gotchasセクションなしでスキルを作ったところ、同じエラーを3回連続で踏みました。その失敗パターンを文書化した一行を追加した瞬間、問題は起きなくなりました。

理由はシンプルです。プロンプト本文に書くような内容のほとんどは、Claudeがすでに知っています。TypeScriptの書き方やJSONのフォーマット方法を伝えても、デフォルトで対応できることを繰り返しているに過ぎません。しかし、あなたの固有の状況において「やってはいけないこと」を伝えるのは、本当に新しい情報になります。

Thariqの投稿から、実践的だと感じた原則をいくつか挙げます。自明なことは書かない（冗長な指示はパフォーマンスを低下させる可能性がある）、過度に具体的な手順でClaudeを縛らない（適応力が失われる）、そしてdescriptionフィールドは人間向けのドキュメントではなくClaudeがスキルをいつ起動するかを判断するための入力であることを忘れない。

Skill Creatorが「動いているっぽい」を「検証済み」に変える

2週間前にリリースされたSkill Creatorのアップデートによって、スキルの品質に対する考え方が変わりました。テストプロンプトを定義し、期待される結果を設定することで、スキルが実際に正しい結果を出しているかどうかを検証できます。プロンプトに対するユニットテストです。

何週間も使っていたスキルにevalを追加してみたところ、絶対に通ると思っていた2つのテストケースが即座に失敗しました。修正は小さなものでしたが、適用後には出力の質が目に見えて変わりました。

スキルには2種類あります。Claudeが単独では苦手なことを教える「能力向上スキル」と、チーム固有のワークフローや基準を徹底させる「好み定着スキル」です。前者にはモデルの改善によっていずれ不要になるという自然な賞味期限があります。後者はワークフローが存在する限り価値を持ち続けます。Evalは、能力向上スキルが役目を終えた瞬間を捉えるのに役立ちます。

このツールはベンチマークモードでモデル更新をまたいだ合格率やトークン使用量を追跡でき、テスト中のコンテキスト汚染を防ぐマルチエージェント並列実行にも対応しています。また、スキルあり・なしの出力をブラインドA/B比較するコンパレーターエージェントも含まれています。

複利的なリターン

これまで見てきた何百ものスキル、そして自分が管理している数十のスキルを通じて、一つのパターンが見えてきました。スキルの価値は最初のドラフトではなく、繰り返しの改善から生まれる、ということです。

フォルダ構造はClaudeのコンテキストウィンドウを形成する手段です。Gotchasは自分の失敗を再利用可能な知識に変えます。Evalはその知識が今も有効かどうかを測ります。

SKILL.mdを書くのに10分かかります。実際の失敗からGotchasを加え、evalケースを構築し、バリデーションスクリプトを含めるには、10時間近くかかります。しかしその投資は、スキルが実行されるたびに回収されます。今夜セットアップしてみてください。朝になる頃には、あなたが手を動かさなくてよかった仕事を、すでにこなしているはずです。