custom-skills-ecc-analyze

カスタムスキル — ECC 分析

ECC の配布リストを 2 つのモードで見直します。

• Mode A — 既存リストの整理：現在の distribution.yaml.enabled に重複や品質の問題がないか確認し、enabled_remove を提案します
• Mode B — 新規項目の導入評価：ecc-catalog.yaml と前回の更新範囲に基づき、ECC 上流で追加されたスキルを紹介し、適用シナリオを分析して、enabled に追加する項目を提案します

出力先はどちらも upstream/reports/ です。distribution.yaml は自動変更しません。

Mode の選び方

   ┌──────────────────────────────────────────────────────────┐
   │  使用者問題                            → 觸發 Mode       │
   ├──────────────────────────────────────────────────────────┤
   │  "分析 ECC 清單" / "瘦身 enabled"      → Mode A           │
   │  "上游新增了什麼" / "要不要加 XX"      → Mode B           │
   │  "全面審視 ECC"                        → A + B 都跑      │
   └──────────────────────────────────────────────────────────┘

どちらの Mode も Step 5 の 5 つの品質 bucket とガードレールを共用します。入力（既存リストか新規リストか）と、提案する出力の方向（削除か追加か）が異なります。

---

Mode A — 既存リストの整理

すでに enabled になっているスキルのうち、削除すべきものを特定します。

ワークフロー

┌────────────────────────────────────────────────────────────────────┐
│                  Mode A — Pruning Pipeline                         │
├────────────────────────────────────────────────────────────────────┤
│                                                                    │
│  1. 取集合          2. 標籤本地         3. 過濾 ECC                │
│  ┌──────────┐       ┌──────────┐       ┌──────────┐               │
│  │ enabled  │  ───▶ │ classify │  ───▶ │ keep ECC │               │
│  │ + local  │       │ local    │       │ in scope │               │
│  └──────────┘       │ by role  │       └──────────┘               │
│                     └──────────┘             │                     │
│                                              ▼                     │
│  4. 重疊比對       5. 品質分群         6. 報告                     │
│  ┌──────────┐      ┌──────────┐       ┌──────────┐                │
│  │ pair by  │ ───▶ │ 5 buckets│  ───▶ │ markdown │                │
│  │ purpose  │      │ A-E      │       │ + yaml   │                │
│  └──────────┘      └──────────┘       └──────────┘                │
│                                                                    │
└────────────────────────────────────────────────────────────────────┘

---

Step 1 — 集合の取得

次の 2 つのソースを読み込みます。

# 第一方 skill collection
DISABLE_TELEMETRY=1 npx skills add ValorVie/ai-dev-skills --list

# ECC enabled 清單
uv run python -c "
import yaml
d = yaml.safe_load(open('upstream/distribution.yaml'))
print('\n'.join(d['distribute']['skills']['enabled']))
"

意味的な比較に使用するため、ECC スキルの description も読み込みます。

ECC=~/.config/everything-claude-code/skills
for n in <names>; do
  desc=$(awk '/^description:/{sub(/^description:[ ]*/,""); print; exit}' "$ECC/$n/SKILL.md")
  echo "[ECC] $n :: $desc"
done

description を全文ではなく使用する理由：description はスキルのトリガー条件であり、「使用する状況」を最もよく表しています。重複を判断するには、「いつ使うか」を比較するほうが「実装の詳細」を比較するより確実です。

---

Step 2 — ファーストパーティスキルの役割を分類

役割が同じスキルに限り ECC と重複する可能性があるため、ファーストパーティスキルを役割ごとに分類します。

   個人工具流          → custom-*
   framework workflow  → custom-skills-*
   個人化輸出          → wiki, work-log-*
   思考框架            → first-principles
   領域特化            → cloud-infra-security
   跨 AI 工具          → discuss-multi-ai

work-log-* は内部専用で、ECC と重複することはありません（ECC にはこれらの概念がありません）。Step 4 では残りのグループのみ比較します。

---

Step 3 — ECC を絞り込む

明らかに確認不要な ECC スキルを除外します。

• 既知の「ECC 内部ツール」（ecc-guide、nanoclaw-repl、hermes-imports など）→ Step 5 の品質グループで扱います
• ECC 上流で新たに追加されたばかりで、catalog にまだ収録されていないもの → スキップします（ai-dev ecc audit を実行して処理します）

---

Step 4 — 重複の比較

各ファーストパーティスキルについて、意味的に最も近い ECC スキルを 1～3 個見つけます。

   ┌────────────────────────────────────────┐
   │  第一方 skill X                        │
   │  ↓ 在 ECC enabled 中找語意鄰近候選     │
   │  Y1, Y2, Y3                            │
   │                                        │
   │  針對每個 (X, Yk) 評估：              │
   │  - 觸發條件是否高度重疊？             │
   │  - 輸出產物是否相似？                 │
   │  - 抽象層級是否相同？                 │
   │                                        │
   │  分級：高 / 中 / 低-中 / 低           │
   └────────────────────────────────────────┘

重複の強さの基準：

強さ	基準	推奨アクション
高	トリガー条件が大きく重なり、出力が類似し、抽象度が同じ	弱いほうを enabled_remove に追加
中	トリガー条件が一部重なるが、スコープが異なる	両方を残し、備考を付ける
低～中	領域は近いが、実際の使い方は異なる	残す
低	キーワードは同じでも、本質が異なる	残す

どちらを残すかの判断（競合する場合）：

• ファーストパーティ版のほうが用途に特化しており、汎用版では代替しにくい → ファーストパーティ版を残し、ECC 版を削除
• ECC 版がローカル版では対応していないシナリオを扱える → ECC 版を残し、ローカル版の削除を検討
• 両方に独自の価値がある → 両方を残す（競合なし）

---

Step 5 — 品質グループ分け（5 つの bucket）

ECC の enabled 項目のうち、削除すべき可能性があるものを 5 つのグループに分類します。

A. 明確な deprecated

基準：description に [DEPRECATED]、deprecated、legacy などの語が含まれている。 アクション：必ず削除します。

B. 高度にニッチな言語／フレームワーク

基準：description が特定のフレームワーク／言語に限定され、かつそのフレームワーク／言語が次のいずれかに該当する：

• GitHub の star 数が 1k 未満
• 世界の開発者に占める割合が 1% 未満
• Cisco、Quarkus など、特定地域のツールを示す名前

アクション：その言語／フレームワークを使用しているかユーザーに確認します。使用していない場合は削除します。

C. 学術／研究専用

基準：description に scientific、literature、patent、genomic、scholar などの学術関連の語が含まれている。 アクション：学術研究を行っているかユーザーに確認します。行っていない場合は、グループ全体を削除します。

D. 名前の質が低く、識別しにくい

基準：

• 展開形のない略称（ck など）
• 作者名が付いた名前（santa-method、ralphinho-*）
• 大げさな名前と内容が一致しない（agentic-os の実態は file-memory）
• 説明が、読者は特定の論文を読んでいることを前提としている（文脈が自己完結していない）

アクション：ユーザーが判断できるように一覧にします。トリガーの説明が曖昧で誤って起動しやすいため、デフォルトでは削除する方向で検討します。

E. 価値が境界的／組み込み機能で代替可能

基準：

• Claude Code／プラットフォームの組み込み機能で代替済み（/compact が strategic-compact を代替）
• 1 つの原則をスキル全体にしている（1 行のルールで表現可能）
• ごく限られた状況でのみ起動する（使用確率が 5% 未満）
• 類似スキルが複数あり、互いに重複している（motion-foundations × motion-advanced × motion-patterns × motion-ui）

アクション：「境界的」として、ユーザーが判断できるよう根拠を添えて一覧にします。

---

Step 6 — レポートの出力（Mode A）

出力先：upstream/reports/ecc-skill-analysis-YYYY-MM-DD.md

レポートの構成：

# ECC Skill 分析報告 — 重疊與品質審視

- 日期、分析對象、比對基準、資料來源

## 一、與第一方 skill 的重疊性分析
  ### 第一方 skill 角色拆解（ASCII 圖）
  ### 重疊矩陣（表格：本地 | ECC 候選 | 強度 | 推薦動作 | 理由）
  ### 重疊小結（建議 enabled_remove 的 yaml 片段）

## 二、品質與通用性問題
  ### A. 明確 deprecated（表格）
  ### B. 高度小眾語言/框架（表格 + 移除建議欄）
  ### C. 學術/科研專用（表格）
  ### D. 命名劣質、辨識度低（表格 + 問題說明）
  ### E. 邊界價值 / 可被內建取代（表格 + 為何邊界）

## 三、建議的 ~/.config/ai-dev/ecc-profile.yaml
  （完整可貼入的 yaml，含中文註解分群）

## 四、後續
  - 重新評估週期
  - 觸發指令

yaml ブロックの記述方針：

• コメントを使い、enabled_remove をソースごとに分類します（重複／deprecated／ニッチ／学術／境界的／二者択一）
• 「二者択一」の項目は、ユーザーがコメントを解除できるよう # コメントで記載し、デフォルトでは削除しません
• 配布数の変化（削除前／削除後）を合計して記載します

---

Mode B — 新規項目の導入評価

ECC 上流で新たに追加されたスキルを紹介し、内容と適用シナリオを分析して、導入を提案します。

ワークフロー

┌────────────────────────────────────────────────────────────────────┐
│              Mode B — New Items Review Pipeline                    │
├────────────────────────────────────────────────────────────────────┤
│                                                                    │
│  1. 找新項目          2. 介紹內容        3. 適用度評估             │
│  ┌──────────┐         ┌──────────┐       ┌──────────┐             │
│  │ catalog  │ ───▶    │ read     │ ───▶  │ 通用度   │             │
│  │ diff /   │         │ SKILL.md │       │ 觸發頻率 │             │
│  │ added    │         │ desc +   │       │ 替代性   │             │
│  └──────────┘         │ 30 lines │       └──────────┘             │
│                       └──────────┘             │                   │
│                                                ▼                   │
│  4. 重疊檢查         5. 5 bucket 過濾    6. 三段建議               │
│  ┌──────────┐        ┌──────────┐       ┌──────────┐              │
│  │ 對比本地 │  ───▶  │ A-E 任一 │  ───▶ │ ✅ / ⚠️ / ❌  │            │
│  │ + enabled│        │ → 拒絕   │       │ + 理由   │              │
│  └──────────┘        └──────────┘       └──────────┘              │
│                                                │                   │
│                                                ▼                   │
│                                          7. 報告 +                 │
│                                            enabled patch          │
│                                                                    │
└────────────────────────────────────────────────────────────────────┘

Step 1 — 新規項目を特定

次の 3 つのソースのいずれかを使用できます（状況に応じて選択します）。

方法 A：ai-dev ecc audit を使用

ai-dev ecc audit
# 看 [NEW] 區段：ECC 有但 catalog 沒有的項目

方法 B：catalog の added フィールド

audit によって catalog に uncategorized が追加されている場合は、added >= 前回の評価日 で比較します。

uv run python -c "
import yaml
from datetime import date
last_review = '2026-05-12'   # 上次評估日，或從報告檔名取
cat = yaml.safe_load(open('upstream/ecc-catalog.yaml'))
new_items = []
for cat_key, cat_data in cat['categories'].items():
    for s in cat_data.get('skills') or []:
        added = s.get('added', '') if isinstance(s, dict) else ''
        if added >= last_review:
            new_items.append((cat_key, s['name'], added))
for c, n, a in sorted(new_items, key=lambda x: x[2]):
    print(f'{a}  [{c}]  {n}')
"

方法 C：catalog の変更に関する git log

git log -p upstream/ecc-catalog.yaml | head -200

新規項目の一覧を確認したら、対象範囲と日付 cutoff を記録します。

Step 2 — 各新規項目を紹介

各新規項目の SKILL.md を読み込みます。

ECC=~/.config/everything-claude-code/skills
for n in <new-names>; do
  echo "=== $n ==="
  sed -n '1,40p' "$ECC/$n/SKILL.md"
  echo
done

各新規項目について、次の内容を含む紹介文を作成します：

• 1 行の要約（description から抽出）
• 主な機能（SKILL.md の最初の 30 行から主要な概念を抽出）
• 使用シナリオの例（description の「Use when...」のセクションから抜粋するか、2～3 件を自分でまとめます）

Step 3 — 適用シナリオを評価（4 つの観点）

各項目を 1～3 で採点します。

観点	1（低）	2（中）	3（高）
汎用性	特定のツール／フレームワーク	特定の技術スタック	50% 以上のプロジェクトに適用可能
起動頻度	まれ	月に数回	週に複数回
代替不可能性	プラットフォームに組み込み済み／ローカルに存在	一部をカバー	類似ツールがない
学習コスト	論文を読む／多くの予備知識が必要	中程度	自己完結している

合計点の判定：

• 10～12 点 → 強く推奨
• 7～9 点 → 条件付きで推奨
• 6 点以下 → 推奨しない

これは補助的なフレームワークであり、厳格なルールではありません。description が曖昧なもの（D グループ）や価値が境界的なもの（E グループ）は、評価を 1 段階下げます。

Step 4 — 重複の確認

既存の enabled 項目とローカルの skills/ を比較します。

   新項目 X
   ├─ 與本地某個高度重疊？      → 「換手」或「不導入」
   ├─ 與某個 enabled 高度重疊？  → 「不導入」或「替換掉舊的」
   ├─ 補強某個既有？             → 「同時保留」並備註定位差異
   └─ 完全獨立？                 → 進入下一步

Step 5 — 5 つの品質 bucket によるフィルタリング（Mode A と共用）

いずれかの bucket に該当した場合は、評価を引き下げるか、不採用とします。

• A. Deprecated：description に [DEPRECATED]／legacy が含まれる → 不採用
• B. 高度にニッチな言語／フレームワーク：特定のニッチなフレームワークに限定 → その技術スタックを使用しているか確認
• C. 学術／研究専用：scientific／literature／patent を含む → 学術研究を行っているか確認
• D. 名前の質が低く、識別しにくい：略称が理解しにくい／作者名が付いている／大げさ／読者の予備知識を前提としている → 導入しない（トリガーの説明が曖昧で誤って起動しやすい）
• E. 価値が境界的：組み込み機能で代替済み／1 つの原則をスキル全体にしている／ごく限られた状況のみ → 条件付き、または導入しない

Step 6 — 3 つのカテゴリで提案

各新規項目を、次の 3 つのカテゴリのいずれかに分類します。

✅ 強烈建議導入

• 通用 + 高品質 + 無重疊 + 適用情境清楚
• 直接列入「下次 commit 加進 distribute.skills.enabled」

⚠️ 條件性導入

• 限定情境但有用（例：你寫 Vue 才有用、做 e2e 才有用）
• 列出觸發條件，由使用者判斷
• 提供「若決定導入」的 patch 片段

❌ 不建議導入

• 附原因（小眾 / 重疊 / 品質 bucket 命中）
• 註明可能在未來情境再評估的條件

Step 7 — 報告輸出（Mode B）

輸出位置：upstream/reports/ecc-new-items-review-YYYY-MM-DD.md

報告結構：

# ECC 新項目導入評估 — YYYY-MM-DD

- 上次評估日、本次 cutoff、新項目數量、catalog 版本

## 一、新項目總覽（表格）
| 名稱 | category | added | 通用 | 頻率 | 替代性 | 學習 | 總分 | 建議 |
|------|----------|-------|------|------|--------|------|------|------|

## 二、強烈建議導入（N 個）
  ### <skill-name>
  - 一行摘要
  - 主要功能（2-4 點）
  - 適用情境（2-3 例）
  - 評分理由

## 三、條件性導入（N 個）
  ### <skill-name>
  - 一行摘要 + 觸發條件
  - 「若你 X 才有用」
  - 評分理由

## 四、不建議導入（N 個）
  ### <skill-name>
  - 為何不建議（命中哪個 bucket / 重疊誰）
  - 未來重新評估的條件（若有）

## 五、建議 patch（要加進 distribution.yaml.enabled）

  ```yaml
  # === <category> ===
  - <skill-1>
  - <skill-2>

記得同步更新 category 計數的註解。

六、後續

• 上次評估日更新為本次日期，下次 cutoff 從此處開始

**patch 撰寫原則**：
- 只列「強烈建議」項目（條件性的留給使用者自行加）
- 按 `ecc-catalog.yaml` 的 category 分群
- 標註各 category 預期數量變化

---

# Guardrails（兩個 Mode 共用）

1. **不自動寫 `ecc-profile.yaml` / `distribution.yaml`**：只產報告，最終由使用者決定
2. **不刪除任何檔案**：建議僅以 yaml 片段表達
3. **資料來源以 description 為主**：必要時再讀 SKILL.md 前 30-50 行；避免讀整檔案（成本控制）
4. **每個判斷要有依據**：每個建議都附「為什麼」一句話，否則不列入
5. **新舊不混淆**：Mode A 處理既有 enabled，Mode B 處理新項目；同時跑時也分開報告

---

## 範例輸出

- **Mode A 完整實例**：[`upstream/reports/ecc-skill-analysis-2026-05-12.md`](https://github.com/ValorVie/custom-skills/blob/main/upstream/reports/ecc-skill-analysis-2026-05-12.md)
- Mode B 範例：首次執行後產出於 `upstream/reports/ecc-new-items-review-YYYY-MM-DD.md`