CLAUDE.md · diff

git:20260805.f3554ac to git:20260806.5bfe60b

14 added, 14 removed. Audit A to A.

- Skills are organized into bucket folders under `skills/`:

+ 技能以 bucket 資料夾形式組織在 `skills/` 下：

- - `engineering/` — daily code work

- - `productivity/` — daily non-code workflow tools

- - `misc/` — kept around but rarely used, not promoted

- - `in-progress/` — beta: public on purpose, feedback wanted, not shipped in the plugin

- - `deprecated/` — no longer used

+ - `engineering/` — 每日程式碼工作

+ - `productivity/` — 每日非程式碼的工作流程工具

+ - `misc/` — 保留但少用，未推廣

+ - `in-progress/` — beta：刻意公開、歡迎回饋、未隨 plugin 發布

+ - `deprecated/` — 已不再使用

- Every skill in `engineering/` or `productivity/` (the **promoted** buckets) must have a reference in the top-level `README.md` and an entry in `.claude-plugin/plugin.json`'s `skills` array (the Claude Code plugin ships exactly the promoted set). Skills in `misc/`, `in-progress/`, and `deprecated/` must not appear in either.

+ `engineering/` 或 `productivity/`（**已推廣（promoted）** 的 bucket）中的每個技能，都必須在頂層 `README.md` 有參照，並在 `.claude-plugin/plugin.json` 的 `skills` 陣列中有對應項目（Claude Code plugin 發布的正好就是已推廣的那一組）。`misc/`、`in-progress/`、`deprecated/` 中的技能不得出現在上述兩者之中。

- Install commands are copied verbatim from [.agents/install-block.md](./.agents/install-block.md). `.claude-plugin/marketplace.json` makes the repo its own single-plugin marketplace — a fallback the install block explains, not the documented route. Run `claude plugin validate . --strict` after touching either manifest. Why a Claude plugin but not (yet) a Codex one lives in [.agents/adr/0002-ship-as-a-claude-code-plugin.md](./.agents/adr/0002-ship-as-a-claude-code-plugin.md).

+ 安裝指令直接從 [.agents/install-block.md](./.agents/install-block.md) 複製。`.claude-plugin/marketplace.json` 讓 repo 成為自己的單一 plugin marketplace — 這是 install block 說明的備援方案，而非文件記載的路徑。觸碰任一 manifest 後，執行 `claude plugin validate . --strict`。為什麼做 Claude plugin 而（目前）不做 Codex plugin，記錄在 [.agents/adr/0002-ship-as-a-claude-code-plugin.md](./.agents/adr/0002-ship-as-a-claude-code-plugin.md)。

- Each skill entry in the top-level `README.md` must link the skill name to its `SKILL.md`.

+ 頂層 `README.md` 中每個技能的項目，必須把技能名稱連結到其 `SKILL.md`。

- Each bucket folder has a `README.md` that lists every skill in the bucket with a one-line description, with the skill name linked to its `SKILL.md`. The promoted buckets' `README.md`s and the top-level `README.md` group entries into **User-invoked** and **Model-invoked**; non-promoted bucket `README.md`s (`misc/`, `in-progress/`) use a flat list.

+ 每個 bucket 資料夾都有 `README.md`，以一行描述列出 bucket 內每個技能，並把技能名稱連結到其 `SKILL.md`。已推廣 bucket 的 `README.md` 與頂層 `README.md` 把項目分成 **User-invoked（使用者觸發）** 與 **Model-invoked（模型觸發）**；未推廣 bucket（`misc/`、`in-progress/`）的 `README.md` 使用平鋪清單。

- Skills in `engineering/` and `productivity/` also have a human-facing docs page at `docs/<bucket>/<skill-name>.md` (the docs tree mirrors those two bucket folders under `skills/`). The published URL is `https://aihero.dev/skills-<skill-name>` regardless of bucket — the docs path is repo organisation only. When you add, rename, or change the behaviour of a skill in `engineering/` or `productivity/`, create or re-sync its docs page following [.agents/writing-docs.md](./.agents/writing-docs.md). A finished page carries four sections — **What it does**, **When to reach for it**, **Common questions**, **It's working if** — and `writing-docs.md` holds the template, the section order, and where to hunt for the questions. Skills in the non-promoted buckets (`misc/`, `in-progress/`, `deprecated/`) get **no** docs page.

+ `engineering/` 與 `productivity/` 中的技能，也有位於 `docs/<bucket>/<skill-name>.md` 的給人看的文件頁（docs 樹鏡像 `skills/` 下的這兩個 bucket 資料夾）。發布的 URL 一律是 `https://aihero.dev/skills-<skill-name>`，與 bucket 無關 — docs 路徑只是 repo 的組織方式。當你在 `engineering/` 或 `productivity/` 新增、改名或改變某技能的**行為**時，依照 [.agents/writing-docs.md](./.agents/writing-docs.md) 建立或重新同步其 docs 頁。完成的頁面帶有四個章節 — **What it does（它做什麼）**、**When to reach for it（何時使用）**、**Common questions（常見問題）**、**It's working if（這樣就算成功）** — 而 `writing-docs.md` 保存模板、章節順序，以及哪裡可以找這些問題。未推廣 bucket（`misc/`、`in-progress/`、`deprecated/`）的技能**沒有** docs 頁。

- Every `SKILL.md` is either user-invoked (`disable-model-invocation: true` plus `policy.allow_implicit_invocation: false` in `agents/openai.yaml`, reachable only by the human) or model-invoked (model- or user-reachable). See [.agents/invocation.md](./.agents/invocation.md).

+ 每個 `SKILL.md` 不是 user-invoked（`disable-model-invocation: true` 加上 `agents/openai.yaml` 中的 `policy.allow_implicit_invocation: false`，僅由人觸發），就是 model-invoked（模型或使用者皆可觸發）。參見 [.agents/invocation.md](./.agents/invocation.md)。

- [`ask-matt`](./skills/engineering/ask-matt/SKILL.md) is the router that maps every user-reachable skill and how they relate. The same trigger that re-syncs a docs page applies to it: whenever you add, rename, remove, or change how a user-reachable skill fits the flows, re-read `ask-matt`'s `SKILL.md` and update it so the map stays accurate — a new skill it never mentions, or a stale one it still routes to, is a router that lies.

+ [`ask-matt`](./skills/engineering/ask-matt/SKILL.md) 是路由每個可觸發技能及其關聯的路由器。觸發重新同步 docs 頁的同一條件也適用於它：每當你新增、改名、移除或改變某個可觸發技能在流程中的定位時，重新讀取 `ask-matt` 的 `SKILL.md` 並更新它，讓地圖保持準確 — 一個它從未提及的新技能，或一個它仍在路由的過時技能，就是一個會騙人的路由器。

- To (re)link every skill into the local harness skill directories (`~/.claude/skills`, `~/.agents/skills`), run `scripts/link-skills.sh`. Each entry is a symlink into this repo, so a `git pull` keeps installed skills current; re-run the script after adding, removing, or renaming a skill.

+ 要把每個技能（重新）連結到本機 harness 的 skill 目錄（`~/.claude/skills`、`~/.agents/skills`），執行 `scripts/link-skills.sh`。每個項目都是指回此 repo 的 symlink，因此 `git pull` 即可讓已安裝的技能保持最新；新增、移除或改名技能後重新執行該腳本。