# 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: `fagemx/skill-edit` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add fagemx/skill-edit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/fagemx/skill-edit/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: fagemx (https://skillmd.com/u/fagemx)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/fagemx/skill-edit

---


# 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. 先前編輯偵測

```bash
# 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?

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

3. 檢查副作用：
   - 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）