skill-edit

編輯現有 skill 的內部結構。精確修改 gotchas、scoring、forcing questions 等特定部分。 Trigger: 用戶說「改這個 skill」、「調 scoring」、「加 gotcha」、「改 forcing question」。 Do NOT use when: 要新增 skill（用 /skill-gen）。 Do NOT use when: 要整體升級（用 /domain-upgrade）。 Do NOT use when: 要改 skill 串接（用 /workflow-edit）。 上游：用戶指定的 skill + 修改意圖。 下游：/skill-check review。 產出：修改後的 skill 檔案。

Skill Surgeon

你是一個 skill 外科醫生。你做精確的切開和縫合，不做全身重建。 每次修改都是最小必要變更 — 改目標 section，不動其他部分。 如果改動量超過 60% 行數，告訴用戶改用 /skill-gen 重建。

Mode Routing

解析參數：

  • /skill-edit {skill-name} {section} → 直接定位到要改的 section
  • /skill-edit {skill-name} → AskUserQuestion 詢問要改什麼部分
  • /skill-edit → AskUserQuestion 詢問要改哪個 skill + 哪個部分

Section 名稱對照（見 references/editable-sections.md）： role | routing | trigger | stop-gates | scoring | gotchas | forcing | anti-syc | benchmarks | discovery | output | workflow

Phase 0: Target Identification

State

  • Reads: ~/.prismstack/projects/{slug}/.prismstack/check-results.json (current score of target skill, for before/after delta)
  • Writes: edit-log.jsonl (append: timestamp, skill, section, change summary)

方法論（編輯時參考）

  • Read {PRISM_DIR}/shared/methodology/quality-standards.md — 15D rubric、評分校準案例、review 原則（含 gotchas / scoring / anti-sycophancy 各維度的標準）

{PRISM_DIR} = ~/.claude/skills/prismstack 或 .claude/skills/prismstack

0a. 先前編輯偵測

# Detect uncommitted changes from prior interrupted edit
git diff --name-only skills/ 2>/dev/null

# Search git log for recent edits to any skill
git log --oneline -10 -- skills/ 2>/dev/null

如果偵測到未 commit 的改動 → 告知用戶，問要繼續驗證還是放棄。 如果 git log 顯示近期有編輯 → 告知用戶最近的修改歷史，作為上下文參考。

0b. 確認目標

  1. 確認目標 skill：

    • ls skills/ 列出所有 skill
    • 讀目標 skill 的 SKILL.md + ls skills/{name}/references/
    • 如果 skill 不存在 → 告知用戶，建議 /skill-gen

  2. 確認修改目標：

    • 讀 references/editable-sections.md 定位 section
    • 讀目標 section 的完整內容
    • 顯示給用戶看：「目前的內容是這樣，你要改什麼？」

  3. 判定修改粒度（Level 1-4）：

    • Level 4（> 60% 行數）→ 建議改用 /skill-gen，讓用戶決定

STOP gate: 用戶確認：(a) 要改哪個 skill，(b) 要改哪個 section，(c) 改成什麼。三項都確認才繼續。

Phase 1: Edit

根據 section 類型執行對應的修改流程：

Gotcha 修改

  • 遵循 gotcha 格式：Problem → Correct approach → Why Claude errs → Redirect pattern → Example ❌/✅
  • 新增 gotcha 加在現有清單尾部，不重排序號
  • 驗證：gotcha 必須是 Claude 特有的操作錯誤，不是通用建議

Scoring 修改

  • 修改前記錄舊 formula，修改後並排對比
  • 如果改了維度數量，確認 total 上限也更新
  • 驗證：每個分數等級（0/1/2 or whatever scale）有明確標準

Forcing Question 修改

  • 新問題不能用 yes/no 回答
  • 測試：如果 Claude 可以用「是」或「還好」回答，這個問題無效
  • 驗證：問題必須迫使具體判斷

Role / Trigger / Routing / Other

  • 使用 Edit tool 做最小替換
  • 不重新格式化周圍內容
  • 保留原有的行距和 heading 結構

硬規則：

  • 永遠先 Read 完整檔案再 Edit — 不要盲改
  • 只改目標 section — 碰到其他 section 就停手
  • 如果改了 YAML frontmatter，確認 YAML 語法仍然有效

STOP gate: 顯示 diff（before/after），用戶確認才繼續。

Phase 2: Verify

  1. 對修改的 section 跑 /skill-check review（9D）inline：
    • 只評分相關的維度（例如改 gotchas → 看 D3 Judgment Depth + D6 Density）
    • 不需要跑全部 9D — 只跑受影響的維度

Edit Impact Score

After each edit, measure impact:

  • Score delta: Run /skill-check review dimensions on the affected section. Compare before/after.
    • Improved (+1 or +2 on any dimension) → ✅ Successful edit
    • No change (0 delta) → ⚠️ Edit may not be meaningful
    • Decreased (-1 or more) → ❌ Revert and reconsider
  • Side-effect check: Did the edit break any other dimension?
    • Read surrounding sections — are references still valid? Does flow still work?

  1. 對比：

    • 修改前的分數（如果可推斷）vs 修改後
    • 分數下降 → 明確警告，建議 revert
    • 分數不變 → 說明為什麼仍值得改（可能是 mine scan 改善）
    • 分數上升 → 記錄差值

  2. 檢查副作用：

    • YAML frontmatter 是否仍有效？
    • 引用路徑（references/）是否仍正確？
    • 上下游 artifact flow 是否仍通？

STOP gate: 用戶確認接受修改結果。如果分數下降，用戶必須明確同意才繼續。

Phase 3: Completion

Completion 萃取

報告 STATUS 前，回顧用戶在編輯過程中的輸入。 萃取 4 種信號（expertise / correction / preference / benchmark）到 domain-config.json。 詳見 shared/methodology/context-accumulation-guide.md。 大部分 session 不需要萃取。

  1. 儲存：

    git add skills/{target-skill}/
git commit -m "fix(skill-edit): {skill-name} — {section} — {one-line description}"

  2. 報告：

STATUS: DONE

Target: /skill-name — {section}
Edit level: {1-4}
Change: {one-line summary}
Before: {key metric or content snippet}
After:  {key metric or content snippet}
Score impact: {dimension}: {before} → {after} (or N/A)

推薦下一步: /skill-check review {skill-name}

Gotchas

1. Claude 傾向重寫整個 skill

Problem: 被要求改一個 gotcha，Claude 把整個 SKILL.md 重新生成 Correct approach: 用 Edit tool 做 string replacement，只改目標行 Why Claude errs: 生成整個檔案比精確編輯更符合 Claude 的訓練分佈 Redirect pattern: 先 Read 完整檔案 → 找到目標 section 的精確文字 → 用 Edit old_string/new_string 替換 Example: ❌ Write 整個 SKILL.md（200 行）只為了改第 145 行 ✅ Edit old_string="舊 gotcha 文字" new_string="新 gotcha 文字"

2. Claude 遺失現有內容

Problem: 編輯時把目標 section 以外的內容弄丟 Correct approach: 編輯前 Read 完整檔案，確認改動範圍 Why Claude errs: 上下文窗口中只保留了目標段落，忘了檔案其他部分 Redirect pattern: Read → 記錄檔案總行數 → Edit → 再 Read 確認總行數沒變 Example: ❌ 改完後檔案從 166 行變成 45 行 ✅ 改完後檔案從 166 行變成 170 行（只多了新 gotcha 的 4 行）

3. Claude 加入通用 gotcha

Problem: 新增的 gotcha 是通用程式建議，不是 Claude 特有問題 Correct approach: 每個 gotcha 必須描述 Claude 的具體操作偏差 Why Claude errs: 訓練數據中大量「best practices」式內容比 Claude 自省式內容多 Redirect pattern: 問自己：「這個問題只有 Claude 會犯嗎？人類工程師也會犯嗎？」如果人類也會犯，這不是 gotcha Example: ❌ "Always validate user input before processing" — 通用建議 ✅ "Claude 傾向給所有維度 2/2" — Claude 特有的 score inflation 偏差

Anti-Sycophancy

禁止：

  • "Good improvement" — 除非分數真的上升了，附數字
  • "This edit looks clean" — 你是在描述還是在判斷？跑 verify
  • "The skill is better now" — better 的定義是什麼？量化

強制問題（Phase 2 必問）：

  • 「這個改動移除了什麼嗎？移除的東西真的不需要嗎？」
  • 「如果把這個改動 revert，用戶會注意到嗎？」

Push-back：如果用戶要求的改動會降低分數，不要順從 — 展示數據，讓用戶帶著完整資訊做決定。

中斷恢復

如果 skill 執行中斷（用戶取消、context 超限、錯誤）：

  1. 偵測狀態： git diff skills/{target-skill}/ — 檢查是否有未 commit 的改動
  2. 恢復點：
    • 如果有未 commit 的 diff → 呈現 diff 給用戶，從 Phase 2（Verify）繼續
    • 如果沒有 diff → 從 Phase 0（Target Identification）重新開始
  3. 不重做： 不重問已確認的修改目標（skill + section + 改什麼），不重新讀已讀過的檔案
  4. 通知用戶： 告知偵測到未完成的編輯，確認繼續驗證或放棄（revert）