@heihei0299/matt-skills 1.6.2 → 1.6.3

package/README.md

@@ -8,7 +8,7 @@ mattpocock/skills（`skills/engineering` + `skills/productivity`）的配置仓
 template/
 ├── AGENTS.md         项目级全局配置（行为路由 + 分文件指针）
 ├── .agents/
-│   └── skills/       32 个技能（上游 26 + 独有 6：ci-guard、tdd-implement、grill-to-spec、diagnose-fix、commit-check、scaffold-functional-test）单一源；模板全量 32，默认安装仅编程相关 22（engineering 18 + 核心独有 4，见 config/engineering.json），--all 展开全量
+│   └── skills/       32 个技能（上游 26 + 独有 6：ci-guard、tdd-implement、grill-to-spec、diagnose-fix、commit-check、scaffold-functional-test）单一源；模板全量 32，默认安装编程相关 23（engineering 18 + 独有所需 1 + 核心独有 4，见 config/engineering.json 与 config/required.json），--all 展开全量
 ├── .pi/              pi-agent 项目配置
 │   ├── skills/       空占位（项目自定义技能，含 .gitkeep + README.md）
 │   ├── prompts/      issue-audit 命令（prompt template）
@@ -29,17 +29,17 @@ template/
 在目标仓库根目录执行一条命令：
 
 ```sh
-npx @heihei0299/matt-skills init              # 默认仅编程相关 21（engineering + 独有），--all 展开全量 32
+npx @heihei0299/matt-skills init              # 默认编程相关 23（engineering 18 + 独有所需 1 + 核心独有 4），--all 展开全量 32
 npx @heihei0299/matt-skills init --all       # 安装全量 32（含 productivity）
 ```
 
-`init` 做一件事：复制 `template/` 快照（`AGENTS.md`、`.agents/skills/`、`.opencode/`、`.pi/`）到当前目录；模板全量 32，默认仅安装编程相关 24（上游 engineering 桶，见 config/engineering.json + 独有 6），`--all` 展开全量，无需二次拉取上游。
+`init` 做一件事：复制 `template/` 快照（`AGENTS.md`、`.agents/skills/`、`.opencode/`、`.pi/`）到当前目录；模板全量 32，默认仅安装默认范围 23（engineering 18 + 独有所需 1 + 核心独有 4，见 config/engineering.json 与 config/required.json），`--all` 展开全量，无需二次拉取上游。
 
-选项：`--dest <path>` 指定目标目录（默认当前目录）；`--force` 覆盖已存在的文件（直接覆盖，`AGENTS.md` 会备份到 `.bak`）（默认跳过）；`--all` 包含非编程技能（productivity，默认仅编程）。
+选项：`--dest <path>` 指定目标目录（默认当前目录）；`--force` 覆盖已存在的文件（直接覆盖，`AGENTS.md` 会备份到 `.bak`）（默认跳过）；`--all` 包含非编程技能（productivity，默认编程 23：engineering 18 + 独有所需 1 + 核心独有 4）。
 **增量同步（已有项目）**：已有项目更新到最新模板与技能：
 
 ```sh
-npx @heihei0299/matt-skills sync                                 # 默认仅对比不写盘（check），有差异 exit 1，--json 可解析（仅编程）
+npx @heihei0299/matt-skills sync                                 # 默认仅对比不写盘（check），有差异 exit 1，--json 可解析（默认范围）
 npx @heihei0299/matt-skills sync --all --json                  # 全量对比
 npx @heihei0299/matt-skills sync --apply                         # 安全增量：AGENTS.md 定制跳过，编程技能 rm+cp，不删多余 productivity（默认保留）
 npx @heihei0299/matt-skills sync --apply --all                  # 安全增量全量
@@ -48,8 +48,8 @@ npx @heihei0299/matt-skills sync --force --all                  # 硬盖全量
 npx @heihei0299/matt-skills sync --apply --dest <path> --upstream <url> --ref <ref> --json  # 选项可组合
 ```
 
-`sync` 专为已有项目设计，三档语义：默认 `check` 仅对比不写盘（仅编程，`--all` 展开全量，打印“上游 HEAD / 本地非独有 vs 上游 / 新增/更新/删除/一致”表，`--json` 可解析，有差异 `exit 1`）；`--apply` 安全增量写盘（编程模式：`AGENTS.md` 若含独有路由如 `tdd-implement` 则跳过，`.agents/skills` 按编程子集 `rm+cp force` 覆盖但不 `remove` 多余 productivity，`template/.agents/.opencode/.pi` 按过滤增量 `add/update`，旧镜像 `.pi/skills` + `.opencode/skills` 中残留的共享技能自动清理但保留项目自定义；`--all` 则全量）；`--force` 硬盖（编程模式：`AGENTS.md` 备份 `.bak` 后强制覆盖，编程技能 `add/update/remove` 全做（含 productivity 删除与旧镜像清理）；`--all` 则全量硬盖）。`--dest`、`--upstream`、`--ref`、`--json`、`--all` 在三档均可透传。
-目标仓库会话即自动加载共享技能（`.agents/skills/` 单一源，默认编程 22，`--all` 全量 32）与项目级全局配置（行为路由表、分文件约定）；项目自定义技能可按需放入 `.pi/skills/` 或 `.opencode/skills/`（按 harness 自动发现）；`issue-audit` 以子代理 + 命令形式分发（`.opencode/agents/`、`.opencode/commands/`）；9 个显式触发技能注册为 opencode 命令（`.opencode/commands/`，`/命令名` 触发）。
+`sync` 专为已有项目设计，三档语义：默认 `check` 仅对比不写盘（默认范围 engineering + 独有所需，`--all` 展开全量，打印“上游 HEAD / 本地非独有 vs 上游 / 新增/更新/删除/一致”表，`--json` 可解析，有差异 `exit 1`）；`--apply` 安全增量写盘（默认模式：`AGENTS.md` 若含独有路由如 `tdd-implement` 则跳过，`.agents/skills` 按默认子集 `rm+cp force` 覆盖但不 `remove` 范围外 productivity，`template/.agents/.opencode/.pi` 按过滤增量 `add/update`，旧镜像 `.pi/skills` + `.opencode/skills` 中残留的共享技能自动清理但保留项目自定义；`--all` 则全量）；`--force` 硬盖（默认模式：`AGENTS.md` 备份 `.bak` 后强制覆盖，默认技能 `add/update/remove` 全做（含范围外 productivity 删除与旧镜像清理）；`--all` 则全量硬盖）。`--dest`、`--upstream`、`--ref`、`--json`、`--all` 在三档均可透传。
+目标仓库会话即自动加载共享技能（`.agents/skills/` 单一源，默认编程 23，`--all` 全量 32）与项目级全局配置（行为路由表、分文件约定）；项目自定义技能可按需放入 `.pi/skills/` 或 `.opencode/skills/`（按 harness 自动发现）；`issue-audit` 以子代理 + 命令形式分发（`.opencode/agents/`、`.opencode/commands/`）；9 个显式触发技能注册为 opencode 命令（`.opencode/commands/`，`/命令名` 触发）。
 **pi-agent 用户**：初始化命令完全相同。pi 从 `.agents/skills/` 自动发现全部共享技能，无需额外指向；`.pi/skills/` 仅用于项目自定义。首次在目标仓库交互启动时 pi 会询问项目信任，用 `/trust` 保存即可。
 
 **手动方式（备选）**：无 npx 环境时，将 `template/` 整个文件夹复制到目标仓库根目录即可（已含全量技能）：
@@ -103,13 +103,13 @@ pi 下对应能力以内置工具或已装扩展为准（`AGENTS.md`「能力边
 
 - **全局**：`~/.pi/agent/skills/`、`~/.agents/skills/`（用户级技能，自动发现）；配置在 `~/.pi/agent/settings.json`
 - **项目**：
-  - `.agents/skills/` — 共享技能单一源（默认编程 22，`--all` 全量 32，自动发现）
+  - `.agents/skills/` — 共享技能单一源（默认编程 23，`--all` 全量 32，自动发现）
   - `.pi/skills/` — 项目自定义技能（pi 标准结构，自动发现，仅放项目本地技能）
   - `.pi/prompts/` — pi 命令（prompt template）自动发现，如 `issue-audit.md` → `/issue-audit`
   - `.pi/settings.json` — 已简化为空对象（历史指向 `.opencode/skills` 已移除，共享技能走 `.agents/skills`）
 ### opencode
 
-- **项目**：`.agents/skills/`（共享技能单一源，默认编程 22，`--all` 全量 32）、`.opencode/skills/`（项目自定义技能）、`.opencode/agents/`（子代理）、`.opencode/commands/`（命令：issue-audit + 9 个显式触发技能，`/命令名` 触发）、`.opencode/docs/`（文档）
+- **项目**：`.agents/skills/`（共享技能单一源，默认编程 23，`--all` 全量 32）、`.opencode/skills/`（项目自定义技能）、`.opencode/agents/`（子代理）、`.opencode/commands/`（命令：issue-audit + 9 个显式触发技能，`/命令名` 触发）、`.opencode/docs/`（文档）
 
 同一份技能（Agent Skills 标准）与 `AGENTS.md` 行为路由在两种 harness 下均可加载：pi 与 codex/claude 从 `.agents/skills/` 自动发现；opencode 按本模板约定同样优先读取 `.agents/skills/`（`.opencode/skills/` 仅用于项目自定义）。
 
@@ -118,23 +118,23 @@ pi 下对应能力以内置工具或已装扩展为准（`AGENTS.md`「能力边
 仓库内提供安装管理 CLI（`bin/cli.js`，依赖 `prompts`，见 `package.json`），同时作为 npm 包 `@heihei0299/matt-skills` 分发（`npx @heihei0299/matt-skills <command>`）：
 
 ```sh
-node bin/cli.js init [--dest <dir>] [--force] [--all]                               # 初始化项目：template 全量 32，默认编程 22
+node bin/cli.js init [--dest <dir>] [--force] [--all]                               # 初始化项目：template 全量 32，默认编程 23
 node bin/cli.js sync [--apply|--force] [--all] [--dest <path>] [--upstream <url>] [--ref <ref>] [--json]  # 同步已有项目到最新（默认编程）
 node bin/cli.js list [--json] [--all]                                            # 列出技能（默认编程）
 node bin/cli.js install [选项]                                                 # 把技能复制到目标工具目录（交互式选择，默认编程）
-node bin/cli.js check [--json] [--all] [--upstream <url>] [--ref <ref>]          # 只读检查上游技能是否最新（等价 sync 默认，仅编程）
+node bin/cli.js check [--json] [--all] [--upstream <url>] [--ref <ref>]          # 只读检查上游技能是否最新（等价 sync 默认，默认范围）
 ```
 
-`init` 选项：`--dest <path>` 指定目标目录（默认当前目录）；`--force` 覆盖已存在的文件（直接覆盖，`AGENTS.md` 会备份到 `.bak`）（默认跳过）；`--all` 包含非编程（productivity，默认仅编程 22），见「初始化」。
-`sync` 选项：`--apply` 安全增量（编程默认：`AGENTS.md` 定制跳过、编程技能不删 productivity，旧镜像清理保留项目自定义；`--all` 全量），`--force` 硬盖（编程默认：`AGENTS.md` 备份后硬盖、编程技能与模板全量 `remove` 含 productivity 删除与旧镜像清理；`--all` 全量）；`--all` 展开全量；`--dest <path>` 目标目录；`--upstream <url>` 上游地址；`--ref <ref>` 上游分支；`--json` JSON 输出；默认无参等价 `check` 仅对比不写盘（仅编程，`--all` 全量），`--json` 可解析，有差异 `exit 1`。
-`check` 选项：`--json`、`--all`（默认仅编程）、`--upstream <url>`、`--ref <ref>`（等价 `sync` 默认 `check`）。
+`init` 选项：`--dest <path>` 指定目标目录（默认当前目录）；`--force` 覆盖已存在的文件（直接覆盖，`AGENTS.md` 会备份到 `.bak`）（默认跳过）；`--all` 包含非编程（productivity，默认编程 23：engineering 18 + 独有所需 1 + 核心独有 4），见「初始化」。
+`sync` 选项：`--apply` 安全增量（默认模式：`AGENTS.md` 定制跳过、默认技能不删范围外 productivity，旧镜像清理保留项目自定义；`--all` 全量），`--force` 硬盖（默认模式：`AGENTS.md` 备份后硬盖、默认技能与模板全量 `remove` 含范围外 productivity 删除与旧镜像清理；`--all` 全量）；`--all` 展开全量；`--dest <path>` 目标目录；`--upstream <url>` 上游地址；`--ref <ref>` 上游分支；`--json` JSON 输出；默认无参等价 `check` 仅对比不写盘（默认范围，`--all` 全量），`--json` 可解析，有差异 `exit 1`。
+`check` 选项：`--json`、`--all`（默认范围：engineering + 独有所需）、`--upstream <url>`、`--ref <ref>`（等价 `sync` 默认 `check`）。
 
 `install` 选项：
 
 - `--dest <dir>`：复制到指定目录（覆盖工具映射）
 - `--tools <t1,t2>`：指定工具，项目级已统一 `codex/pi/opencode/claude → .agents/skills`（共享技能单一源，`.pi/skills`/`.opencode/skills` 仅用于项目自定义）
 - `--global`：安装到全局目录（`~/.codex/skills`、`~/.pi/agent/skills`、`~/.config/opencode/skills`、`~/.claude/skills`）；`--project` 回到项目级
-- `--all`：安装全部技能（默认仅编程 22，`--all` 32，交互勾选时仅列编程）；`--force`：覆盖已存在的技能
+- `--all`：安装全部技能（默认编程 23，`--all` 32，交互勾选时仅列默认范围）；`--force`：覆盖已存在的技能
 
 
 ### 上游同步（自动更新）
@@ -153,7 +153,7 @@ node scripts/sync-upstream.js --check               # 等价底层脚本（CLI s
 node scripts/sync-upstream.js --apply --dry-run
 ```
 
-实现细节：`scripts/sync-upstream.js` 为单一事实源（CLI 与 Actions 共用），以 `config/proprietary.json` 为独有白名单 + `config/engineering.json` 为编程白名单（engineering 桶即编程，productivity 默认不装，`--all` 展开），上游通过 `git clone --depth 1 https://github.com/mattpocock/skills.git` 获取，比对 `SKILL.md` 的 sha256，自动处理新增/更新/重命名/删除；Actions 提 PR 后需人工合入，合入后按“发布”节打 `v*` 标签即发布（自动 patch 发版可在后续扩展为 PR 合入后自动 bump）。
+实现细节：`scripts/sync-upstream.js` 为单一事实源（CLI 与 Actions 共用），以 `config/proprietary.json` 为独有白名单 + `config/engineering.json` 为编程白名单 + `config/required.json` 为独有所需白名单（当前仅 grilling：grill-to-spec 经 grill-with-docs 所需，属 productivity 但默认同步；其余 productivity 默认不装，`--all` 展开），上游通过 `git clone --depth 1 https://github.com/mattpocock/skills.git` 获取，比对 `SKILL.md` 的 sha256，自动处理新增/更新/重命名/删除；Actions 提 PR 后需人工合入，合入后按“发布”节打 `v*` 标签即发布（自动 patch 发版可在后续扩展为 PR 合入后自动 bump）。
 上游重命名映射：`RENAMES = { "writing-great-skills": "writing-for-agents" }`，Actions/CLI 均会删除旧目录并复制新目录。
 ## 发布
 

package/bin/cli.js

@@ -10,6 +10,7 @@ const TEMPLATE_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..
 const PROPRIETARY_SKILLS = new Set(['ci-guard', 'tdd-implement', 'grill-to-spec', 'diagnose-fix', 'commit-check', 'scaffold-functional-test']);
 const PROPRIETARY_DEFAULT = new Set(['tdd-implement', 'diagnose-fix', 'commit-check', 'grill-to-spec']); // 默认仅装核心 3，--all 才装全部 6
 const ENGINEERING_PATH = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'config', 'engineering.json');
+const REQUIRED_PATH = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'config', 'required.json');
 let ENGINEERING_SKILLS = null;
 async function loadEngineeringSkills() {
   if (ENGINEERING_SKILLS) return ENGINEERING_SKILLS;
@@ -21,8 +22,19 @@ async function loadEngineeringSkills() {
   }
   return ENGINEERING_SKILLS;
 }
-function isProgrammingSkill(name, engineering) {
-  return PROPRIETARY_DEFAULT.has(name) || engineering.has(name);
+let REQUIRED_SKILLS = null;
+async function loadRequiredSkills() {
+  if (REQUIRED_SKILLS) return REQUIRED_SKILLS;
+  try {
+    const raw = await readFile(REQUIRED_PATH, 'utf8');
+    REQUIRED_SKILLS = new Set(JSON.parse(raw));
+  } catch {
+    REQUIRED_SKILLS = new Set(['grilling']);
+  }
+  return REQUIRED_SKILLS;
+}
+function isProgrammingSkill(name, engineering, required) {
+  return PROPRIETARY_DEFAULT.has(name) || engineering.has(name) || (required && required.has(name));
 }
 function isProgrammingAll(name, engineering) {
   return PROPRIETARY_SKILLS.has(name) || engineering.has(name);
@@ -53,7 +65,7 @@ Usage:
 Init options:
   --dest <path>   Target directory (default: current directory)
   --force         Overwrite existing files
-  --all           Include non-programming skills (productivity) and optional proprietary; default only core programming (engineering 18 + default proprietary 4 → 22)
+  --all           Include non-programming skills (productivity) and optional proprietary; default only core programming (engineering 18 + required 1 + default proprietary 4 → 23)
   --help, -h      Show this help
 
 提示：matt-skills --help 查看全量
@@ -65,13 +77,13 @@ Usage:
   matt-skills sync [--all|--force|--dry-run] [--dest <path>]
 
 Sync options:
-  --all           范围：含非编程与可选独有（默认仅编程 22）
+  --all           范围：含非编程与可选独有（默认编程 23：engineering 18 + 独有所需 1 + 核心独有 4）
   --force         力度：硬盖（备份 .bak + 删多余，全量 add/update/remove）
   --dry-run       预演：只比对不写盘
   --dest <path>   Target directory (default: current directory)
   --help, -h      Show this help
 
-说明：默认不带参即安全增量同步默认技能（22）；--all 与 --force 互斥。
+说明：默认不带参即安全增量同步默认技能（23）；--all 与 --force 互斥。
 
 提示：matt-skills --help 查看全量
 `;
@@ -82,7 +94,7 @@ Usage:
   matt-skills list [--all] [--json]
 
 List options:
-  --all           List all skills (default only core programming 22)
+  --all           List all skills (default only core programming 23)
   --json          Output as JSON
   --help, -h      Show this help
 
@@ -95,7 +107,7 @@ Usage:
   matt-skills check [--all] [--json] [--upstream <url>] [--ref <ref>]
 
 Check options:
-  --all           Include non-programming and optional proprietary; default only core programming (22)
+  --all           Include non-programming and optional proprietary; default only core programming (23: engineering 18 + required 1 + default proprietary 4)
   --json          Output as JSON
   --upstream <url> Upstream repo URL (default: https://github.com/mattpocock/skills.git)
   --ref <ref>     Upstream ref (default: HEAD)
@@ -111,7 +123,7 @@ Usage:
 
 Install options:
   --tools <a,b>   Install for the given tools (codex, pi, opencode, claude); skips tool selection — 共享技能统一指向 .agents/skills，.pi/skills/.opencode/skills 仅用于项目自定义
-  --all           Install all skills (default only core programming 22); skips skill selection
+  --all           Install all skills (default only core programming 23); skips skill selection
   --force         Overwrite existing skills
   --global        Install to the user's global skill directories
   --project       Install to project skill directories (default)
@@ -143,12 +155,14 @@ async function listSkills({ onlyProgramming = false } = {}) {
   const entries = await readdir(SKILLS_DIR, { withFileTypes: true });
   const skills = [];
   let engineering = null;
+  let required = null;
   if (onlyProgramming) engineering = await loadEngineeringSkills();
+  if (onlyProgramming) required = await loadRequiredSkills();
   for (const entry of entries) {
     if (!entry.isDirectory()) continue;
     if (entry.name.endsWith('.bak')) continue;
     if (entry.name === 'skill-creator') continue;
-    if (onlyProgramming && !isProgrammingSkill(entry.name, engineering)) continue;
+    if (onlyProgramming && !isProgrammingSkill(entry.name, engineering, required)) continue;
     let content;
     try {
       content = await readFile(path.join(SKILLS_DIR, entry.name, 'SKILL.md'), 'utf8');
@@ -225,8 +239,9 @@ async function promptSkills(skills) {
 async function installCommand({ dest, all, force, tools, global }) {
   const onlyProgramming = !all;
   const engineering = onlyProgramming ? await loadEngineeringSkills() : null;
+  const required = onlyProgramming ? await loadRequiredSkills() : null;
   const skillsAll = await listSkills({ onlyProgramming: false });
-  const skills = onlyProgramming ? skillsAll.filter(s => isProgrammingSkill(s.name, engineering)) : skillsAll;
+  const skills = onlyProgramming ? skillsAll.filter(s => isProgrammingSkill(s.name, engineering, required)) : skillsAll;
   let targets;
   if (dest) {
     targets = [{ tool: null, dir: path.resolve(process.cwd(), dest) }];
@@ -290,16 +305,17 @@ async function initCommand({ dest, force, all }) {
       await cp(TEMPLATE_DIR, target, { recursive: true, force: true });
       process.stdout.write('模板：已复制（AGENTS.md、.agents/skills、.opencode/、.pi/）\n');
     }
-    // 默认仅编程（engineering + proprietary），--all 才保留 productivity
+    // 默认范围（engineering + 独有所需 + 默认独有），--all 才保留其余 productivity
     if (onlyProgramming && path.resolve(target) !== path.resolve(path.join(path.dirname(fileURLToPath(import.meta.url)), '..'))) {
       const engineering = await loadEngineeringSkills();
+      const required = await loadRequiredSkills();
       const skillsDirFilter = path.join(target, '.agents', 'skills');
       try {
         const entries = await readdir(skillsDirFilter, { withFileTypes: true });
         for (const e of entries) {
           if (!e.isDirectory()) continue;
           if (e.name.endsWith('.bak') || e.name === '.git' || e.name === 'skill-creator') continue;
-          if (!isProgrammingSkill(e.name, engineering)) {
+          if (!isProgrammingSkill(e.name, engineering, required)) {
             await rm(path.join(skillsDirFilter, e.name), { recursive: true, force: true });
           }
         }
@@ -315,9 +331,10 @@ async function initCommand({ dest, force, all }) {
   } catch {}
   const allSkillsFull = await listSkills({ onlyProgramming: false });
   const engineeringForStats = await loadEngineeringSkills();
-  const programmingCount = allSkillsFull.filter(s => isProgrammingSkill(s.name, engineeringForStats)).length;
+  const requiredForStats = await loadRequiredSkills();
+  const programmingCount = allSkillsFull.filter(s => isProgrammingSkill(s.name, engineeringForStats, requiredForStats)).length;
   const upstreamFull = allSkillsFull.filter((s) => !PROPRIETARY_SKILLS.has(s.name)).length;
-  const upstreamProg = allSkillsFull.filter((s) => !PROPRIETARY_SKILLS.has(s.name) && engineeringForStats.has(s.name)).length;
+  const upstreamProg = allSkillsFull.filter((s) => !PROPRIETARY_SKILLS.has(s.name) && (engineeringForStats.has(s.name) || requiredForStats.has(s.name))).length;
   const displayTotal = onlyProgramming ? programmingCount : allSkillsFull.length;
   const displayUpstream = onlyProgramming ? upstreamProg : upstreamFull;
   if (path.resolve(skillsDir) === path.resolve(SKILLS_DIR)) {
@@ -339,7 +356,7 @@ async function syncCommand({ dest, force, all, dryRun, json, upstreamUrl, ref })
     if (json) {
       process.stdout.write(JSON.stringify({ head: cmp.head, counts: cmp.counts, result: cmp.result, onlyProgramming }, null, 2) + '\n');
     } else {
-      const modeHint = onlyProgramming ? '（仅编程）' : '（全量）';
+      const modeHint = onlyProgramming ? '（默认：engineering + 独有所需）' : '（全量）';
       const lines = [];
       lines.push(`上游 HEAD: ${cmp.head}`);
       lines.push(`本地非独有: ${cmp.counts.local}  上游: ${cmp.counts.upstream} ${modeHint}`);
@@ -364,13 +381,13 @@ async function syncCommand({ dest, force, all, dryRun, json, upstreamUrl, ref })
 
   const target = dest ? path.resolve(process.cwd(), dest) : process.cwd();
   const marker = path.join(target, 'AGENTS.md');
-  // 模板同步：仅编程模式下过滤 skills，仅同步 programming 子集
+  // 模板同步：默认模式下过滤 skills，仅同步默认子集
   async function copyTemplateFiltered() {
     if (!onlyProgramming) {
       await cp(TEMPLATE_DIR, target, { recursive: true, force: true });
       return;
     }
-    // 仅编程：分别复制非 skills 部分，skills 由后续 allSkills 循环处理
+    // 默认范围：分别复制非 skills 部分，skills 由后续 allSkills 循环处理
     await cp(path.join(TEMPLATE_DIR, 'AGENTS.md'), path.join(target, 'AGENTS.md'), { force: true });
     await cp(path.join(TEMPLATE_DIR, '.opencode'), path.join(target, '.opencode'), { recursive: true, force: true });
     await cp(path.join(TEMPLATE_DIR, '.pi'), path.join(target, '.pi'), { recursive: true, force: true });
@@ -429,13 +446,14 @@ async function syncCommand({ dest, force, all, dryRun, json, upstreamUrl, ref })
       process.stdout.write('模板：已同步（AGENTS.md、.agents/skills、.opencode/、.pi/）\n');
     }
   }
-  // 技能同步：按编程过滤（默认仅编程，--all 全量）
+  // 技能同步：按默认范围过滤（engineering + 独有所需 + 默认独有，--all 全量）
   const entries = await readdir(SKILLS_DIR, { withFileTypes: true });
   const allNames = entries.filter((e) => e.isDirectory() && !e.name.endsWith('.bak') && e.name !== 'skill-creator' && e.name !== '.git').map((e) => e.name);
   let allSkills = allNames.sort();
   if (onlyProgramming) {
     const engineering = await loadEngineeringSkills();
-    allSkills = allSkills.filter(n => isProgrammingSkill(n, engineering));
+    const required = await loadRequiredSkills();
+    allSkills = allSkills.filter(n => isProgrammingSkill(n, engineering, required));
   }
   const skillsDir = path.join(target, '.agents', 'skills');
   await mkdir(skillsDir, { recursive: true });
@@ -458,7 +476,7 @@ async function syncCommand({ dest, force, all, dryRun, json, upstreamUrl, ref })
       installed++;
     }
   }
-  // --force 时删除多余；仅编程模式下多余指不在编程集合中的，--all 模式下多余指不在全量中的
+  // --force 时删除多余；默认模式下多余指不在默认集合中的，--all 模式下多余指不在全量中的
   // 默认安全增量保留多余（不删除），符合“默认保留、--force 删除”
   if (force) {
     let localEntries = [];
@@ -595,16 +613,18 @@ async function checkCommand(args) {
   const json = args.includes('--json');
   const onlyProgramming = !args.includes('--all');
   const upstreamIdx = args.indexOf('--upstream');
-  const upstreamUrl = upstreamIdx !== -1 ? args[upstreamIdx + 1] : undefined;
+  const upstreamEq = args.find((x) => x.startsWith('--upstream='));
+  const upstreamUrl = upstreamIdx !== -1 ? args[upstreamIdx + 1] : (upstreamEq ? upstreamEq.slice('--upstream='.length) : undefined);
   const refIdx = args.indexOf('--ref');
-  const ref = refIdx !== -1 ? args[refIdx + 1] : undefined;
+  const refEq = args.find((x) => x.startsWith('--ref='));
+  const ref = refIdx !== -1 ? args[refIdx + 1] : (refEq ? refEq.slice('--ref='.length) : undefined);
   const cmp = await compare({ upstreamUrl, ref, onlyProgramming });
   if (json) {
     process.stdout.write(JSON.stringify({ head: cmp.head, counts: cmp.counts, result: cmp.result, onlyProgramming }, null, 2) + '\n');
   } else {
     const lines = [];
     lines.push(`上游 HEAD: ${cmp.head}`);
-    const modeHint = onlyProgramming ? '（仅编程）' : '（全量）';
+    const modeHint = onlyProgramming ? '（默认：engineering + 独有所需）' : '（全量）';
     lines.push(`本地非独有: ${cmp.counts.local}  上游: ${cmp.counts.upstream} ${modeHint}`);
     lines.push('');
     const totalDiff = cmp.result.added.length + cmp.result.updated.length + cmp.result.removed.length + cmp.result.renamed.length;
@@ -695,10 +715,11 @@ async function main() {
   }
   if (command === 'check') {
     // check strict: allow --all/--json/--upstream/--ref/--help
-    for (const a of rest) {
+    for (let i = 0; i < rest.length; i++) {
+      const a = rest[i];
       if (a === '--all' || a === '--json' || a === '--help' || a === '-h') continue;
-      if (a === '--upstream' || a.startsWith('--upstream=')) continue;
-      if (a === '--ref' || a.startsWith('--ref=')) continue;
+      if (a === '--upstream' || a === '--ref') { i++; continue; }
+      if (a.startsWith('--upstream=') || a.startsWith('--ref=')) continue;
       if (a.startsWith('-')) { process.stderr.write(`error: unknown option '${a}' for command 'check'\n`); process.stderr.write(`Run 'matt-skills check --help' for usage.\n`); process.exitCode = 1; return; }
       process.stderr.write(`error: unknown argument '${a}' for command 'check'\n`); process.stderr.write(`Run 'matt-skills check --help' for usage.\n`); process.exitCode = 1; return;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heihei0299/matt-skills",
-  "version": "1.6.2",
+  "version": "1.6.3",
   "description": "Agent skills + 项目配置模板：一条命令初始化 opencode / pi-agent 项目（含 mattpocock/skills 上游技能）",
   "type": "module",
   "bin": {

package/scripts/sync-upstream.js

@@ -10,6 +10,7 @@ const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const LOCAL_SKILLS_DIR = path.join(ROOT, '.agents', 'skills');
 const PROPRIETARY_PATH = path.join(ROOT, 'config', 'proprietary.json');
 const ENGINEERING_PATH = path.join(ROOT, 'config', 'engineering.json');
+const REQUIRED_PATH = path.join(ROOT, 'config', 'required.json');
 const UPSTREAM_URL = 'https://github.com/mattpocock/skills.git';
 
 // 重命名映射：上游已重命名，本地旧名需迁移
@@ -34,6 +35,14 @@ async function loadEngineering() {
     return new Set(['ask-matt','code-review','codebase-design','diagnosing-bugs','domain-modeling','grill-with-docs','implement','improve-codebase-architecture','prototype','research','resolving-merge-conflicts','setup-matt-pocock-skills','tdd','to-spec','to-tickets','triage','wayfinder','wizard']);
   }
 }
+async function loadRequired() {
+  try {
+    const raw = await readFile(REQUIRED_PATH, 'utf8');
+    return new Set(JSON.parse(raw));
+  } catch {
+    return new Set(['grilling']);
+  }
+}
 
 async function hashFile(filePath) {
   const buf = await readFile(filePath);
@@ -120,12 +129,14 @@ export async function compare({ upstreamUrl, tmpDir, ref, onlyProgramming = true
   const upstreamRoot = fetched.dest;
   const upstreamMapFull = await collectUpstreamSkills(upstreamRoot);
   const localMapFull = await collectLocalSkills(proprietary);
-  // 编程子集：engineering 桶即编程（默认），--all 则含 productivity
+  // 默认范围：engineering 桶（编程）+ 独有所需（config/required.json，如 grill-to-spec 经 grill-with-docs 所需的 grilling）；--all 则含全部 productivity
+  const required = await loadRequired();
   const upstreamMap = onlyProgramming
-    ? new Map([...upstreamMapFull.entries()].filter(([, v]) => v.bucket === 'engineering'))
+    ? new Map([...upstreamMapFull.entries()].filter(([name, v]) => v.bucket === 'engineering' || required.has(name)))
     : upstreamMapFull;
   const localMap = localMapFull;
   const isEngineering = (name) => engineering.has(name);
+  const isDefault = (name) => engineering.has(name) || required.has(name);
 
   const added = [];
   const updated = [];
@@ -166,14 +177,14 @@ export async function compare({ upstreamUrl, tmpDir, ref, onlyProgramming = true
   for (const name of localMap.keys()) {
     if (renamedFrom.has(name)) continue;
     if (upstreamMap.has(name) || renamedTo.has(name)) continue;
-    // 编程模式下仅报告 engineering 本地技能的删除；productivity/instance-test 等跳过
-    if (onlyProgramming && !isEngineering(name)) continue;
+    // 默认模式下仅报告默认范围（engineering + 独有所需）内本地技能的删除；其余 productivity/instance-test 等跳过
+    if (onlyProgramming && !isDefault(name)) continue;
     // 全量模式下所有本地非独有且不在上游的都视为 removed
     removed.push(name);
   }
 
   const localCount = onlyProgramming
-    ? [...localMap.keys()].filter(isEngineering).length
+    ? [...localMap.keys()].filter((n) => isDefault(n)).length
     : localMap.size;
   return {
     head: fetched.head,
@@ -184,6 +195,7 @@ export async function compare({ upstreamUrl, tmpDir, ref, onlyProgramming = true
     localMapFull,
     proprietary: [...proprietary],
     engineering: [...engineering],
+    required: [...required],
     onlyProgramming,
     result: { added: added.sort(), updated: updated.sort(), same: same.sort(), removed: removed.sort(), renamed },
     counts: { upstream: upstreamMap.size, local: localCount, upstreamFull: upstreamMapFull.size, localFull: localMapFull.size },
@@ -247,7 +259,7 @@ function formatTable(cmp) {
   const { result, counts, head, onlyProgramming } = cmp;
   const lines = [];
   lines.push(`上游 HEAD: ${head}`);
-  const modeHint = onlyProgramming ? '（仅编程，engineering）' : '（全量，含 productivity）';
+  const modeHint = onlyProgramming ? '（默认，engineering + 独有所需）' : '（全量，含 productivity）';
   lines.push(`本地非独有: ${counts.local}  上游: ${counts.upstream} ${modeHint}`);
   lines.push('');
   const totalDiff = result.added.length + result.updated.length + result.removed.length + result.renamed.length;
@@ -291,7 +303,7 @@ Usage:
 Options:
   --check     只对比，不改动文件（默认）
   --apply     应用同步（覆盖 .agents/skills 非独有技能）
-  --all       包含非编程技能（productivity）；默认仅同步编程相关（engineering）
+  --all       包含全部非编程技能（productivity）；默认同步编程相关（engineering）+ 独有所需（config/required.json）
   --dry-run   演练模式，不写文件
   --json      以 JSON 输出结果
   --upstream  上游仓库 URL（默认 https://github.com/mattpocock/skills.git）

package/template/AGENTS.md

@@ -26,7 +26,7 @@
 
 以全局 AGENTS.md 安全铁律为准，本仓库无附加差异。
 
-## 行为路由（默认 22 自动发现，`--all` 展开至 32）
+## 行为路由（默认 23 自动发现，`--all` 展开至 32）
 
 命中即行动，回复中简短声明所用技能与原因。
 
@@ -37,10 +37,10 @@
 - 领域术语/ADR → domain-modeling；模块接口 → codebase-design；巨型规划 → wayfinder
 - 诊断 → diagnose-fix（编排 diagnosing-bugs + tdd，硬门槛）；审查 → code-review；合并冲突 → resolving-merge-conflicts；提交前 → commit-check（文档一致性 → 目录卫生 → commit message，三项）
 - 分诊 → triage；架构扫描 → improve-codebase-architecture；综合 spec → to-spec；拆票 → to-tickets
-- 可选（需 `--all` 才发现）：grill-me / grilling / handoff / teach / to-questionnaire / wait-what / writing-for-agents / ci-guard / scaffold-functional-test / instance-test
+- 可选（需 `--all` 才发现）：grill-me / handoff / teach / to-questionnaire / wait-what / writing-for-agents / ci-guard / scaffold-functional-test / instance-test
 - 兜底 → ask-matt；模板维护 → README.md
 
-显式触发（须用户 `/` 发起，默认 22 中仅 grill-to-spec/wayfinder/to-spec/to-tickets/triage/improve-codebase-architecture 为默认；其余 teach/handoff/writing-for-agents 需 `--all`）：grill-to-spec、wayfinder、to-spec、to-tickets、triage、improve-codebase-architecture、teach、handoff、writing-for-agents
+显式触发（须用户 `/` 发起，默认 23 中仅 grill-to-spec/wayfinder/to-spec/to-tickets/triage/improve-codebase-architecture 为默认；其余 teach/handoff/writing-for-agents 需 `--all`）：grill-to-spec、wayfinder、to-spec、to-tickets、triage、improve-codebase-architecture、teach、handoff、writing-for-agents
 
 ## 分文件