matt-skills

面向项目仓库的 Agent skills 与配置模板。模板包含项目 skeleton、AGENTS.md、项目上下文占位文件，以及 pi / opencode 所需的项目配置；共享 Skills 由 CLI 从 Workspace 的 canonical source 直接组装到目标项目。

环境要求

• Node.js >=18。
• npm（随 Node.js 提供，用于安装和运行 CLI；也可通过 npx 直接调用）。
• Git（sync、check 和发布流程需要）。

模板内容

template/
├── AGENTS.md                 Agent 行为路由与项目上下文入口
├── PROJECT.md                目标项目填写的目标、范围和主要入口
├── .opencode/                opencode 基础框架（context、docs、skills 占位）
└── .pi/                      pi 基础框架（context、docs、skills 占位）

共享 Skills 不作为 Template Snapshot 的持久化副本；init、普通 sync 和项目级 install 都从 Workspace 的 canonical source 分发到唯一的 .agents/skills/。.pi/skills/、.opencode/skills/ 和 .claude/skills/ 仅用于项目自定义 skills。

• PROJECT.md 描述项目是什么；操作规则放在 AGENTS.md。
• 分发的 AGENTS.md 提供通用工作流；项目专用规则、命令、测试方式和完成标准由目标项目更具体的 AGENTS.md 补充。
• .opencode/CONTEXT.md / .pi/CONTEXT.md 保存领域术语与边界。
• .agents/skills/ 承载共享 skills；同步只处理可分发 skill 名称，不删除额外的项目自定义 skills。
• ci-guard、commit-check 是本仓库维护用的 repo-local skills，不会分发到目标项目。
• .pi、.codex 不承载共享 skills；workspace 专用 commands、agents 和 prompts 也不会进入默认模板。

独有 skill 分发边界

本仓库有 8 个独有（proprietary）skills：

可分发的 6 个

• tdd-implement
• diagnose-fix
• grill-to-spec
• scaffold-functional-test
• show-me
• initialize-project

仓库内部的 2 个

• ci-guard
• commit-check

repo-local skills 不会通过 init、install、sync 分发到用户项目。

初始化

在目标仓库根目录执行：

npx @heihei0299/matt-skills init              # 安装默认 workflow skills
npx @heihei0299/matt-skills init --all       # 安装全部可分发 skills

已有项目同步：

npx @heihei0299/matt-skills sync             # 安全增量同步默认范围
npx @heihei0299/matt-skills sync --all       # 同步全部可分发 skills
npx @heihei0299/matt-skills sync --dry-run --json

init 对已有 AGENTS.md 始终跳过；已有项目使用 sync。默认 sync 保留已有 AGENTS.md 和项目规则，--all 只扩大技能范围。需要显式刷新 AGENTS.md 时使用 sync --refresh-agents；无受管区块时会先备份为 AGENTS.md.bak。sync 不删除目标项目的额外文件或自定义 skills。

默认 init / sync 不分发 .pi 与 .opencode；需要完整 harness 配置时使用 --all。

默认 workflow 范围固定为 9 个入口及依赖 skills，包含 initialize-project、setup-matt-pocock-skills、grill-with-docs、to-spec、to-tickets、grilling、domain-modeling、tdd 和 diagnosing-bugs；其中默认独有 skills 是 initialize-project。

CLI

npx @heihei0299/matt-skills list [--all] [--json]
npx @heihei0299/matt-skills install [--all] [--tools <list>] [--global] [--dest <dir>]
npx @heihei0299/matt-skills init [--all] [--dest <dir>]
npx @heihei0299/matt-skills sync [--all] [--dry-run] [--refresh-agents] [--dest <dir>]
npx @heihei0299/matt-skills check [--all] [--json] [--upstream <url>] [--ref <ref>]

常用选项：

• --all：包含全部可分发 skills，默认范围只包含 workflow skills；不会隐式刷新 AGENTS.md。
• --refresh-agents：显式刷新目标 AGENTS.md；与 --all、--dry-run 可组合。
• --dest <dir>：指定目标目录。
• --tools <list>：选择 codex、pi、opencode 或 claude；项目级 skills 统一写入 .agents/skills/，全局安装仍使用各工具目录。
• --global：写入用户级 skills 目录。
• --dry-run：预演目标项目差异，不写入；sync --dry-run --json 输出机器可读结果。
• check --json：输出上游比较的机器可读结果。普通 sync --json 不支持。

Codex CLI 支持

Codex 的项目级 skills 位于 .agents/skills/；全局 skills 位于 ~/.codex/skills。init、普通 sync 和项目级 install 共用 .agents/skills/，避免同一共享 skill 在多个项目目录产生镜像。

npm run codex:smoke
CODEX_E2E=1 npm run codex:smoke

本项目不包含 Codex Cloud、Codex 专用 commands、plugins 或 MCP 配置。

上游同步

非独有 skills 来自 mattpocock/skills。

npx @heihei0299/matt-skills check --json              # 检查上游差异
npx @heihei0299/matt-skills sync --dry-run --json     # 预演目标项目变化
npx @heihei0299/matt-skills sync                      # 同步默认范围
npx @heihei0299/matt-skills sync --all                # 同步全部可分发范围
npx @heihei0299/matt-skills sync --refresh-agents     # 同步并刷新 AGENTS.md

发布

版本由推送的 v* 标签决定；GitHub Actions 会在发布时从 tag 设置 npm 包版本，并执行全量测试与模板检查。

npm test
npm run build:template
git tag vX.Y.Z
git push origin main vX.Y.Z

发布需要 GitHub Secrets 中配置 NPM_TOKEN。模板或共享 skills 的改动需要新版本才会分发给目标项目。

开发

npm test
npm run build:template

测试位于 test/；模板由 scripts/build-template.js 生成，template/AGENTS.md 的独立源是 config/template-AGENTS.md。提交前应确保模板同步测试通过。

许可证

MIT