zakelfassi/skills-driven-development

SkillForge

從觀察到的模式中建立格式完整、符合規範的技能。

何時鍛造

✅ 鍛造時機：

• 你在同一個會話中已執行相同序列 2-3 次
• 某個專案慣例尚未在任何地方文件化
• 你解決了一個難題，且解法具有可重複使用性
• 有人要求你建立一個技能

❌ 不要鍛造：

• 那是一次性任務
• 現有技能已涵蓋該問題（應更新而非新建）
• 所謂的「技能」只是一個單一指令（請使用腳本別名）

步驟

1. 命名模式

• 這個技能解決什麼問題？
• 什麼觸發它？（請具體說明——description 欄位是發現的表面）
• 輸入與輸出是什麼？

2. 選擇名稱

• kebab-case，長度 1-64 字元
• 盡量以動詞開頭：deploy-preview、scaffold-component、triage-bug
• 每個技能只負責一個職責

3. 建立技能目錄

mkdir -p skills/<skill-name>

4. 撰寫 SKILL.md

使用以下骨架：

---
name: <skill-name>
description: <它的功能>。當 <觸發條件> 時使用。
metadata:
  forged-by: <代理 ID>
  forged-from: <會話或背景>
  forged-reason: "<建立原因>"
---

# <技能名稱>

## 輸入
- ...

## 步驟
1. ...
2. ...

## 慣例
- 專案特定的模式

## 邊界情況
- 已知的陷阱或特殊處理

5. 新增腳本（可選）

如果技能涉及檔案產生或自動化：

skills/<skill-name>/
├── SKILL.md
├── scripts/
│   └── run.sh         # 可執行的自動化腳本
└── references/
    └── conventions.md # 詳細參考文件（讓 SKILL.md 保持精簡）

6. 註冊技能

更新專案根目錄（與 skills/ 同一層）的 .skills-registry.md。如果該檔案不存在請建立它：

| <skill-name> | local | <今天日期> | 1 | <description> |

如果專案使用機器可讀的註冊表（.skills-registry.json），也一併更新——skdd forge 會自動處理兩種格式。

更新現有技能

當你使用某個技能並遇到它未涵蓋的情況時：

1. 將新的邊界情況或步驟新增到現有的 SKILL.md
2. 如果技能檔案太長（超過 200 行），請拆分成多個
3. 更新註冊表中的 last-used 並增加 usage-count

品質檢查清單

在提交新技能前：

• name 是 kebab-case，長度 ≤64 字元
• description 包含功能說明與使用時機
• 步驟已編號且可操作
• 沒有硬編碼的路徑、秘密或環境特定值
• SKILL.md 少於 200 行（詳細內容移至 references/）
• 已在 .skills-registry.md 中註冊