improve-ic-skill

IC Skill の改善

IC Skills リポジトリ内の既存のスキルを改善するための、トークン効率の高いワークフローです。基本原則は、まず問題を理解し、変更は的確に行い、変更した箇所だけを検証することです。 Evals は回帰を防ぐための安全網です。毎回自動的に実行するのではなく、必要に応じて選択的に実行してください。

ステップ 0 — 何かに手を付ける前に問題を理解する

ここで必ず停止してください。ユーザーから具体的な問題の説明を受けるまでは、ファイルを読んだり、コマンドを実行したり、変更を加えたりしてはいけません。

次の点を把握する必要があります。

1. 具体的な問題は何ですか？（例：「Canister ID X が古い」「Y についての落とし穴が記載されていない」「Z で説明がトリガーされない」「コード例で非推奨の API W を使用している」）
2. なぜ問題なのですか？（例：「エージェントが動作しないコードを生成する」「このユースケースでスキルがまったくトリガーされない」「アップストリームとの同期で、対象としていない新しいコマンドが追加された」）

依頼が曖昧な場合（「motoko スキルを改善して」「ckbtc スキルがいまひとつ」など）は、次のように尋ねてください。

「どの具体的な問題に取り組めばよいですか？ たとえば、記載されていない落とし穴、古い Canister ID、壊れたコード例、または正しくトリガーされない説明などがあります。」

ユーザーが具体的な問題を提示できない、または提示しない場合は、そこで停止してください。 先に進んではいけません。スキルを読んではいけません。コマンドを実行してはいけません。「自分で調べて改善点を見つける」こともしてはいけません。次のように、はっきり説明してください。

「作業を始める前に、解決すべき具体的な問題が必要です。見当違いの改善は、変更する必要のない箇所を変えてしまうおそれがあります。具体的な問題を見つけるには、npm run validate の実行、evaluations/<skill-name>.json で失敗したケースの確認、または GitHub の issue やアップストリームの diff を提示する方法があります。」

ユーザーが反論したり、同じ曖昧な依頼を繰り返したり、不満を示したりしても、この方針を維持してください。答えは常に同じです。具体的な問題がなければ、作業は開始しません。

唯一の例外は、会話内のコンテキスト（GitHub issue の本文、アップストリームの diff、具体的なエラーメッセージなど）から理由が明白な場合です。その場合は、質問せずにステップ 1 に進んでください。

ステップ 1 — スキルを理解する

skills/<skill-name>/SKILL.md を最後まで読んでください。次の点を確認します。

• 対象としている内容と、対象から漏れている内容
• アップストリームで追跡されているかどうか：grep <skill-name> .claude/upstream.md を実行し、該当する場合は icskills が管理するセクションを確認します（これらはアップストリームの内容で上書きしてはいけません）
• 最近の Git 履歴：git log --oneline -5 -- skills/<skill-name>/SKILL.md

ステップ 2 — ベースラインを検証する

npm run validate

内容を変更する前に、エラーを修正してください。警告は許容できます。改善に関係する場合を除き、警告への対処は不要です。

ステップ 3 — 改善点を特定する

新鮮な目で読み直してください。特に効果の高い一般的な改善点は次のとおりです。

落とし穴 — 最も価値の高い内容です。記録された落とし穴は、それぞれエージェントのハルシネーションを防ぎます。よくある誤った使用パターン、エージェントが読み違えがちなエラーメッセージ、誤ったデフォルト値、API の注意点を探してください。

Canister ID とバージョン番号 — メインネットと現在のリリースタグに照らして確認してください。古い ID は、エージェントが生成したコードを気付かれないまま壊します。

コード例 — 構文がコンパイルできること、API が現存すること、非推奨のパターンを使っていないことを確認してください。

説明 — 何をするか、いつ使うか、そしていつ使わないかを明記する必要があります。エージェントが照合する具体的なキーワードを含めてください。説明が弱いと、スキルはまったくトリガーされません。

必須の frontmatter — CI では metadata.title と metadata.category が必須です。これらが欠けていると、デプロイがブロックされます。

アップストリームで追跡されているスキル（writing-motoko、migrating-motoko-actors、troubleshooting-motoko-migrations、reviewing-motoko、mops-cli、static-site）については、.claude/upstream.md を注意深く読んでください。icskills が管理するセクションのみを自由に変更してください。共有コンテンツを変更する場合は、アップストリームにも変更を提出してください。

ステップ 4 — 改善を適用する

skills/<skill-name>/SKILL.md を編集してください。依頼されていない箇所はリファクタリングせず、対象に集中してください。

ステップ 5 — 再度検証する

npm run validate

エラーは修正してください。無関係なセクションの警告は、そのままにして構いません。

変更が大規模な場合は、必要に応じて LLM の品質スコアリングを実行してください。

skill-validator score evaluate --provider claude-cli skills/<skill-name>

ステップ 6 — 評価を確認して更新する

リポジトリのルートにある evaluations/<skill-name>.json を開きます（スキルディレクトリの中ではありません）。

ファイルがまだ存在しない場合は、この改善作業の一環として作成します。スキルを改善するタイミングは、最初の評価を用意するのに適しています。まずは必要最小限にします。最も重要な落とし穴を対象とする output_evals を 1～2 件、説明文を対象とする trigger_evals を 2～3 件用意します。網羅的にしようとする必要はありません。小規模で正確な評価ファイルは、実行されない大規模な評価ファイルより優れています。

評価ファイルが存在しない上流同期作業では、上流の差分から直接ケースを用意します。差分内の新しいコマンド、変更されたデフォルト値、名称変更された API、新しい落とし穴は、ガイダンスを更新しなければエージェントがまさに誤った内容を生成しやすい部分です。差分が最適な情報源です。

# Verify no eval file exists
ls evaluations/<skill-name>.json 2>/dev/null || echo "No evals yet — create them"

ファイルが存在する場合は、変更内容と照らし合わせて既存のケースを確認します。

次の場合は必ず評価を更新します。

• 新しい落とし穴を追加した場合 — 落とし穴は、ガイダンスがなければエージェントが誤った内容を生成しやすい部分です。新しい落とし穴ごとにケースを用意します。
• コマンド、API、または canister ID を変更した結果、既存のケースの説明が誤りになった場合 — ケースを修正します。
• 明示的なガイダンスがなければ、エージェントが誤りやすい新しい動作を導入した場合

評価スイートは必要最小限に保ちます。 明らかな内容や、すでに十分にカバーされている内容についてケースを追加しないでください。各ケースは、実行にトークンを消費する将来の回帰テストになります。

ステップ 7 — 評価を実行する

ここでは別々の作業を 2 つ行います。混同しないでください。

A. 追加または変更したすべてのケースを、ベースラインとともに必ず実行します。 新規または編集した評価ケースは、書いたばかりのコードです。実行することで、スキルで実際にパスすることを確認し、スキルありとベースラインの実際の差を確認できます。実行していないケースは、範囲の設定が適切でない可能性があります。たとえば、「コマンドだけ」と指示するプロンプトに、説明を必要とする期待動作を組み合わせると、スキルありの実行が失敗します。そのままでは、気づかれずに壊れた回帰テストをコミットすることになります。これらの結果を PR に含めます。「追加のみ」の変更であっても、これは必須です。追加のみの変更には新しいケースが含まれ、新しいケースは必ず実行する必要があります。

B. 関連する場合に限り、変更していない既存のケースを再実行します。 既存スイートの残りを再実行するのは、回帰チェックです。「すでにテスト済みの内容を壊していないか」を確認します。次の場合に実行してください。

• 既存の評価で明示的にテストしている内容（canister ID、コマンド名、エラーメッセージ）を変更または削除した場合
• いくつかの既存の評価でカバーされているセクションを書き換えた場合
• 説明文を大幅に変更した場合 — trigger evals のみ実行します
• 変更が安全かどうか判断できない場合

変更した内容がケースの対象と重ならない場合に限り、既存のケースの再実行を省略できます。

実行するものを決める前に、存在する評価を確認します。

node scripts/evaluate-skills.js <skill-name> --list

関連するサブセットのみを実行します。

# Single eval by index (cheapest)
node scripts/evaluate-skills.js <skill-name> --eval <N>

# Trigger evals only — for description changes
node scripts/evaluate-skills.js <skill-name> --triggers-only

# Run a case you added/changed WITH baseline (default) — this is what goes in the PR
node scripts/evaluate-skills.js <skill-name> --eval <N>

# Skip baseline (--no-baseline) only for a quick correctness spot-check, not for PR results
node scripts/evaluate-skills.js <skill-name> --eval <N> --no-baseline

# Full suite — only when you made broad changes across the whole skill
node scripts/evaluate-skills.js <skill-name>

評価の形式に関するリファレンス：

{
  "output_evals": [
    {
      "name": "descriptive name",
      "prompt": "scoped prompt asking for one thing — specify what to exclude to keep it fast",
      "expected_behaviors": [
        "Specific, checkable behavior the model should exhibit",
        "Another specific behavior"
      ]
    }
  ],
  "trigger_evals": [
    {
      "query": "realistic user prompt that should trigger this skill",
      "expected_behavior": "should trigger"
    },
    {
      "query": "realistic prompt that looks similar but should NOT trigger this skill",
      "expected_behavior": "should NOT trigger"
    }
  ]
}

プロンプトの範囲は厳密に設定します。自由回答形式のプロンプトは長い回答を生成し、タイムアウトのリスクがあります。質問は 1 つに絞り、不要な内容は明示的に除外してください（「関数のみ。デプロイ手順は不要」など）。

ステップ 8 — 最終確認

npm run validate

スキルを PR に出せる状態になりました。変更内容の簡潔な概要と、ステップ 7 で評価を実行した場合は、該当する結果を <details> ブロック内に折りたたんで記載してください（正確な形式についてはPR を提出するを参照してください）。

上流で追跡されているスキル

writing-motoko、migrating-motoko-actors、troubleshooting-motoko-migrations、reviewing-motoko、mops-cli、または static-site を編集する前に、.claude/upstream.md を読んでください。各セクションのうち、icskills が所有するものが記載されています。所有するセクションは自由に改善できます。共有コンテンツを改善する場合は、次回の同期で反映されるよう、上流にも issue を提出してください。