asiaostrich/skill-builder

流程轉 Skill 助手

語言: English | 繁體中文

引導你從「我一直手動做這件事」走到「擁有一個正確建立的 Skill」，並在過程中保持適量的流程治理。

何時使用

• 你已經用同樣的多步驟流程手動執行 ≥ 3 次
• 同事第 3 次問你「我們是怎麼做 X 的？」
• 你臨時建了一個 Skill，現在想將其正式化

備註：/process-to-skill 是本 Skill 的繁體中文翻譯版，功能完全相同。

核心原則

Skill 紀錄的是流程知識。Memory 紀錄的是歷史事實。 當你注意到自己重複執行相同的步驟，那就是 Skill 候選。

決策樹

需要新建 Skill？
├── 修改現有 Skill？
│     → Delta 路徑：在現有 SKILL.md 後附加 ## MODIFIED / ## ADDED
│                   更新 version 欄位 → 完成
│
├── 回答這 4 個問題（任一「是」→ Complex）：
│     1. 超過 7 個步驟？
│     2. 步驟之間有分支邏輯（if / else）？
│     3. 需要 3+ 不同標準／決策的知識？
│     4. 輸出會直接影響子專案原始碼？
│
├── 全部「否」→ Simple 路徑
│     → 填寫 Skill Brief（templates/SKILL-BRIEF-TEMPLATE.md）
│     → 直接建立 SKILL.md（無需 XSPEC）
│
└── 任一「是」→ Complex 路徑
      → 先建立 XSPEC → 執行 /sdd
      → XSPEC Approved 後回到此處

棄用 Skill？
  → 在 SKILL.md frontmatter 加入：
      status: deprecated
      deprecated_at: YYYY-MM-DD
      deprecated_reason: "..."
      superseded_by: "/new-skill"   (若適用)
  → 在 SKILL-CANDIDATES.md 標記為已封存

擺放位置決策

建立 SKILL.md 前，先決定它該放在哪裡：

| 條件 | 擺放位置 | |------|----------| | 步驟引用專案特定路徑（如 TECH-RADAR.md、DEC-*.md） | 專案：{project}/.claude/skills/ | | 步驟為通用流程（無專案特定路徑） | UDS：skills/{name}/ + zh-TW locale |

工作流程

Step 1 — 描述流程

捕捉重複的步驟序列：

• 哪些步驟？依什麼順序？
• 目前手動執行過幾次？
• 觸及哪些工具或檔案？

Step 2 — 更新 SKILL-CANDIDATES.md

打開專案的 SKILL-CANDIDATES.md（首次請從 templates/SKILL-CANDIDATES.md 複製）：

• 尚未記錄 → 新增一列，填入當前次數
• 已記錄 → 增加次數
• 次數達 3 → 標記 trigger ✅，繼續執行

Step 3 — 選擇路徑（Simple / Complex / Delta）

回答 4 個判斷問題，決定：Simple、Complex 或 Delta。

Step 4a — Simple：填寫 Skill Brief

使用 templates/SKILL-BRIEF-TEMPLATE.md：

• 觸發情境（何時會用到？）
• 核心步驟（3 ~ 7 個，有順序）
• 驗收條件（2 ~ 3 條）
• 範圍外（明確邊界）

Step 4b — Complex：建立 XSPEC

執行 /sdd 建立 XSPEC。XSPEC Approved 後回到 Step 5。

Step 4c — Delta：識別變更範圍

識別現有 SKILL.md 中哪些區段需要變更。 在檔尾加入 ## MODIFIED Requirements 或 ## ADDED Requirements。

Step 5 — 建立 / 更新 SKILL.md

依 Brief 或 XSPEC 生成 SKILL.md：

• 確認 frontmatter：name、scope、description、allowed-tools
• description 格式規則（scope: universal 或 uds-specific 時強制）：
  • 必須以 [UDS] 開頭
  • 第一行使用繁體中文描述用途
  • 單行寫法：description: "[UDS] 繁體中文說明"
  • 多行寫法（含 Use when / Keywords）：description: |\n [UDS] 繁體中文說明\n Use when: ...
  • 禁止：description: "\"[UDS] ..."（多餘引號會讓 description 顯示空白）
• UDS 通用 Skill：同步建立 zh-TW locale 版本
• 專案 Skill：放在 {project}/.claude/skills/{name}/SKILL.md

description 快速驗證（寫完即執行）：

bash cross-project/validate-skills.sh
# → 0 ❌ 錯誤才能繼續

Step 6 — 更新 SKILL-CANDIDATES.md

將候選列標記為：trigger ✅、Skill 欄位填寫完成。

Step 7 — Commit

feat(skills): Add /{skill-name} skill. 新增 /{skill-name} Skill。

{English description, 1-2 lines}

{中文描述，1-2 行}

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

輸出檢查清單

完成所有步驟後，請確認：

• [ ] SKILL-CANDIDATES.md 已更新（trigger ✅、Skill 名稱已填）
• [ ] SKILL.md 已建立並有完整 frontmatter（name / scope / description / allowed-tools）
• [ ] description 格式（universal / uds-specific scope 必填）：
  • [ ] 第一行以 [UDS] 開頭（"[UDS] 繁體中文..." 格式）
  • [ ] 使用繁體中文，非純英文
  • [ ] 無多餘外層引號（避免 "\"[UDS]..." 格式）
• [ ] bash cross-project/validate-skills.sh → 0 ❌ 錯誤
• [ ] Simple 路徑：Skill Brief 已引用或保留
• [ ] Complex 路徑：XSPEC ID 已記錄在 SKILL.md header comment
• [ ] UDS skill：已建立 zh-TW locale 檔案
• [ ] 棄用：frontmatter 含 status: deprecated
• [ ] git commit 已完成

參考

• Skill Brief 模板：templates/SKILL-BRIEF-TEMPLATE.md
• 候選追蹤：templates/SKILL-CANDIDATES.md（請複製到專案）
• ADR 標準：core/adr-standards.md