5.7 KiB
5.7 KiB
JSC 技能準則
本文件是 jsc 技能組的唯一準則來源。skill-new、skill-update、skill-delete 與技能審核都必須依此檢查。
命名
- Plugin 名稱：
jsc-{domain}，domain 用一個簡短的英文代表詞（例：ask、sdlc、gitea）。 - Marketplace 名稱：
jsc。 - Skill 名稱：小寫、數字、連字號（
-），最長 64 字元。名稱即指令（/jsc-{domain}:{name}）。 - 每個 domain 是一個獨立存取庫
https://gitea.jsc.idv.tw/plugins/{domain}.git。新 domain 必須依https://gitea.jsc.idv.tw/plugins/template的結構建立新存取庫：三份 plugin manifest（plugin 名jsc-{domain}）、自身的.claude-plugin/marketplace.json與.agents/plugins/marketplace.json（marketplace 名 ={domain}）、skills/、README.md、AGENTS.md。 - Git 分支名只允許 ASCII（
a-z0-9與/、-）；中文需求或標題先翻譯成英文短語再 slug 化。
Description 規則
- frontmatter 的
description為一行英文，不超過 5 句或 5 個步驟。 - 使用專有名詞、概念或指引詞（例：WBS、TDD、decision tree、STE100）取代解釋。
- 必須寫清楚觸發時機（何時用、何時不用），這是各 CLI 自動載入的唯一依據。
- 複雜流程透過組合其他技能實現，不在單一 description 裡塞流程。
強制力層級
- 規則的實現優先順序：hook > prompt。凡是可以由 hook 強制的規則（語言、計時、統計），一律下放 hook，SKILL.md 只保留 hook 無法涵蓋的指引。
- 有標準輸入與輸出的流程一律下放到
tools/腳本，SKILL.md 只描述何時呼叫與參數。 - 主 agent 不需要處理細節的流程，SKILL.md 必須明確要求建立 sub agent 處理（關鍵字：「必須以 sub agent 執行」）。
Hook 規則
- 所有 hook 專屬存放於
jsc-hooks，不可散落在其他 domain。 - Hook 腳本實作優先順序：shell > nodejs > python。
- Hook 必須適用於 claude / codex / copilot / antigravity / kiro 五種 CLI：
- 腳本同時支援 stdin JSON（Claude 格式）與環境變數輸入，缺欄位時安靜降級（exit 0）。
- 各 CLI 的接線方式由
jsc-hooks:hooks-install技能處理。
技能設計
- 每個技能必須有單一明確目標，不可與既有技能重複；能複用就複用（呼叫其他技能或工具）。
- 需要操作 gitea 且輸入輸出明確的技能，一律透過
jsc-gitea/tools/gitea.sh（curl +GITEA_TOKEN）或teaCLI，不可自行拼 API 呼叫。 - 需要問使用者的技能，一律透過
jsc-ask:ask的決策樹規則：選項式提問、每個選項標明影響範圍、問到沒有疑慮為止、已有紀錄的答案不再問。
語言
- 所有交談與輸出內容基於 STE100（簡化技術中文）使用繁體中文：短句、一句一指令、主動語態、術語一致、UTF-8 無亂碼。
- SKILL.md 的
description為英文（見上），內文為繁體中文。
撰寫規範（SKILL.md 內文）
- 每個步驟以可檢核的完成條件結尾（例：「成功標上工作證才可以進入下一步」），不用模糊語（「理解後」「適當地」）。
- 用正向敘述寫目標行為；禁止句只留給無法正向表達的硬性護欄。
- 每個意義只有單一真實來源：環境可查的資訊（指令、設定、目錄結構）不要抄進技能，只寫環境查不到的慣例、原因與陷阱。
- 漸進揭露：所有分支都需要的內容留在 SKILL.md；只有部分分支需要的參考資料下放
references/，以一行指引指過去。 - 善用引導詞（WBS、CPM、TDD、seam、STE100 等既有概念）取代整段解釋。
環境變數
| 變數 | 用途 | 未設定時 |
|---|---|---|
GITEA_HOST |
Gitea 站台（例：https://gitea.jsc.idv.tw） |
詢問使用者 |
GITEA_TOKEN |
Gitea API token | 詢問使用者 |
JSC_WIKI_REPO_{TYPE} |
各類型 wiki 頁所在的 {owner}/{repo}；TYPE = QUESTION / PLAN / ANALYZE / MAINTAIN / REPO / LOG |
退回 JSC_WIKI_REPO |
JSC_WIKI_REPO |
未逐類設定時的共用 wiki {owner}/{repo} |
詢問使用者 |
JSC_HOME |
Hook 資料目錄 | 預設 ~/.jsc |
Wiki 頁命名總表
| 頁面 | 用途 | 擁有者 |
|---|---|---|
QUESTION_CONTENTS |
問詢目錄（存取庫名稱 → 問詢紀錄） | jsc-ask |
QUESTION_{HASH} |
單一存取庫的問詢紀錄 | jsc-ask |
PLAN_CONTENTS |
計畫目錄 | jsc-sdlc |
PLAN_{yyyyMMdd}_{HHmmss}_{HASH} |
計畫頁 | jsc-sdlc |
ANALYZE_CONTENTS |
分析目錄 | jsc-sdlc |
ANALYZE_{yyyyMMdd}_{HHmmss}_{HASH} |
分析頁 | jsc-sdlc |
MAINTAIN_CONTENTS |
維護目錄 | jsc-sdlc |
REPO_CONTENTS |
盤點目錄 | jsc-sdlc |
REPO_{HASH} |
存取庫盤點頁（功能與端點 + commit sha） | jsc-sdlc |
LOG_CONTENTS |
日誌目錄 | jsc-log |
LOG_{yyyyMM}_W{週數} |
工作日誌（週數基於週五日期計算） | jsc-log |
{HASH} 一律為 {owner}/{repo}（必要時加上主題字串）的 SHA-1 前 8 碼、大寫。
審核檢查清單
新增或更新技能後逐項檢查，任一不符就修正：
- 名稱符合命名規則，且與既有技能目標不重複
- description 為英文、≤ 5 句或 5 步驟、含觸發時機
- 可 hook 的規則已下放 jsc-hooks；可工具化的流程已下放 tools/
- 細節流程已標示「必須以 sub agent 執行」
- gitea 操作透過 gitea.sh 或 tea
- 問詢透過 jsc-ask 決策樹規則
- 內文為 STE100 繁體中文、UTF-8 無亂碼
- 已同步更新該 domain 的 README「Skills 目錄」與三份 manifest 的 version