Claude が出した『Agent Skills』、r/LocalLLaMA は1ヶ月前に正準4本を書いていた

skill はもう一般用語。ローカル版は別物。

Claude の「Agent Skills」ドキュメントが今春公開されてから、用語が一気に広まった。Google Trends の Claude skill は先週時点で 100 点満点中 88.5。Anthropic・Microsoft・OpenAI・VS Code、それに複数の "agent skill library" リポが SERP を奪い合っている。

その裏で、r/LocalLLaMA では1ヶ月ほど前から skill ファイルがひっそりと交換されてきた。Anthropic 版とは姿が違う。短く、制約がきつく、そして Opus のようにパターンを内在化していないモデル ── Qwen3.6 27B、Gemma 4 26B、issue 10 の scaffold-first ツールが想定するサイズのモデル ── 向けに書かれている。

issue 10 の最後で「次は正準 skill ライブラリ」と予告した。今回がそれだ。直近 30 日で最も信号が強かった r/LocalLLaMA スレッドから抽出した4本の skill ファイルと、どのモデル × VRAM ティアにどれが効くかの対応表。

なぜローカルモデルは cloud 以上に skill ファイルを必要とするのか

クラウドモデルは公開コードを十分食ってきたので、「関数を書く前にテストを書く」のような pattern を重みの中に内在化している。Sonnet に refactor を頼めば、plan-then-execute のループはある程度自動で回る。

70B 未満のローカルモデルはそれを内在化していない。12 ステップの refactor の1ターン目から喜んでコードを書き始める。3メッセージ前に出した制約を忘れる。プロンプトに固定しなければ、存在しない依存を生成する。

skill ファイルは、ワークフローを各セッションで明示的に再宣言することでこれを解決する。フェーズ、禁止事項、決定的な実行形状 ── すべて文面に書く。覚えなくていい形にする。Anthropic は Opus 相手でも有効だと気づいた。Qwen3.6 27B では「実用 daily driver」と「イラつくおもちゃ」の差になる。

下の4本はすべて同じ形を共有している：

---
name: <slug>
description: <この skill を起動する場面>
---

# <タイトル>

## Rules
- NEVER ...
- NEVER ...

## Phase 1 — ...
## Phase 2 — ...
...

以上。ツールも callback も SDK もない。scaffold が各タスクの開始時に読む markdown ファイル。それだけ。

1. plan-first ── 全員がそれぞれ再発見した1本

出典：r/LocalLLaMA 1stjwg5 256 upvotes / 106 コメント。投稿者 SoAp9035 が PI Coding Agent + Qwen3.6 35B-A3B Q4_K_XL を、この skill ファイル付きで実プロダクションのチケットに1ヶ月使い続けた記録。コメント欄での再現報告がやたら多い。

ファイル本文（著者の構造を踏襲。価値は文章ではなくルールセット側にある）：

---
name: plan-first
description: あらゆるコーディング作業のための構造化された計画ワークフロー。新機能・バグ修正・refactor・実装依頼の起点で必ず使う。プロジェクトを解析 → 最大 5 個まで確認質問 → TODO.md を作成 → ユーザー承認 → タスクを 1 つずつ実行。承認前にコードは書かない。
---

# Plan-First Workflow

## Rules
- TODO.md が承認される前に、コードを書く / ファイルを作る / コマンドを走らせる、をしない。
- 欠けている情報を仮定しない。質問する。
- ステップを飛ばさない。フェーズの順序通りに進める。
- 計画から外れない。新作業が見つかったら TODO.md に追記して承認を取る。

## Phase 1 — プロジェクトを解析
無言で読む。確認対象：ディレクトリ構造（上 2 階層）、該当マニフェスト（`package.json` / `go.mod` / `pubspec.yaml` / `Cargo.toml` / ...）、既存依存とバージョン、ビルドスクリプト、README、既存の TODO.md や open issue。

## Phase 2 — 確認質問（1 ラウンドのみ、5 個まで）
解析後、正しく実装するためにブロックになるギャップを特定。1 メッセージ内で最大 5 個まで、番号付きで聞く。コードベースから推測できることは聞かない。

## Phase 3 — TODO.md を作成
プロジェクトルートに TODO.md を書く。Goal（1 文）、Tasks（フェーズごとにグループ化、小さく独立検証可能、依存順）、Notes（制約 / リスク）。書いたら全文を表示して「この計画で合っていますか？ YES なら開始、変更があれば指示を」と尋ねる。

## Phase 4 — 修正ループ
ユーザーが変更を求めたら、的を絞った追加質問 → TODO.md 再生成 → 再表示 → 承認まで繰り返す。

## Phase 5 — 実行
タスクを順序通り 1 つずつ。完了後 `- [ ]` を `- [x]` に書き換える。開始前に「これからタスク X を始める」と宣言する。リストにない作業が必要になったら停止し `## Discovered Tasks` に追記、承認を取ってから進む。全部 `[x]` になったら「TODO.md のタスクはすべて完了しました」と書く。

なぜ小さいモデルで効くか：すべての遷移がモデルが次ターンで参照できるファイル書き込みで gate されている。モデルに「計画を覚えておけ」と要求しない。計画はディスク上にある。質問 5 個の上限は、小さいモデルが過剰質問でストールする失敗モードを止める。

2. test-first ── 「LLM よりコンパイラの方が信頼できる」派のワークフロー

これは単独スレッドではなく、繰り返し浮上するパターン：1th5t1b（"favorite Agentic Coding Harness" 62）、1thnnjs（pacman ベンチマーク 48）、それに issue 10 で扱った SmallCode の "improvement loop"。要点：小さいモデルは テストを先に固定し、実装をテストに対して回す と明らかにうまく書く。

---
name: test-first
description: 小さなローカルモデル向けの反復的テスト駆動ワークフロー。検証可能な成功基準がある振る舞いの変更に使う。失敗するテストを先に書く → 期待通りの理由で失敗することを確認 → テストが通るまで実装を反復、ただし試行回数の上限あり。
---

# Test-First Workflow

## Rules
- 失敗するテストが存在し走らせるまで、実装を書かない。
- テストを通すためにテストを書き換えない。テストが間違っているなら停止して尋ねる。
- 1 つのテストに対する実装試行は 5 回まで。5 回失敗したらタスクを分解して指示を求める。

## Phase 1 — テストハーネスを探す / 作る
プロジェクトのテストランナー（`pytest` / `go test` / `npm test` / `cargo test` / ...）を特定。なければ追加前にユーザーに確認。今回の変更に最も近い既存テストファイルを特定。

## Phase 2 — 失敗するテストを書く
テストが何の振る舞いを検証するか 1 文で言う。最小のテストを書く。走らせる。**失敗すること**と**期待通りの理由で失敗していること**（import エラー・構文エラーではない）を確認。失敗メッセージを原文で報告。

## Phase 3 — テストに対して実装する
最小の変更でテストを通す。走らせる。通れば Phase 4 へ。通らなければログ：試行 N/5、失敗の差分、次の仮説。繰り返す。試行 5 が失敗したら停止して分解案を出す：「このタスクは A / B / C に分けるべき。どれから着手しますか？」

## Phase 4 — 回帰確認
全テストスイート（または該当する最小スコープ）を走らせる。それまで通っていたテストが落ちていたら、停止して報告 ── 自動修正しない。

## Phase 5 — 報告
出力：追加したテスト、実装の diff、テスト実行結果、回帰チェック結果。commit はしない、ユーザーにレビューさせる。

なぜ小さいモデルで効くか：実装がモデル自身が生成していない 2 値信号で縛られる。「もっともらしいから完了」という失敗モードの余地がない。試行 5 回上限は、7B 級モデルで本当に起きる無限ループ死を防ぐ。

3. refactor-with-constraint ── 「未来は架空」バグを潰す skill

出典シグナル：r/LocalLLaMA 1tcrrfq 100 upvotes ── Gemma 4 26B が本物の 2026 年のニュースを「架空」と自信満々に分類する。学習カットオフを超えているため。スレッドが収束した解決策：日付やプロジェクト事実を ground truth としてシステムプロンプトに注入する。これを skill に一般化すると、refactor の最頻発失敗 ── 存在しない依存・API・「現代のベストプラクティス」を勝手に持ち込む ── を防ぐ規律になる。

---
name: refactor-with-constraint
description: モデルが推測できない事実を固定する refactor ワークフロー。モデルが依存・API・言語バージョン・「現在のベストプラクティス」を勝手に発明しそうな、既存コードの変更に使う。ファイルに触れる前に project ground truth をロードする。
---

# Refactor-With-Constraint Workflow

## Rules
- このプロジェクトに存在することを確認していない API・パッケージ・言語機能を使わない。
- 単に「新しい」という理由で「モダンな」パターンを持ち込まない。ユーザーが明示的にモダン化を求めない限り、コードベース既存のスタイルに合わせる。
- 現在の日付やドキュメントの新鮮さを仮定しない。ground truth はモデルの prior ではなくプロジェクトファイルから来る。

## Phase 1 — Ground Truth をロード
読んで報告：(a) システム上の今日の日付、(b) マニフェストでピンされた言語バージョン、(c) 直接依存トップ 10 とピンバージョン、(d) ある場合は lint / formatter 設定、(e) `.editorconfig` やスタイルガイド。これがセッション残り全体の制約ブロックになる。

## Phase 2 — Refactor のスコープを切る
1 段落で記述：何を refactor するか、なぜ、何が **スコープ外** か。触るファイルを列挙。それぞれ全文を読む。変更する関数の呼び出し箇所を読む。

## Phase 3 — diff を提案（まだ書き込まない）
提案 diff を unified patch で出力。重要な変更それぞれに注釈：Phase 1 のどの制約を尊重しているか（または制約を緩める必要があるなら理由）。「このパッチを適用しますか？」と尋ねる。

## Phase 4 — 適用と検証
ユーザー承認で適用。その後：build、lint、触れたコードを動かす最小のテストサブセットを走らせる。それぞれを個別に報告。

## Phase 5 — 失敗時のロールバック
build か lint が落ちたら、修正を試みない。パッチを revert、何が落ちたか要約、指示を求める。

なぜ小さいモデルで効くか：変更提案の前に プロジェクトを読ませる ことを強制する。7B〜30B モデルがコードベース実態ではなく学習データの「モダン Go」「モダン React」にパターンマッチしてしまう失敗モードを潰す。失敗時の強制ロールバックは「修正の修正の修正」スパイラルを防ぐ。

4. debug-loop ── context に収まらないタスク向け

出典：r/LocalLLaMA 1tftaaa DeltaSqueezer 投稿 144 upvotes ── Qwen3.5 9B + 構造化ワークフロー + map-reduce + 並列実行 + checkpoint / recovery。著者の決め台詞：「自作エージェントが Claude Code を 99% のタスクで置き換えた」。同じ思想を skill 形式に：

---
name: debug-loop
description: context 制限のあるローカルモデル向けの境界付きデバッグワークフロー。コンテキストウィンドウを超えるスコープのバグ（複数ファイル探索、長いログ、巨大データセット）に使う。調査をチャンクに分割、反復間で状態をディスクに永続化、ハードな反復上限で停止。
---

# Debug-Loop Workflow

## Rules
- 作業 context に同時に保持するのは 1 ファイル / 1 ログチャンクのみ。
- 確認なしで 10 反復を超えない。
- 反復間で発見を捨てない。即座に `DEBUG.md` に書く。

## Phase 1 — バグを定義
`DEBUG.md` に書く：Symptom（観測可能な振る舞い）、Expected（あるべき振る舞い）、Reproduction（正確な手順か入力）、Hypotheses（番号付きリスト、小さい順）。

## Phase 2 — 反復
各反復 N（最大 10）：
1. `DEBUG.md` から最小の未検証仮説を選ぶ。
2. それを確証 / 否定できる単一のファイル・関数・ログ片を特定。
3. その片だけを読む。最小のプローブ（1 テスト、1 ログクエリ、1 print）だけ走らせる。
4. `DEBUG.md` の `## Iteration N` に追記：検証した仮説、見つけた証拠、結論（確証 / 否定 / 不明）、次の仮説。

## Phase 3 — 3 反復ごとに checkpoint
反復 3、6、9 の後：調査の現状を `DEBUG.md` 末尾に 5 行で要約し、「続行 / 方向転換 ？」と尋ねる。

## Phase 4 — 解決か分解
仮説が確証され修正が 3 行以内なら：diff を提案、適用前に確認。修正がそれより大きい、または根本原因が別所にあるなら：停止、より小さなバグへの分解を出力、実際の修正は `plan-first` に渡す。

なぜ小さいモデルで効くか：作業 context が境界付きになる ── 1 片、1 プローブ、1 追記。モデルが大きなファイルを頭の中でジャグリングする必要がない。発見はディスクに残るのでセッションが切れても調査を再開できる。ハードキャップは、午後の GPU 時間をまるごと食い潰す「ウサギの穴」失敗モードを防ぐ。

互換マトリクス

どの skill がどのモデル × タスク形状で投資する価値があるか：

Skill	最低モデル	最低 VRAM	最適なタスク形状	スキップ条件
plan-first	Qwen3.6 27B / Gemma 4 26B	24GB	新機能・refactor・複数ファイル修正	単一ファイル 1 行の変更
test-first	Qwen3.6 27B / 35B-A3B	24GB	明確なテスト境界を持つ振る舞い変更	テストランナーがまだ無い
refactor-with-constraint	Qwen3.6 27B+	24GB	既存コードの変更、バージョン感応な API	グリーンフィールド、既存コード無し
debug-loop	Qwen3.6 27B+	24GB	1 ファイル / 1 ログを超えるスコープのバグ	場所と行が既に判っている

8GB 帯（SmallCode 内の Gemma 4 4B）は plan-first と debug-loop までなら動く。refactor-with-constraint は context window に対してプロジェクト読み込みが重すぎる。小型 GPU は最初の 2 本に絞る。

各 scaffold へのインストール

• SmallCode ── ~/.smallcode/skills/ にファイルを置き、プロンプトで名前指定：「use the plan-first skill」。名前が一致すれば SmallCode が自動注入。
• PI Coding Agent ── 同じ思想で ~/.pi/skills/ ディレクトリ。SoAp9035 のスレッドが示す通り、ファイル形式はそのまま動く。
• little-coder ── skill はエージェントのシステムプロンプト routing table に入れる。README が文書化している routing policy ファイルで「タスク形状 → skill」を mapping。
• 汎用（システムプロンプトを読むエージェント全般） ── 該当 skill ファイルを手でシステムプロンプト先頭に連結する。雑だが動く。

今週末にやること

1. plan-first を今日中にローカルエージェントへコピー。 今週で最も投資対効果が高い 10 分。
2. backlog から実チケットを 1 件選ぶ。plan-first 経由でエンドツーエンドに走らせる。小さいモデルが破綻したポイントを記録 ── そこが次の skill が入る場所。
3. plan-first が回るようになったら次は test-first。複合効果が本物：同じ Qwen3.6 27B が両方入れた状態で目に見えてタスクを通すようになる。
4. runlocal.dev カリキュレーターで VRAM 余裕を確認 ── skill ファイル自体は VRAM コストを変えないが、ぎりぎりで動かしている場合は MTP オーバーヘッドで足が出ることがある。

Japan corner：Hermes ルーターの中の skill

JP コミュニティで人気の Hermes Agent + Kiro CLI 構成は、どのタスクにどのモデルを発火させるか を routing 問題として扱う。skill ファイルはその 1 つ下の階層の同じ思想：どのタスクにどのワークフロー形状を発火させるか。自然な統合形は、ルーターが引く skill registry。Hermes 深掘り回でちゃんと扱うが、すでにこのスタックの人は、上の正準 4 本がそのままルーターの per-route system prompt スロットに刺さる。

今週を超える意味

2026 年ここまでの流れ：

1. Q1：モデルが十分良くなった（Qwen3.6、Gemma 4）。
2. 春：MTP + llama.cpp で十分速くなった。
3. 今：scaffold-first ツールで 実用 になった（issue 10）。

足りないピースは 持ち運べるワークフロー形状 ── scaffold をまたぎ、モデル交換にも耐える skill ファイル。Anthropic はフォーマットの価値を確定した。r/LocalLLaMA は荷重 4 本がどれかを確定した。

直近 60 日の観察点：

• コミュニティキュレーションの awesome-local-llm-skills リポは誰が出すか。需要はある ── SERP Claude skill local LLM 1 位がフォーラム、4 位が awesome-llm-skills GitHub。だが 小さいモデル特化 の正準セットはまだパッケージ化されていない。
• PI Coding Agent と SmallCode のどちらが先に内蔵 skill registry を出すか。先に出した方がロックインする。
• skill 選択をモデルルーター（Hermes 流）に配線する人は誰か。それが次の自然な抽象化。

ローカルスタックで daily driver 資格を取った 5 本目の skill を書いたら送ってほしい。コミュニティキュレーション分は後のイシューで紹介する。

次回：routing パターン ── Hermes Agent がどのタスクにどのモデルを発火させているか、skill + router を統合した設定はどんな形か。