はじめに
GitHub で 205k スターを集める affaan-m/ECC は、Claude Code・Codex・Cursor などのエージェントハーネスを横断する「ハーネス性能最適化システム」です。公称 63 agents / 249 skills / 79 legacy command shims という規模ですが、数字だけ眺めても使い方は見えてきません。
本記事では、ECC のスキルの中から代表的な3つ（search-first / continuous-learning-v2 / strategic-compact）の SKILL.md を実際に読み解き、スキルがどういう構造で書かれているかと、導入後にどう日常運用するかを整理します。
- この記事で分かること: ECC スキルの定義構造、主要スキル3つの動作原理、選定・学習・コンテキスト管理という3つの運用ルーチン
- 対象読者: Claude Code でスキルやフックを使い始めていて、「設定を入れた後の運用」を設計したいエンジニア
- 前提知識: Claude Code の基本操作（スラッシュコマンド、フック、コンテキストウィンドウの概念）
なお、本記事はリポジトリの README と各 SKILL.md（v2.0.0-rc.1 時点）を一次情報として読み解いたものです。
背景：なぜ「スキルの運用」が問題になるのか
ECC は「Skills are the primary workflow surface（スキルが主要なワークフロー面）」と明言しており、スラッシュコマンドは互換層、古いものは legacy-command-shims/ に退避という整理です。つまり ECC を導入するということは、実質的に249個のスキル群とどう付き合うかを決めることになります。
ここで問題になるのが次の2点です。
- 選定の問題: 全部入れるとコンテキストを圧迫する。README には「MCP サーバーの入れすぎで 200k のコンテキストが実質 70k まで減る」という注意があり、MCP は10個以下・アクティブツール80個以下という目安が示されています
- 運用の問題: スキルは入れて終わりではなく、セッションからの学習・コンテキストの圧縮・状態の引き継ぎといった日々のルーチンとセットで初めて機能します
この2点を、実際のスキル定義から逆算して見ていきます。
ECC スキルの解剖学：SKILL.md の構造
ECC のスキルはすべて frontmatter 付き Markdown（SKILL.md）で定義されます。search-first の冒頭はこうなっています。
---
name: search-first
description: Research-before-coding workflow. Search for existing tools,
libraries, and patterns before writing custom code.
origin: ECC
---
本文は概ね次のセクションで構成されており、これは自作スキルのテンプレートとしてそのまま流用できる形です。
| セクション | 役割 |
|---|---|
| When to Activate / Trigger | スキルが発火すべき状況の列挙 |
| Workflow | 手順のステップ定義（図解付きが多い） |
| Decision Matrix | 判断基準の表（採用/拡張/自作など） |
| Examples | 入力→判断→結果の具体例 |
| Anti-Patterns | やってはいけないことの明示 |
特に Trigger（いつ使うか）と Anti-Patterns（何をしないか）を必ず書くスタイルは重要です。スキルの発火は LLM の判断に依存する確率的なものなので、発火条件を具体的な状況の列挙で書くほど安定します。
主要スキル解説①：search-first — 書く前に調べさせる
search-first は「コードを書く前に既存解を調べる」を強制するワークフローです。手順は、ツール可用性の事前確認 → 要求分析 → 並列調査（npm/PyPI・MCP・GitHub/Web）→ 評価 → 判断 → 実装、と進みます。
面白いのは判断が4択の Decision Matrix になっている点です。
| シグナル | アクション |
|---|---|
| 完全一致・保守良好・MIT/Apache | Adopt（そのまま採用） |
| 部分一致・土台として良い | Extend（薄いラッパーを書く） |
| 弱い候補が複数 | Compose（2〜3個の小パッケージを組み合わせる） |
| 適切なものなし | Build（調査結果を踏まえて自作） |
Anti-Patterns には「検索チャネルが使えなかったのに『見つからなかった』と報告する（Silent skipping）」が挙げられており、エージェントの調査品質で実際に起きがちな問題を押さえています。筆者もユーティリティを書かせる前にこの4択を意識させるだけで、車輪の再発明がかなり減ると感じています。
主要スキル解説②：continuous-learning-v2 — instinct という学習単位
ECC で最も独創的なのが instinct（勘所）ベースの継続学習です。フックで全ツール呼び出しを観測し、バックグラウンドの観測エージェント（Haiku）がパターンを検出して、確信度スコア付きの instinct として蓄積します。
---
id: prefer-functional-style
trigger: "when writing new functions"
confidence: 0.7
domain: "code-style"
scope: project
---
設計上のポイントは3つあります。
1. 観測はスキルではなくフックで行う。 v1 はスキルで観測していましたが、スキルの発火は50〜80%程度と確率的です。フックは100%決定的に発火するため、v2 では観測をフックに移しています。「確実に実行したい処理はスキルではなくフックに置く」という使い分けは、ECC 以外のハーネス設計でも通用する原則です。
2. v2.1 でプロジェクトスコープが入った。 React の流儀が Python プロジェクトに漏れる「クロスプロジェクト汚染」を防ぐため、instinct は git remote URL のハッシュでプロジェクト単位に隔離されます。「入力検証は必ずやる」のような普遍的パターンだけがグローバルに昇格します。
3. 確信度が運用の軸になる。 0.3（暫定）から 0.9（ほぼ確実）まで、観測の繰り返しで上がり、ユーザーの訂正で下がります。0.7 以上で自動適用という閾値設計です。
主要スキル解説③：strategic-compact — 圧縮のタイミングを設計する
長いセッションで自動コンパクション（auto-compaction）がタスクの途中に走り、文脈が飛んだ経験は多くの人にあるはずです。strategic-compact は「論理的な区切りで手動 /compact する」ことを促すスキルで、フックがツール呼び出し回数を数えて閾値（デフォルト50回）で提案します。
判断基準の表が実用的です。
| フェーズ遷移 | 圧縮する？ | 理由 |
|---|---|---|
| 調査 → 計画 | する | 調査コンテキストは嵩張る。計画が蒸留された成果物 |
| 計画 → 実装 | する | 計画はファイルにあるので、コードのために空ける |
| 実装の途中 | しない | 変数名・ファイルパス・途中状態を失うコストが大きい |
| 失敗したアプローチの後 | する | 袋小路の推論を消してから次の手を打つ |
「何が圧縮を生き残るか」も明示されています。CLAUDE.md・タスクリスト・メモリファイル・git 状態・ディスク上のファイルは残り、中間推論・読んだファイル内容・口頭で伝えた細かい好みは消えます。だからこそ「圧縮の前にファイルへ書き出す」が鉄則になります。
日常運用の組み立て方
ここからは、上記のスキル群を前提にした運用ルーチンを3つに分けて整理します。
ルーチン1：選定 — 全部入れずに相談して絞る
ECC には同梱のアドバイザー CLI があり、欲しい能力を自然文で聞くと該当コンポーネントと選択的インストールのコマンドを返してくれます。
# どのコンポーネントが必要か相談
npx ecc consult "security reviews" --target claude
# 最小プロファイル + 必要な能力だけ追加
npx ecc install --profile minimal --target claude --with capability:machine-learning
インストール経路はプラグイン（/plugin install ecc@ecc）か手動インストーラのどちらか一方だけを使い、混ぜないのが大原則です（混在は重複登録の最頻出原因です）。
ルーチン2：学習 — instinct のライフサイクルを回す
continuous-learning-v2 を有効にしたら、定期的に次のコマンドで学習結果を棚卸しします。
/instinct-status # 学習済み instinct を確信度付きで確認
/evolve # 関連 instinct をクラスタリングしてスキル化を提案
/promote # 2プロジェクト以上・確信度0.8以上をグローバル昇格
/instinct-export # チーム共有用にエクスポート
筆者が良い設計だと思うのは、エクスポートできるのは instinct（パターン）だけで、生の観測ログやコード内容は共有されない点です。チームでの知見共有とプライバシーの線引きが明確です。
ルーチン3：コンテキスト管理 — フックの強度を環境変数で調整
フックの挙動はファイルを編集せずランタイムで制御できます。
# フックの厳格さ（minimal / standard / strict）
export ECC_HOOK_PROFILE=standard
# 特定フックだけ無効化
export ECC_DISABLED_HOOKS="pre:bash:tmux-reminder,post:edit:typecheck"
# セッション開始時に注入する追加コンテキストの上限
export ECC_SESSION_START_MAX_CHARS=4000
さらに v2.0.0-rc.1 では運用状態のスナップショット機能が入り、セッション・スキル実行の健全性・保留イベントを Markdown で書き出して引き継ぎに使えます。
ecc status --markdown --write status.md # 状態を引き継ぎ用に書き出し
ecc status --exit-code # CI で readiness を検査
「エージェントの状態を人間に引き継ぐ」ところまで運用に含めている点は、個人利用を超えてチーム運用を見据えた設計だと言えます。
ハマりどころ
-
プラグイン導入後に observe.sh を settings.json へ手動コピーしない: Claude Code v2.1+ はプラグインの hooks.json を自動ロードするため、二重実行と
${CLAUDE_PLUGIN_ROOT}解決エラーの原因になります -
学習データの置き場所が
~/.claudeの外にある: instinct のデータは~/.local/share/ecc-homunculus/（XDG 準拠）に置かれます。Claude Code のセンシティブパスガードがバックグラウンド書き込みをブロックしないための配置で、旧~/.claude/homunculusからは移行スクリプトが用意されています -
観測エージェントはデフォルト無効:
config.jsonのobserver.enabledはfalseが初期値です。入れただけでは学習は始まりません - スキルの発火は確率的: 確実に実行したい処理（観測・検証・状態保存）はフックに置き、判断を伴うワークフローをスキルに置く、という役割分担を崩さないことです
まとめ
ECC のスキル群を読み解くと、「Trigger と Anti-Patterns を明示するスキル定義」「確実性が必要な処理はフック、判断はスキル」「圧縮・学習・引き継ぎをルーチン化する」という、リポジトリの規模に関係なく持ち帰れる設計原則が見えてきます。
249 スキルは全部入れるカタログではありません。ecc consult で必要な分だけ選び、instinct の棚卸しと区切りの良いタイミングでの /compact を日々のルーチンに組み込む——これが筆者の考える現実的な ECC 運用です。まずは本記事で取り上げた3つの SKILL.md を原文で読んでみることをおすすめします。スキル自作の教科書としても十分に元が取れる内容です。