mattpocock-skills 安装指南：Claude Code 插件与 skills.sh 双路线的规范化安装实践

本文基于 skills13/skills 仓库中的 .agents/install-block.md 编写，围绕该仓库的"规范化安装文案"（canonical install block）展开。它定义了 mattpocock-skills 这一技能集在 Claude Code（原生插件）与 Codex 及其他 Agent（skills.sh）两条安装路线下的唯一标准命令，并解释了为何两条路线必须二选一。读完本文，你将掌握两种环境的准确安装命令、单技能与全量安装的写法、官方市场自动更新机制，以及仓库内部对安装文案的治理约定。

一个安装故事，一种措辞：什么是 canonical install block

mattpocock-skills 的安装文案不是散落在各处的零散命令，而是一个集中治理的单一事实源（single source of truth）。install-block.md 在仓库中承担这一角色：README.md、.changeset/* 以及 docs/ 下的每一页都必须引用同一套安装命令，任何措辞调整都先改这里，再向外传播。

这一约定解决的是文档维护中的经典问题——安装命令在多处被复制后必然漂移（drift）：某处升级了参数，另一处还停留在旧写法，读者照抄后执行失败。通过把命令收敛为唯一的"块"，仓库保证任何入口给出的安装方式都彼此一致、可验证。

路线一：Claude Code 原生插件（推荐）

mattpocock-skills 已上架 Claude Code 官方插件市场（市场配置名 claude-plugins-official，源仓库为 anthropics/claude-plugins-official），而该市场是每个 Claude Code 安装开箱即用的默认市场——不需要先手动添加任何市场，因此"更新自动到达"是一句真话，而非承诺：Anthropic 官方市场默认启用自动更新。

命令行安装

在终端中执行：

claude plugins install mattpocock-skills

会话内安装

在 Claude Code 会话中，直接输入斜杠命令：

/plugin install mattpocock-skills

安装完成后，技能即作为受管、只读、持续更新的捆绑包存在：你订阅它，而不是编辑它。仓库内的 .agents/adr/0002-ship-as-a-claude-code-plugin.md 记录了 2026-08-05 在 Claude Code 2.1.222 上的实测验证结果：claude plugins install mattpocock-skills 无需预先添加市场即可解析成功，并报告 mattpocock-skills@claude-plugins-official；claude plugin details mattpocock-skills 可查看版本并加载已上架技能。该 ADR 还披露了一个关键细节：官方市场的 source 中 sha 是固定的（pinned），因此一个 release 是在 pin 移动后才到达已安装用户，而不是打 tag 的瞬间。

插件包里到底有什么

插件清单 .claude-plugin/plugin.json 以显式数组列出了全部 24 个受推广技能（engineering/ 与 productivity/ 两个桶），例如 ./skills/engineering/triage、./skills/engineering/tdd、./skills/productivity/grilling 等，从而零歧义地排除 misc/、in-progress/、deprecated/ 等非推广桶。插件 version（当前为 1.2.3）与 package.json 的版本由 scripts/sync-plugin-version.mjs 在发布时同步，因为 Claude 正是依据插件 version 决定已安装用户何时看到更新。

路线二：Codex 及其他 Agent 使用 skills.sh

插件是 Claude Code 专属的。在 Codex 以及其他遵循 Agent-Skills 标准的 harness 上，统一使用 skills.sh 将可编辑的技能文件复制进项目——你拥有并可以自行修改这些文件，与插件的"订阅只读捆绑包"形成对照。

全量安装（用于 README.md）

npx skills@latest add mattpocock/skills

安装器会交互式地让你挑选需要哪些技能，以及安装到哪些 coding agent 上。官方措辞强调一个关键点：务必把 setup-matt-pocock-skills 纳入选择。它是整个技能集的"一次性初始化"技能，负责为工程类技能播种仓库级配置（issue tracker、triage 标签词汇、领域文档布局）。.agents/adr/0001-explicit-setup-pointer-only-for-hard-dependencies.md 进一步说明：to-tickets、to-spec、triage 是硬依赖技能，没有该配置输出就是错误的，而不是模糊；因此安装时若漏掉它，这几个技能将无法正常工作。

单技能安装与更新（用于单独提到某个技能的页面）

当文案中单独点名某个技能时，使用单技能形式：

npx skills@latest add mattpocock/skills --skill=<name>

npx skills@latest update <name>

注意：docs 页面不承载安装命令

一个值得注意的仓库约定（见 .agents/writing-docs.md）：docs/ 页面不是本安装块的消费方。ai-hero 站点会在正文上方渲染安装组件（复制按钮 + 单技能命令 + 全量命令 + 更新行），因此页面如果再手写一遍命令，就会与组件重复并随时间漂移。docs/ 下原先自带的命令块因此被删除而非修正——安装文案是站点（ai-hero）的属性，而不是页面属性；若要修改，改 ai-hero 侧的组件，标准措辞则以本 install block 为准。

两条路线互斥：永远只说"二选一"

这是 install block 最核心的一条使用规则：

路线	交付形态	文件归属	更新方式
Claude Code 插件	受管、只读的捆绑包	你订阅它，不拥有它	官方市场自动更新
skills.sh	可编辑的技能文件	复制进项目，你拥有并修改	手动 npx skills@latest update <name>

同时安装两条路线会让用户得到每个技能的副本 ×2，因此官方文案永远只说"选一个"。给读者讲安装时，务必备注二选一，避免技能重复。

不是安装故事：marketplace.json 兜底路由

仓库还保留着一个不向用户宣传的兜底路径：.claude-plugin/marketplace.json 使仓库成为自己的单插件市场：

/plugin marketplace add mattpocock/skills
/plugin install mattpocock-skills@mattpocock

这条路径在官方上架之后已被官方列表取代——官方列表直接读取该仓库 git URL 下的 .claude-plugin/plugin.json，并不依赖 marketplace.json。它只作为直接安装本仓库（未发布的 commit 或 fork）时的回退方案保留，且不写入任何面向用户的文档。这种"留后门、不宣传"的处理，恰好说明了 canonical install block 的治理目标：用户看到的安装故事只有官方那一个。

小结

mattpocock-skills 的安装治理浓缩为一句话：一条路线对应一个标准命令，一处修改全仓库同步。Claude Code 用户走 claude plugins install mattpocock-skills（自动更新、只读订阅），Codex 及其他 Agent 用户走 npx skills@latest add mattpocock/skills（可编辑、可挑选、手动更新），二者互斥；setup-matt-pocock-skills 在任何安装路径下都不应缺席。这一套约定由 .agents/install-block.md、.claude-plugin/plugin.json、.claude-plugin/marketplace.json 以及两份 ADR 共同支撑，构成了从命令到清单再到决策记录的全链路证据。