diff --git a/references/guidelines.md b/references/guidelines.md new file mode 100644 index 0000000..743b66e --- /dev/null +++ b/references/guidelines.md @@ -0,0 +1,92 @@ +# JSC 技能準則 + +本文件是 jsc 技能組的唯一準則來源。`skill-new`、`skill-update`、`skill-delete` 與技能審核都必須依此檢查。 + +## 命名 + +1. Plugin 名稱：`jsc-{domain}`，domain 用一個簡短的英文代表詞（例：`ask`、`sdlc`、`gitea`）。 +2. Marketplace 名稱：`jsc`。 +3. Skill 名稱：小寫、數字、連字號（`-`），最長 64 字元。名稱即指令（`/jsc-{domain}:{name}`）。 +4. 每個 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`。 +5. Git 分支名**只允許 ASCII**（`a-z0-9` 與 `/`、`-`）；中文需求或標題先翻譯成英文短語再 slug 化。 + +## Description 規則 + +1. frontmatter 的 `description` 為一行英文，不超過 5 句或 5 個步驟。 +2. 使用專有名詞、概念或指引詞（例：WBS、TDD、decision tree、STE100）取代解釋。 +3. 必須寫清楚觸發時機（何時用、何時不用），這是各 CLI 自動載入的唯一依據。 +4. 複雜流程透過**組合其他技能**實現，不在單一 description 裡塞流程。 + +## 強制力層級 + +1. 規則的實現優先順序：**hook > prompt**。凡是可以由 hook 強制的規則（語言、計時、統計），一律下放 hook，SKILL.md 只保留 hook 無法涵蓋的指引。 +2. 有標準輸入與輸出的流程一律下放到 `tools/` 腳本，SKILL.md 只描述何時呼叫與參數。 +3. 主 agent 不需要處理細節的流程，SKILL.md 必須明確要求建立 sub agent 處理（關鍵字：「必須以 sub agent 執行」）。 + +## Hook 規則 + +1. 所有 hook 專屬存放於 `jsc-hooks`，**不可散落在其他 domain**。 +2. Hook 腳本實作優先順序：**shell > nodejs > python**。 +3. Hook 必須適用於 claude / codex / copilot / antigravity / kiro 五種 CLI： + - 腳本同時支援 stdin JSON（Claude 格式）與環境變數輸入，缺欄位時安靜降級（exit 0）。 + - 各 CLI 的接線方式由 `jsc-hooks:hooks-install` 技能處理。 + +## 技能設計 + +1. 每個技能必須有單一明確目標，不可與既有技能重複；能複用就複用（呼叫其他技能或工具）。 +2. 需要操作 gitea 且輸入輸出明確的技能，一律透過 `jsc-gitea/tools/gitea.sh`（curl + `GITEA_TOKEN`）或 `tea` CLI，不可自行拼 API 呼叫。 +3. 需要問使用者的技能，一律透過 `jsc-ask:ask` 的決策樹規則：選項式提問、每個選項標明影響範圍、問到沒有疑慮為止、已有紀錄的答案不再問。 + +## 語言 + +1. 所有交談與輸出內容基於 STE100（簡化技術中文）使用繁體中文：短句、一句一指令、主動語態、術語一致、UTF-8 無亂碼。 +2. SKILL.md 的 `description` 為英文（見上），內文為繁體中文。 + +## 撰寫規範（SKILL.md 內文） + +1. 每個步驟以**可檢核的完成條件**結尾（例：「成功標上工作證才可以進入下一步」），不用模糊語（「理解後」「適當地」）。 +2. 用**正向敘述**寫目標行為；禁止句只留給無法正向表達的硬性護欄。 +3. 每個意義只有**單一真實來源**：環境可查的資訊（指令、設定、目錄結構）不要抄進技能，只寫環境查不到的慣例、原因與陷阱。 +4. **漸進揭露**：所有分支都需要的內容留在 SKILL.md；只有部分分支需要的參考資料下放 `references/`，以一行指引指過去。 +5. 善用**引導詞**（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 diff --git a/skills/skill-delete/SKILL.md b/skills/skill-delete/SKILL.md new file mode 100644 index 0000000..7f68295 --- /dev/null +++ b/skills/skill-delete/SKILL.md @@ -0,0 +1,22 @@ +--- +name: skill-delete +description: Remove a skill from the jsc skill set safely. List skills, let the user pick, inventory every file referencing the skill via a sub agent, fix each affected file through decision-tree questions until guideline checks pass, then delete the skill and open a PR via jsc-git pr. Use only for removal; not for renaming (use skill-update). +--- + +# skill-delete — 刪除技能 + +準則單一來源：[`../../references/guidelines.md`](../../references/guidelines.md)。 + +## 流程 + +1. 列出技能組內含的所有技能：掃描 `jsc-*/skills/*/SKILL.md`。 +2. 讓使用者選擇要刪除的技能（選項標明影響範圍：被哪些技能引用、刪除後指令即失效）。 +3. 盤點與此技能關聯的所有檔案，此步驟**必須以 sub agent 執行**： + - `grep -r` 技能名稱與 `/jsc-{domain}:{name}` 於整個 monorepo + - 其他 SKILL.md 的引用、domain README「Skills 目錄」、該 repo 自身兩份 marketplace.json、`tools/`、`jsc-hooks` 接線 +4. 逐檔執行： + 1. 判斷刪除技能後，該檔是否需要修正才能維持既有功能；**不需要修正就跳過**剩下的流程。 + 2. 依 `jsc-ask:ask` 決策樹詢問修正細節（改為呼叫替代技能？內聯流程？一併移除功能？），每個選項標明影響範圍。 + 3. 修正後依 guidelines.md「審核檢查清單」檢查；不符合就回到步驟 4.2。 +5. 刪除技能目錄 `skills/{name}/`，同步 domain README 與三份 manifest 的 version bump。 +6. 呼叫 `jsc-git:pr` 建立 Push Request。 diff --git a/skills/skill-new/SKILL.md b/skills/skill-new/SKILL.md new file mode 100644 index 0000000..acc0b5a --- /dev/null +++ b/skills/skill-new/SKILL.md @@ -0,0 +1,25 @@ +--- +name: skill-new +description: Create a new skill in the jsc skill set. Ask skill details via decision tree, generate the skill under the right jsc-{domain} per guidelines.md (create the domain from the template repo if missing), then open a PR via jsc-git pr. Use when the user wants to add a skill; not for editing an existing one (use skill-update). +--- + +# skill-new — 新建技能 + +準則單一來源：[`../../references/guidelines.md`](../../references/guidelines.md)。 + +## 流程 + +1. 依 `jsc-ask:ask` 決策樹詢問技能細節，直到沒有疑慮： + - 目標（單一、與既有技能不重複——先掃 `jsc-*/skills/*/SKILL.md` 列出相近技能供比對，選項需標明「複用既有」與「新建」的影響範圍） + - 觸發時機（何時用、何時不用、觸發關鍵字） + - 輸入與輸出（是否有標準輸入輸出可下放 `tools/`；是否需要 gitea 操作——需要就讓技能使用 `jsc-gitea/tools/gitea.sh` + token） + - 所屬 domain（列出現有 `jsc-*` 供選擇） +2. 若 domain 不存在： + 1. 為其想一個簡短的英文代表詞（一個單字為佳），與使用者確認。 + 2. 請使用者建立存取庫 `plugins/{domain}`，clone 後依 `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。 +3. 依 guidelines.md 產生技能（此步驟**必須以 sub agent 執行**）： + - `skills/{name}/SKILL.md`：英文 description（≤ 5 句、含觸發時機）、STE100 繁中內文 + - 可 hook 的規則放 `jsc-hooks`（不可散落本 domain）；標準輸入輸出流程放 `tools/` + - 同步該 domain README 的「Skills 目錄」、三份 manifest 的 version bump +4. 依 guidelines.md「審核檢查清單」逐項自檢，不符就修正。 +5. 呼叫 `jsc-git:pr` 建立 Push Request。 diff --git a/skills/skill-update/SKILL.md b/skills/skill-update/SKILL.md new file mode 100644 index 0000000..0e87dde --- /dev/null +++ b/skills/skill-update/SKILL.md @@ -0,0 +1,17 @@ +--- +name: skill-update +description: Update an existing skill in the jsc skill set. List all skills, let the user pick one, ask update details via decision tree, apply the change, re-check against the guidelines checklist until it passes, then open a PR via jsc-git pr. Use for modifying a skill; not for creating (skill-new) or removing (skill-delete). +--- + +# skill-update — 更新技能 + +準則單一來源：[`../../references/guidelines.md`](../../references/guidelines.md)。 + +## 流程 + +1. 列出技能組內含的所有技能：掃描 `jsc-*/skills/*/SKILL.md`，以「domain / 名稱 / description」清單呈現。 +2. 讓使用者選擇要更新的技能。 +3. 依 `jsc-ask:ask` 決策樹詢問更新細節（改目標？改觸發時機？改流程？下放 hook 或工具？），每個選項標明影響範圍（例：改名會使既有呼叫指令失效）。 +4. 更新技能（此步驟**必須以 sub agent 執行**）：修改 SKILL.md 與關聯檔案，同步 domain README「Skills 目錄」與三份 manifest 的 version bump。 +5. 依 guidelines.md「審核檢查清單」逐項檢查；**不符合就回到步驟 3** 重新詢問並修正，直到全部通過。 +6. 呼叫 `jsc-git:pr` 建立 Push Request。