plugins/meta
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
24b350880c55072a14900fdc3659f417f818c9fa
meta/references/guidelines.md
T
jiantw83andClaude Fable 5 dd04781058 docs(guidelines): 補記 gitea.sh 的 tea 登入金鑰備援機制 
What（改了什麼）：
- 「技能設計」第 2 條補充：gitea.sh 在 token 未設定或收到 401／403 時，會自動改用 tea 的登入金鑰重試一次。
- 環境變數表 GITEA_TOKEN 的「未設定時」欄位由「詢問使用者」改為「改用 tea 登入金鑰（tea login list）；tea 也沒有才詢問使用者」。

Why（為什麼改）：
- gitea.sh 已實作 tea token 備援，但準則文件未記載；技能作者與審核者依文件行事，文件落後會導致誤判認證失敗的處理方式。

How（怎麼改）：
- 僅更新 references/guidelines.md 兩處文字，與 jsc-gitea/tools/gitea.sh 的實際行為對齊，不動任何流程或工具。

Who（影響哪個功能／使用者）：
- 所有依 guidelines.md 撰寫或審核 jsc 技能的維護者；使用 gitea.sh 的技能在 token 失效時的預期行為自此有文件依據。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-08-21 08:23:53 +00:00

7.0 KiB
Raw Blame History

JSC 技能準則

本文件是 jsc 技能組的唯一準則來源。skill-new、skill-update、skill-delete 與技能審核都必須依此檢查。

命名

  1. Plugin 名稱：jsc-{domain}，domain 用一個簡短的英文代表詞（例：ask、sdlc、gitea）。
  2. Marketplace 統一為 jsc，正本在 https://gitea.jsc.idv.tw/plugins/jsc.git；安裝 token 一律 jsc-{domain}@jsc。每個 domain 存取庫都帶同一份 marketplace 檔（.claude-plugin/marketplace.json 與 .agents/plugins/marketplace.json，內容與正本完全一致），所以任何一個 repo 都能當註冊入口，互相覆蓋沒關係。
  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、skills/、README.md、AGENTS.md），並把 plugin 條目（URL 來源指向新存取庫）加入 plugins/jsc 正本的兩份 marketplace 檔，再把更新後的檔案同步到所有 domain 存取庫（含新存取庫自己）。
  5. Git 分支名只允許 ASCII（a-z0-9 與 /、-）；中文需求或標題先翻譯成英文短語再 slug 化。
  6. Manifest 版本號從 0.0.1 開始，三份 manifest 同步 bump。

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 呼叫。gitea.sh 在 token 未設定或收到 401／403 時，會自動改用 tea 的登入金鑰重試一次。
  3. 需要問使用者的技能，一律透過 jsc-ask:ask 的決策樹規則：選項式提問、每個選項標明影響範圍、問到沒有疑慮為止、已有紀錄的答案不再問。

語言

  1. 所有交談與輸出內容使用 STE100 繁體中文，帶擬人台灣感：短句、一句一指令、主動語態、術語一致、台灣用語、全形標點、去 AI 味、直接講重點。完整規則的唯一來源：references/ste100.md。
  2. 技能文件（SKILL.md）整份為英文：frontmatter 與內文都是。風格比照 STE100：短句、祈使句、術語一致。
  3. 技能文件裡「要原樣輸出的繁中字面內容」保留繁中：wiki 狀態字串（例：已分析、未完成）、hook 注入文字、要寫進 wiki 或 commit 的文案。技能執行時產生的 commit 訊息、PR 描述、wiki 頁內容仍依第 1 條輸出繁中。
  4. README、AGENTS.md、templates/、references/ 為 STE100 繁體中文。中文並列項用頓號「、」，不用半形「/」；英文項目的並列（CLI 名、頁名前綴）可用「/」。

撰寫規範（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 改用 tea 登入金鑰（tea login list）；tea 也沒有才詢問使用者
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/
  • 細節流程已標示 MUST run as a sub agent
  • gitea 操作透過 gitea.sh 或 tea
  • 問詢透過 jsc-ask 決策樹規則
  • SKILL.md 整份為英文（要原樣輸出的繁中字面除外）；README、AGENTS、templates、references 為 STE100 繁中；UTF-8 無亂碼
  • 已同步更新該 domain 的 README「Skills 目錄」與三份 manifest 的 version
Reference in New Issue View Git Blame Copy Permalink