@vinvcn/dsh-mattpocock-skills-zh 1.2.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,78 @@
+# Matt Pocock Skills 中文本地化 dsh 插件
+
+## 这是什么
+
+本插件包把 `mattpocock-skills-zh-CN` 仓库的 35 个可用技能，打包为 DeepSeek Harness（dsh）插件。
+
+技能以 `zh-<name>` 命名，并以 `/zh-<name>` 调用，例如 `/zh-grilling`。
+
+## 30 秒安装
+
+前提：机器上已能运行 dsh（`dsh --version` 有输出）。尚未安装时，先用 `npx @deepseek-ai/dsh web` 启动一次。
+
+1. 把插件装进 web profile：
+
+   ```sh
+   dsh plugin --profile web add @vinvcn/dsh-mattpocock-skills-zh
+   ```
+
+   该包尚未发布到 npm 之前，用打包出的 tarball 绝对路径代替包名：
+
+   ```sh
+   (cd dsh-plugin && npm pack)
+   dsh plugin --profile web add "$PWD/dsh-plugin/vinvcn-dsh-mattpocock-skills-zh-1.2.3.tgz"
+   ```
+
+2. 启动 dsh：
+
+   ```sh
+   dsh web
+   ```
+
+3. 在会话中输入 `/zh-grilling`（或任意 `/zh-<name>`）即可调用。
+
+确认插件已挂载：
+
+```sh
+dsh --profile web --dump-config | grep 'id: mattpocock-skills-zh'
+```
+
+## 构建期改写
+
+构建期会重写 skill 正文里的内部引用：`/grilling` 会变成 `/zh-grilling`。
+
+非 `.md` 资源文件与 `argument-hint` frontmatter 原样复制，dsh 不消费它们。
+
+仓库根目录内容不会被改动。
+
+## 维护者发布
+
+发布前先登录 npm（账号需有权发布 `@vinvcn` scope）：
+
+```sh
+npm login
+npm whoami
+```
+
+然后构建并发布：
+
+```sh
+(cd dsh-plugin && npm run build)
+(cd dsh-plugin && npm publish)
+```
+
+`private:false` 与 `publishConfig.access: public` 使该包可以公开发布。
+
+发布成功后无需 tarball，直接安装：
+
+```sh
+dsh plugin --profile web add @vinvcn/dsh-mattpocock-skills-zh
+```
+
+## 局限
+
+正文中裸写的技能名不会被重写。
+
+`in-progress` 技能仍为 beta。
+
+当前共 35 个技能。

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+  - id: mattpocock-skills-zh
+    name: '@vinvcn/dsh-mattpocock-skills-zh'

package/index.js

@@ -0,0 +1,124 @@
+/**
+ * Self-contained skill provider for the bundled `mattpocock-skills-zh` package.
+ *
+ * Discovers the generated `skills/<name>/SKILL.md` bundle shipped in this
+ * package, parses each file's YAML frontmatter, and registers the results on
+ * `ctx.skills` at bundled rank 600. Skill bodies are re-read on every `get`,
+ * so edits need no cache invalidation.
+ *
+ * @module @vinvcn/dsh-mattpocock-skills-zh
+ */
+
+import { readdir, readFile } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+import { join } from 'node:path'
+import { parse } from 'yaml'
+
+/** Provider name registered on `ctx.skills`. */
+const PROVIDER_NAME = 'mattpocock-skills-zh'
+/** Bundled-provider rank, matching `BUNDLED_SKILL_RANK` in `dsh-skill`. */
+const RANK = 600
+/** Origin bucket for skills shipped inside this package. */
+const SOURCE = 'bundled'
+/** Absolute path of the generated skill tree. */
+const skillsRoot = fileURLToPath(new URL('./skills/', import.meta.url))
+
+/**
+ * Split `---`-delimited YAML frontmatter from a skill's Markdown body.
+ * @param raw - full `SKILL.md` text.
+ * @returns parsed frontmatter object and the body after it, or `undefined` when
+ *   the file has no closed frontmatter block.
+ */
+function splitFrontmatter(raw) {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(raw)
+  if (match === null) return undefined
+  return { data: parse(match[1]) ?? {}, body: raw.slice(match[0].length) }
+}
+
+/**
+ * Project frontmatter into the shared invocation policy; omitted fields permit
+ * both surfaces.
+ * @param data - parsed frontmatter.
+ * @returns model and user invocation controls.
+ */
+function invocationFrom(data) {
+  return {
+    modelInvocable: data['disable-model-invocation'] !== true,
+    userInvocable: data['user-invocable'] !== false,
+  }
+}
+
+/**
+ * Create a provider over a skill root.
+ * @param root - absolute directory containing one `<name>/SKILL.md` bundle per
+ *   skill; defaults to this package's generated `skills/` tree.
+ * @returns the `ctx.skills` provider, whose `list`/`get` both return Promises.
+ */
+export function createProvider(root = skillsRoot) {
+  return {
+    name: PROVIDER_NAME,
+    async list(_options) {
+      const entries = await readdir(root, { withFileTypes: true })
+      entries.sort((left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0))
+      const candidates = []
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue
+        const dir = join(root, entry.name)
+        const { data } = splitFrontmatter(await readFile(join(dir, 'SKILL.md'), 'utf8')) ?? { data: {} }
+        const whenToUse = data.whenToUse
+        const metadata = data.metadata
+        candidates.push({
+          name: data.name,
+          description: data.description,
+          ...(whenToUse !== undefined ? { whenToUse } : {}),
+          invocation: invocationFrom(data),
+          source: SOURCE,
+          provider: PROVIDER_NAME,
+          rank: RANK,
+          locator: dir,
+          path: join(dir, 'SKILL.md'),
+          ...(metadata !== undefined ? { metadata } : {}),
+        })
+      }
+      return candidates
+    },
+    async get(candidate, _options) {
+      let raw
+      try {
+        raw = await readFile(candidate.path, 'utf8')
+      } catch {
+        // Any `readFile` failure (missing, unreadable, or invalid path) means the skill is no longer loadable.
+        return undefined
+      }
+      const frontmatter = splitFrontmatter(raw)
+      const data = frontmatter?.data ?? {}
+      const whenToUse = data.whenToUse
+      const metadata = data.metadata
+      return {
+        name: data.name,
+        description: data.description,
+        ...(whenToUse !== undefined ? { whenToUse } : {}),
+        invocation: invocationFrom(data),
+        source: SOURCE,
+        provider: PROVIDER_NAME,
+        path: candidate.path,
+        ...(metadata !== undefined ? { metadata } : {}),
+        resourceBase: { kind: 'directory', path: candidate.locator },
+        content: frontmatter?.body ?? raw,
+      }
+    },
+  }
+}
+
+/** Cordis plugin name. */
+export const name = PROVIDER_NAME
+/** Service required by the bundled provider. */
+export const inject = ['skills']
+
+/**
+ * Register the bundled provider on `ctx.skills`.
+ * @param ctx - Cordis context carrying the `skills` service.
+ */
+export function apply(ctx) {
+  ctx.skills.registerProvider(() => createProvider())
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@vinvcn/dsh-mattpocock-skills-zh",
+  "version": "1.2.3",
+  "description": "Matt Pocock skills 中文本地化的 DeepSeek Harness 插件包：以 zh- 前缀暴露全部 35 个可用技能。",
+  "private": false,
+  "publishConfig": { "access": "public" },
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./package.json": "./package.json"
+  },
+  "files": ["index.js", "cordis.patch.yml", "LICENSE", "README.md", "skills"],
+  "engines": { "node": "^22.19.0 || >=24" },
+  "license": "MIT",
+  "repository": { "type": "git", "url": "git+https://github.com/vinvcn/mattpocock-skills-zh-CN.git", "directory": "dsh-plugin" },
+  "dsh": { "bundle": { "patch": "./cordis.patch.yml" } },
+  "dependencies": { "yaml": "^2.4.2" },
+  "scripts": {
+    "build": "node scripts/copy-skills.mjs",
+    "verify": "node scripts/verify.mjs",
+    "test": "node --test",
+    "version:check": "node scripts/verify-version-sync.mjs",
+    "prepack": "npm run version:check && npm run build && npm test && npm run verify"
+  }
+}

package/skills/ask-matt/PHASE-BOUNDARIES.md

@@ -0,0 +1,55 @@
+# Phase boundaries
+
+**phase** 是 session 内的一段工作——grilling、implementation、QA。这个定义刻意模糊：当你冒出 "行，这个做完了" 的想法时，一个 phase 就结束了。
+
+**phase boundary** 是两个 phase 之间的间隙，也是这个决定唯一该出现的地方。phase 中途没有决定要做——要么继续，要么把剩余的工作拆成 subagents。在 phase 中途 compact 会让 agent 丢失线索。
+
+## The five options
+
+| Option       | What it does                                                    |
+| ------------ | --------------------------------------------------------------- |
+| **Continue** | Stay in the session. No context switch at all.                    |
+| **`/clear`** | Empty the context window and start from nothing.                  |
+| **`/zh-handoff`** | Write a portable markdown file and seed a session anywhere with it. |
+| **Subagent** | Send the task to its own context window and get a report back.     |
+| **`/compact`** | Compress this context and seed a fresh session with the summary.  |
+
+## The tree
+
+在 boundary 处从上到下工作。第一个 **yes** 胜出。
+
+**1. 你能在这个 session 里继续吗？** 有两个条件让答案为 yes：下一 phase 需要当前 phase 作为 **primary source**，或者你还有足够的 [smart zone](https://www.aihero.dev/ai-coding-dictionary/smart-zone)（约 150k tokens）让下一 phase 装得下。Grilling -> implementation 是标准的 yes：implementation 想要的是逐字的推理过程，而不是它的 summary。Continue 不花成本也不丢任何东西，所以先排除它。
+
+**2. 这个 context 对接下来要做的事无关紧要吗？** 这个 session 里的一切——探索、决定、死胡同——都可以丢弃吗？如果是，**`/clear`**。它是整张棋盘上最便宜的一步：不花时间，把整个 window 还给你。`/clear` 也不是终局——旧 session 仍然可以恢复。
+
+选错这一步的代价是单向的。清掉一个 *relevant* 的 context，你就失去了你构建之物背后的 **why**，再怎么回读 diff 也要不回来。
+
+**3. 你需要 hand off 吗？** `/zh-handoff` 很窄。只有以下情况才需要它：
+
+- 换到 **new harness**（Claude -> Codex），
+- 移到 **new directory** 或 repo，
+- 把工作交给 **colleague**，
+- 或者在 **phase 中途** 分叉一个 side task，而不打乱你正在做的事。
+
+这个列表就是全部条款。`/zh-handoff` 买到的是 **portability**——一份能随行移动的文件。如果没有东西在移动，你就不需要它。
+
+**4. 这个 task 能否 AFK 完成？** 它的 scope 是否足够紧，能在你离开键盘、不做任何 steering 的情况下运行？如果是，就把它发给 **subagent**，让这个 session 保持原样。自动化 review 是标准场景：agent 读 diff 并报告，期间不需要你。
+
+**5. 否则，`/compact`。** Relevant context、同一 harness、同一 directory，而且你需要留在 loop 中——树的落点就在这里，而且经常落在这里。给它一条指令（`/compact we're going to QA this area`），让 summary 保留下一 phase 需要的东西。
+
+`/compact` 是 **default，不是最先伸手可及的选择**。它位于树底，是因为上面四个问题的成本都更低或更精确。人们从这里开始时典型的 failure mode 是：一个 fresh session 对 summary 压扁过的决定自信地给出错误答案。
+
+## Primary and secondary sources
+
+除了 **Continue**，每个动作都会把 **primary source** 变成 **secondary source**——以 summary 取而代之正在发生的 session。权衡的形状总是一样的：
+
+| Source                            | Information | Noise | Room to move |
+| --------------------------------- | ----------- | ----- | ------------ |
+| Primary (Continue)                | Full        | Lots  | Little       |
+| Secondary (`/compact`, `/zh-handoff`) | Lossy       | Less  | Lots         |
+
+这就是为什么问题 1 排在最前。只有留在原地比省下更多时，你才付 lossiness 的代价。
+
+## These are judgement calls
+
+这些问题不是客观的——每个都掺着品味，同一个 boundary 昨天和今天可能走两个方向。价值在于**按顺序**、在 boundary 而不是工作中途提出它们。

package/skills/ask-matt/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: zh-ask-matt
+description: 询问当前情境适合哪个技能或流程；它是本仓库所有 skills 的路由器。
+disable-model-invocation: true
+---
+
+# Ask Matt
+
+你不需要记住每个 skill，所以直接问。
+
+**Flow** 是穿过 skills 的一条路径。大多数路径沿着一条 **main flow** 前进，两个 **on-ramps** 会并入它。其他内容要么是 standalone，要么是在下层运行的 vocabulary layer。
+
+## The main flow: idea -> ship
+
+这是大多数工作的路线：你有一个想法，并希望把它构建出来。
+
+1. **`/zh-grill-with-docs`** - 通过访谈打磨想法。在 **working directory** 中工作时从这里开始：它是 stateful 的，会把学到的内容保存在 `CONTEXT.md` 和 ADRs 中。（没有 working directory？用 `/zh-grill-me`，见 Standalone。两者都运行同一个 `/zh-grilling` primitive；`grill-with-docs` 是会留下文档痕迹的版本，只要有 repo 可记录，它就是两者中更好的那个。）
+2. **分支 - 能否在对话中解决所有问题？** 如果某个问题需要可运行的答案（state、business logic，或必须亲眼看到的 UI），就通过 prototype 绕行，并用 **`/zh-handoff`** 在两个方向桥接（prototype 住在自己的目录里，这正是 `/zh-handoff` 的用途，见 Phase boundaries）：
+   - **`/zh-handoff`** 导出，然后基于该文件打开 fresh session；
+   - **`/zh-prototype`** 用 throwaway code 回答问题；
+   - **`/zh-handoff`** 把学到的内容带回来，并在原始 idea thread 中引用它。
+3. **分支 - 这是 multi-session build 吗？**
+   - **是** -> **`/zh-to-spec`**（把 thread 变成 spec），再用 **`/zh-to-tickets`** 拆成 tracer-bullet tickets，每个 ticket 声明 **blocking edges**。Local tracker 在 `.scratch/<feature>/issues/` 下每 ticket 一个文件，手动按 blockers-first 处理；真实 tracker 用 native blocking links，因此 blockers 已完成的 ticket 都可领取。每 ticket 启动一次 **`/zh-implement`**，并在 tickets 之间用 **`/clear`** 清空 context。每个 ticket 都是自包含的，因此最后一个 ticket 的 context 可以丢弃。
+   - **否** -> 在当前 context window 里直接运行 **`/zh-implement`**。
+
+   无论哪种方式，**`/zh-implement`** 都会在内部驱动 **`/zh-tdd`** 构建每个 issue：一次一个 red-green slice；然后用 **`/zh-code-review`** 收尾，对 diff 做 Standards + Spec 双轴 review，再提交。只想在没有完整 spec 的情况下 test-first 构建一个具体 behavior 时，单独用 **`/zh-tdd`**；想按固定点 review branch 或 PR 时，单独用 **`/zh-code-review`**。
+
+### Context hygiene
+
+步骤 1 到 `/zh-to-tickets` 要留在 **同一个未中断的 context window** 中；不要 compact 或 clear，这样 grilling、spec 和 tickets 才能建立在同一组思考之上。之后每个 `/zh-implement` 都从 fresh session 开始，只基于对应 ticket 工作。
+
+限制来自 **[smart zone](https://www.aihero.dev/ai-coding-dictionary/smart-zone)**：在该窗口（最新模型大约 150k tokens）内，模型还能保持敏锐推理。如果 session 在 `/zh-to-tickets` 前接近这个区间，不要硬撑降级状态；在最近的 phase boundary 用 `/compact`，然后继续（见 Phase boundaries）。
+
+## On-ramps
+
+起点会生成工作，然后并入 main flow。
+
+- **Bugs 和 requests 堆积** -> **`/zh-triage`**。它通过 triage roles 推进 issues，并产出 agent-ready issues，之后由 **`/zh-implement`** 领取。
+
+  Triage 只用于 **不是你创建的** issues：bug reports、incoming feature requests，以及任何原始进入的内容。`/zh-to-tickets` 产出的 tickets 已经是 agent-ready，不要再 triage。
+
+- **Something's broken** -> **`/zh-diagnosing-bugs`**。用于难处理的问题：第一眼看不出的 bug、间歇性 flake、夹在两个 known-good states 之间的 regression。它在拥有 **tight feedback loop** 前拒绝空想，也就是一个已经能在 _这个_ bug 上变红的命令；然后用 regression test 修复。如果复盘发现真正问题是没有好 seam 能锁住 bug，它会把后续交给 **`/zh-improve-codebase-architecture`**。
+
+- **巨大而模糊的 effort——greenfield project 或巨大 feature build，一个 session 装不下** -> **`/zh-wayfinder`**，这是这里认知负担最重的 flow。当从当前位置到 destination 的路还看不见时，它在 issue tracker 上绘制 **decision tickets** 的 **shared map**，逐个解决，产出 **decisions, not deliverables**，直到 fog 被推开、路径清晰。`/zh-grill-with-docs` 用于一个 session 能装下的想法，wayfinder 用于装不下的想法；它更慢、更密集，所以只应留给确实如此的 effort，绝不要用于范围明确的 feature。
+
+  Map 清晰后，**它会 hand off，而不是 build**：先进入 **`/zh-to-spec`**，把 map 中相互链接的 decisions 收束成可构建计划，然后照常使用 `/zh-to-tickets` 和 `/zh-implement`。让 map 直接循环进入 `/zh-implement` 会跳过这次收束并丢掉相互链接的细节；只有当 effort 后来发现确实很小时，才直接进入 `/zh-implement`。
+
+## Codebase health
+
+这不是 feature work，而是维护。
+
+- **`/zh-improve-codebase-architecture`** - 有空时运行，保持 codebase 适合 agents 操作。它会暴露 **deepening opportunities**；选择其中一个会生成一个 idea，可以带入 main flow 的 `/zh-grill-with-docs`。它负责找候选项；**`/zh-codebase-design`**（见下文）是你设计已选候选项时使用的工作台。
+
+## Vocabulary underneath
+
+两个 model-invoked references 在其他 skills 下层运行，分别是自己词汇的 single source of truth。问题在于**词语**而不是流程时直接用它们；也可以让上面的 skills 自动拉起它们。
+
+- **`/zh-domain-modeling`** - 打磨项目的 _domain_ language：挑战模糊术语、解决 overloaded word（例如一个 "account" 承担三件事）、把难以逆转的决策记录为 ADR。它是 `/zh-grill-with-docs` 用来保持 `CONTEXT.md` glossary 干净的主动纪律。
+- **`/zh-codebase-design`** - deep-module vocabulary（module、interface、depth、seam、adapter、leverage、locality），用于设计 module 的 _shape_：把大量 behavior 放在 clean seam 上的小 interface 后面。`/zh-tdd` 和 `/zh-improve-codebase-architecture` 都使用这套语言。
+
+## Phase boundaries
+
+**phase** 是 session 内的一段工作——grilling、implementation、QA。在它们之间的 **boundary** 处你有五个选项，而在这整张 map 中，选哪个是最模糊的决定：
+
+- **Continue** - 原地不动。不花成本，也不丢失任何东西。
+- **`/clear`** - 清空 context window，当这里的内容对接下来什么都不重要时。
+- **`/zh-handoff`** - 写一个便携 markdown 文件。范围很窄：只用于 **new harness**、**new directory**、**colleague**，或在 **阶段中途** 分叉一个 side task。它买到的是 portability。
+- **Subagent** - 把 tightly-scoped task 送到它自己的 context window，并拿回一份报告。
+- **`/compact`** - 压缩这个 context，并用 summary 播种 fresh session。它是 **default**，位于树的底部，而不是最先伸手可及的地方。
+
+关于有序的树，阅读 [PHASE-BOUNDARIES.md](PHASE-BOUNDARIES.md)：五个问题、每个分支背后的推理，以及为什么 primary-source 成本让 **Continue** 成为第一个要排除的选项。**在** boundary 处做决定；阶段中途，要么继续，要么把剩余的工作拆成 subagents。
+
+## Standalone
+
+完全在 main flow 之外。
+
+- **`/zh-grill-me`** - 与 `/zh-grill-with-docs` 一样的持续访谈，但 **stateless**：不在本地保存任何内容，也不构建 `CONTEXT.md`。当你 **不在 working directory** 中工作时使用它——打磨一个计划、一个设计、一段文字，任何没有 repo 承载的东西。如果你在 working directory 中，改用 `/zh-grill-with-docs`：它运行同样的访谈并留下文档痕迹，因此严格来说是更好的选择。
+- **`/zh-grilling`** - 访谈 primitive 本身：rounds、frontier，facts 是 agent 的工作，decisions 是你的。`/zh-grill-me` 和 `/zh-grill-with-docs` 是两个命名的入口，`/zh-triage`、`/zh-wayfinder` 和 `/zh-improve-codebase-architecture` 都在内部运行它。只有在你想要不带任何 wrapper 的访谈时才直接使用它。
+- **`/zh-resolving-merge-conflicts`** - hunk by hunk 处理进行中的 merge 或 rebase conflict，依据能追溯到每一侧 primary source 的 **intent** 来解决，而不是挑选行，然后完成操作。它从不运行 `--abort`。完全 standalone，不属于任何 flow：当你已身处 conflict 中时使用它。
+- **`/zh-prototype`** - 一个小型 throwaway program，用来回答一个设计问题：这个 state model 感觉对吗，或者这个 UI 应该是什么样。Throwaway 是对代码编写方式的约束，而不是销毁它的承诺：答案会折进真实代码，prototype 本身则作为 **primary source** 保留在 main 之外的 `prototype/<name>` branch 上，并由 implementation issue 指向。它是 main flow 第 2 步的绕行，但任何难以纸面解决的 design question 都可以直接用它。
+- **`/zh-research`** - 把阅读工作委托给 **background agent**：它对照 **primary sources** 调研问题，然后在 repo 中留下带引用的 Markdown 文件。你可以在它阅读时继续工作。产物应带入 `/zh-grill-with-docs` 的 main flow；research 提供思考材料，但不取代思考。
+- **`/zh-to-questionnaire`** - 当阻塞你的东西不在你的头脑或 codebase 里，而在 **别人的** 头脑里时，这个 skill 会写一份问卷让他们填写。它是 `/zh-grill-me` 的反向：它不访问你关于 subject，而是访问你关于 **send**——发给谁、你需要拿回什么——并把问题对准 gap。拿回来的东西是 `/zh-grill-with-docs` 或 `/zh-to-spec` 的素材。
+- **`/zh-wizard`** - 用于只有 **human** 能完成的步骤：provisioning infrastructure、设置 credentials 或 CI secrets、在陌生的第三方 dashboard 中点击操作、运行一次性 migration 或 cutover。它生成一个交互式 bash script，打开每个 URL、捕获每个值，并写入 `.env` 和 GitHub secrets——这样该过程就不再需要你每次向 agent 重新解释。它是 model-invoked 的，所以 agent 一遇到只有你能通过的墙就会伸手够它。如果 agent 自己能做，它就应该自己做；这个 skill 用于 human 真正在 loop 中的场景。
+- **`/zh-wait-what`** - 对没有落地的消息的纠正。在对话中途、任何其他 skill 内部使用它，agent 会用你缺失的 context、以 plain English、用 `CONTEXT.md` vocabulary 重新表述它刚说的话。它事后生效；`/zh-grill-with-docs` 是前置的解法，因为早早就共同约定的共享语言才是阻止 jargon 出现的根本。
+- **`/zh-teach`** - 使用当前目录作为 stateful workspace，跨多个 sessions 学习一个概念。
+- **`/zh-writing-for-agents`** - 编写 agents 消费的文档的 reference：skills、AGENTS.md、被指向的 docs。
+
+## Precondition
+
+**`/zh-setup-matt-pocock-skills`** - 第一次运行 engineering flow 前先执行，用来配置其他 skills 所依赖的 issue tracker、triage labels 和 docs layout。自定义 issue trackers 也可以。

package/skills/ask-matt/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Ask Matt"
+  short_description: "找到合适的 skill 或 workflow"
+policy:
+  allow_implicit_invocation: false

package/skills/claude-handoff/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: zh-claude-handoff
+description: 把当前对话交接给一个全新的 background agent，让它立即接手工作。
+argument-hint: "下一个 session 将用于什么？"
+disable-model-invocation: true
+---
+
+为当前对话写一份 handoff summary，让一个全新的 agent 可以继续工作。不要把它保存下来，而是启动一个以这份 summary 作为 prompt 的 background agent：`claude --bg --name "<descriptive name>" "<handoff summary>"`。它会在当前工作目录中启动并立即返回；用户用 `claude agents` 管理它。
+
+始终带上 `-n`/`--name` 并给出描述性名称（例如 `--name "Fix login bug"`）——它设置显示名称，会出现在 job list、session picker 和 terminal title 中。
+
+在 summary 中包含一个 "suggested skills" section，推荐 agent 应当调用的 skills。
+
+不要重复其它 artifacts（PRDs、plans、ADRs、issues、commits、diffs）中已经记录的内容，改为用 path 或 URL 引用它们。
+
+删去任何敏感信息，例如 API keys、passwords 或个人身份信息——这份 summary 会成为 agent 的 prompt。
+
+如果用户传入了 arguments，把它们当作对下一个 session 重点的描述，并据此调整 summary。

package/skills/claude-handoff/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Claude Handoff"
+  short_description: "把工作交给后台 agent"
+policy:
+  allow_implicit_invocation: false

package/skills/code-review/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: zh-code-review
+description: 从固定点（commit、branch、tag 或 merge-base）开始，按 Standards（代码是否符合本仓库记录的编码标准？）和 Spec（代码是否符合来源 issue/spec 的要求？）两个轴线审查变更。两个审查会在并行子代理中运行，并并排报告。适用于用户想审查 branch、PR、进行中的变更，或要求 “review since X” 时。
+---
+
+对用户提供的 fixed point 与 `HEAD` 之间的 diff 做双轴 review：
+
+- **Standards** — 代码是否符合这个 repo 记录下来的 coding standards？
+- **Spec** — 代码是否忠实实现来源 issue / spec？
+
+两个轴线都作为**并行 sub-agents**运行，避免互相污染 context；然后这个 skill 聚合它们的 findings。
+
+Issue tracker 应该已经提供给你；如果缺少 `docs/agents/issue-tracker.md`，运行 `/zh-setup-matt-pocock-skills`。
+
+## Process
+
+### 1. Pin the fixed point
+
+用户说的任何内容都是 fixed point：commit SHA、branch name、tag、`main`、`HEAD~5` 等。如果用户没有指定，就询问。
+
+先捕获一次 diff command：`git diff <fixed-point>...HEAD`（three-dot，因此比较对象是 merge-base）。同时用 `git log <fixed-point>..HEAD --oneline` 记录 commits 列表。
+
+继续前，确认 fixed point 能解析（`git rev-parse <fixed-point>`），并且 diff 非空。错误 ref 或空 diff 应该在这里失败，而不是进入两个并行 sub-agents 后才失败。
+
+### 2. Identify the spec source
+
+按以下顺序寻找来源 spec：
+
+1. Commit messages 中的 issue references（`#123`、`Closes #45`、GitLab `!67` 等）— 按 `docs/agents/issue-tracker.md` 中的 workflow 获取。
+2. 用户作为 argument 传入的 path。
+3. `docs/`、`specs/` 或 `.scratch/` 下与 branch name 或 feature 匹配的 spec 文件。
+4. 如果什么都找不到，询问用户 spec 在哪里。如果用户说没有 spec，**Spec** sub-agent 跳过并报告 “no spec available”。
+
+### 3. Identify the standards sources
+
+Repo 中任何记录代码应该如何写的内容，例如 `CODING_STANDARDS.md` 或 `CONTRIBUTING.md`。
+
+在 repo 自己记录的 standards 之外，Standards 轴线始终带有下面的 **smell baseline**：一组固定的 Fowler code smells（_Refactoring_ 第 3 章），即使 repo 没有任何约定也适用。有两条规则：
+
+- **The repo overrides.** 已记录的 repo standard 永远优先；如果它认可 baseline 会标记的东西，就压制该 smell。
+- **Always a judgement call.** 每个 smell 都是带 label 的 heuristic（例如 "possible Feature Envy"），不是硬性违规；和这里的其他 standard 一样，跳过 tooling 已经强制检查的内容。
+
+每个 smell 按 _what it is_ -> _how to fix_ 读取，并对照 diff：
+
+- **Mysterious Name** — function、variable 或 type 的名称没有说明它做什么或装什么。-> rename it；如果找不到诚实名称，设计本身可能浑浊。
+- **Duplicated Code** — 同一 logic shape 出现在多个 hunk 或 file 中。-> 抽出共享形状，让两边调用。
+- **Feature Envy** — method 访问另一个 object 的 data 多于自己的 data。-> 把 method 移到它羡慕的数据上。
+- **Data Clumps** — 同几组 fields 或 params 总是一起出现。-> 包成一个 type 来传。
+- **Primitive Obsession** — primitive 或 string 代替了值得拥有自有 type 的 domain concept。-> 给该 concept 一个小 type。
+- **Repeated Switches** — 对同一 type 的相同 `switch`/`if` cascade 在改动中重复。-> 换成 polymorphism，或共享一个 map。
+- **Shotgun Surgery** — 一个 logical change 迫使 diff 分散修改很多文件。-> 把一起变化的东西收拢进一个 module。
+- **Divergent Change** — 一个 file 或 module 因多个无关原因被修改。-> 拆分，让每个 module 只因一个原因变化。
+- **Speculative Generality** — 为 spec 没有的需求增加 abstraction、params 或 hooks。-> 删除它，inline 回来，直到有真实需要。
+- **Message Chains** — caller 不该依赖的长链式导航 `a.b().c().d()`。-> 把这段导航藏到第一个 object 的一个 method 后面。
+- **Middle Man** — class 或 function 基本只是在继续委托。-> 删掉它，直接调用真实目标。
+- **Refused Bequest** — subclass 或 implementer 忽略或 override 了继承来的大部分内容。-> 去掉 inheritance，使用 composition。
+
+### 4. Spawn both sub-agents in parallel
+
+**Standards sub-agent prompt** — 包含：
+
+- 完整 diff command 和 commit list。
+- Step 3 中找到的 standards-source files 列表，**以及 Step 3 的 smell baseline 全文**；sub-agent 没有其他方式读取它。
+- Brief："Report — per file/hunk where relevant — (a) every place the diff violates a documented standard: cite the standard (file + the rule); and (b) any baseline smell you spot: name it and quote the hunk. Distinguish hard violations from judgement calls — documented-standard breaches can be hard, but baseline smells are always judgement calls, and a documented repo standard overrides the baseline. Skip anything tooling enforces. Under 400 words."
+
+**Spec sub-agent prompt** — 包含：
+
+- Diff command 和 commit list。
+- Spec 的 path 或已获取内容。
+- Brief："Report: (a) requirements the spec asked for that are missing or partial; (b) behaviour in the diff that wasn't asked for (scope creep); (c) requirements that look implemented but where the implementation looks wrong. Quote the spec line for each finding. Under 400 words."
+
+如果缺少 spec，跳过 Spec sub-agent，并在最终报告中说明。
+
+### 5. Aggregate
+
+在 `## Standards` 和 `## Spec` headings 下展示两个 reports，可原样或轻微清理。**不要**合并或重新排序 findings；这两个轴线刻意保持分离（见 _Why two axes_）。
+
+最后用一行总结：每个轴线的 findings 总数，以及每个轴线内最严重的问题（如果有）。不要跨轴线选一个总冠军；分离就是为了避免这种 reranking。
+
+## Why two axes
+
+一个变更可能通过其中一个轴线，但失败在另一个轴线：
+
+- 代码符合所有 standard，但实现了错误的东西 -> **Standards pass, Spec fail.**
+- 代码完全符合 issue 要求，但破坏了项目约定 -> **Spec pass, Standards fail.**
+
+分开报告能避免一个轴线掩盖另一个轴线。

package/skills/code-review/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Code Review"
+  short_description: "按规范和 spec 审查 diff"

package/skills/codebase-design/DEEPENING.md

@@ -0,0 +1,37 @@
+# Deepening
+
+在已知 dependencies 的情况下，安全地深化一组 shallow modules。本文件假设你已经使用 [SKILL.md](SKILL.md) 中的词汇：**module**、**interface**、**seam**、**adapter**。
+
+## Dependency categories
+
+评估 deepening candidate 时，先分类它的 dependencies。分类决定 deepened module 如何跨 seam 测试。
+
+### 1. In-process
+
+纯计算、内存状态、无 I/O。总是可以 deepen：合并 modules，并直接通过新的 interface 测试。不需要 adapter。
+
+### 2. Local-substitutable
+
+有本地 test stand-ins 的 dependencies（例如 Postgres 的 PGLite、in-memory filesystem）。如果 stand-in 存在，就可以 deepen。Deepened module 在 test suite 中带着 stand-in 一起测试。seam 是 internal 的；module external interface 上不需要 port。
+
+### 3. Remote but owned (Ports & Adapters)
+
+你拥有的跨网络服务（microservices、internal APIs）。在 seam 上定义 **port**（interface）。Deep module 拥有 logic；transport 作为 **adapter** 注入。Tests 使用 in-memory adapter。Production 使用 HTTP/gRPC/queue adapter。
+
+推荐形状：*"Define a port at the seam, implement an HTTP adapter for production and an in-memory adapter for testing, so the logic sits in one deep module even though it's deployed across a network."*
+
+### 4. True external (Mock)
+
+你无法控制的第三方服务（Stripe、Twilio 等）。Deepened module 把外部 dependency 作为 injected port；tests 提供 mock adapter。
+
+## Seam discipline
+
+- **One adapter means a hypothetical seam. Two adapters means a real one.** 除非至少有两个 adapters 合理存在（通常是 production + test），否则不要引入 port。单 adapter seam 只是 indirection。
+- **Internal seams vs external seams。** Deep module 可以有 internal seams（implementation 私有，供自身 tests 使用），也可以有 interface 上的 external seam。不要只因为 tests 使用 internal seams，就把它们暴露到 interface。
+
+## Testing strategy: replace, don't layer
+
+- 一旦 deepened module interface 上有了 tests，旧的 shallow modules unit tests 就变成 waste，删除它们。
+- 在 deepened module 的 interface 上写新 tests。**Interface is the test surface**。
+- Tests 通过 interface 断言 observable outcomes，而不是 internal state。
+- Tests 应能承受 internal refactors；它们描述 behavior，不描述 implementation。若 implementation 改动会迫使 test 改动，那就是在越过 interface 测试。

package/skills/codebase-design/DESIGN-IT-TWICE.md

@@ -0,0 +1,44 @@
+# Design It Twice
+
+当用户想为某个 deepening candidate 探索 alternative interfaces 时，使用这个并行 sub-agent pattern。它基于 Ousterhout 的 "Design It Twice"：你的第一个想法很可能不是最好的。
+
+使用 [SKILL.md](SKILL.md) 中的词汇：**module**、**interface**、**seam**、**adapter**、**leverage**。
+
+## Process
+
+### 1. Frame the problem space
+
+在启动 sub-agents 之前，先为选中的 candidate 写一段面向用户的问题空间说明：
+
+- 新 interface 需要满足的 constraints
+- 它会依赖哪些 dependencies，以及这些 dependencies 属于哪一类（见 [DEEPENING.md](DEEPENING.md)）
+- 一个粗略的 illustrative code sketch，用来让 constraints 具体化；这不是 proposal，只是帮助理解约束
+
+把这些展示给用户，然后立即进入 Step 2。用户可以一边读一边思考，sub-agents 同时并行工作。
+
+### 2. Spawn sub-agents
+
+并行启动 3+ 个 sub-agents。每个都必须为 deepened module 产出一个 **radically different** interface。
+
+给每个 sub-agent 单独的 technical brief（file paths、coupling details、来自 [DEEPENING.md](DEEPENING.md) 的 dependency category、seam 后面是什么）。这个 brief 独立于 Step 1 的用户-facing problem-space explanation。给每个 agent 不同的 design constraint：
+
+- Agent 1: "Minimize the interface - aim for 1-3 entry points max. Maximise leverage per entry point."
+- Agent 2: "Maximise flexibility - support many use cases and extension."
+- Agent 3: "Optimise for the most common caller - make the default case trivial."
+- Agent 4（如适用）: "Design around ports & adapters for cross-seam dependencies."
+
+Brief 中同时包含 [SKILL.md](SKILL.md) vocabulary 和 `CONTEXT.md` vocabulary，确保每个 sub-agent 的命名同时符合 architecture language 和项目 domain language。
+
+每个 sub-agent 输出：
+
+1. Interface（types、methods、params，以及 invariants、ordering、error modes）
+2. Usage example，展示 callers 如何使用它
+3. Implementation 在 seam 后隐藏了什么
+4. Dependency strategy 和 adapters（见 [DEEPENING.md](DEEPENING.md)）
+5. Trade-offs：leverage 哪里高，哪里薄
+
+### 3. Present and compare
+
+顺序展示各个 designs，让用户能逐个吸收，然后用 prose 比较。按 **depth**（interface 上的 leverage）、**locality**（change 集中在哪里）和 **seam placement** 对比。
+
+比较后，给出你的推荐：你认为哪个 design 最强，以及为什么。如果不同 designs 的元素可以组合，提出 hybrid。要有观点；用户需要强判断，不是菜单。