setup-skills

设置 skills

起草 ship 技能会读取的仓库级文档；每次写入前都要先与用户确认。此技能只处理其父技能 setup-matt-pocock-skills 未完成、但 ship 需要的内容：将父技能关于跟踪器、分流词汇和领域文档布局的回答视为既定，只询问父技能尚未明确的事项。

你在此处编写的每份文档都会由 Agent 读取：请对文档中的文字应用 writing-for-agents。

流程

1. 前置条件：告知并停止

开始探索前，检查以下三项。任何一项不符合，都打印确切命令，然后打印“then rerun /setup-skills”，并停止。

1. 父级文档。 docs/agents/issue-tracker.md、docs/agents/triage-labels.md 和 docs/agents/domain.md 必须存在。否则：运行 /setup-matt-pocock-skills。例外：如果主机（第 2 步）是 Azure DevOps，且 issue-tracker.md 缺失或是父技能的自由格式“Other”页面，则可提出将随附的 issue-tracker-ado.md 写入该位置（先确认），然后继续。父技能仅附带 GitHub、GitLab 和本地模板。

2. 由派生副本组成的 skills。 .claude/skills/ 中必须有 code-review、tdd、codebase-design、writing-for-agents、triage、find-docs 和 show-me，并且每项都记录在仓库的 skills-lock.json 中（skills CLI 会在安装时写入），其 ref 必须与下方对应行固定的值一致，即源仓库测试所用的上游提交。锁文件记录的副本若使用其他 ref，或未记录在锁文件中，都视为未固定：打印对应行。若副本存在但未记录在锁文件中，则属于手工维护：说明“will be replaced by the derived copy”，确认后按对应行刷新。~/.claude/skills 下的全局副本不满足此检查：个人技能会悄悄覆盖仓库技能，因此 ship 的组合技能必须放在仓库中。否则打印：

   npx skills add mattpocock/skills#f3fc5632f401156837ee3872f14fe33ccf1024ea --skill code-review --skill tdd --skill codebase-design --agent claude-code -y
   npx skills add mattpocock/skills#c55ee46073ed923f86ce59a5eb3b6d895095d1b7 --skill writing-for-agents --agent claude-code -y
   npx skills add mattpocock/skills#d81f3a183412e71a5b1e84ca21bc1a35eea03a60 --skill triage --agent claude-code -y
   npx skills add upstash/context7#3131245817e9e40626d8f43ce85dabab09d4ff35 --skill find-docs --agent claude-code -y
   npx skills add humanlayer/skills#ca7c8088db69e315a8b2deea43820270457f8f3c --skill show-me --agent claude-code -y
   

3. ship、cloud-ship 和 setup-skills。 .claude/skills/ship、.claude/skills/cloud-ship 和 .claude/skills/setup-skills 必须存在且记录在锁文件中。若 ship 文件夹的 frontmatter 中没有 metadata.version，则属于通用技能出现前的手工维护副本：说明“will be replaced by the derived copy”，确认后刷新。setup-skills 按步骤 1.2 的方式处理；运行此检查的副本不能作为证据，因此请读取 skills-lock.json。否则打印：

   npx skills add Gharib89/skills --skill ship --skill cloud-ship --skill setup-skills --skill update-skills --agent claude-code -y
   

   update-skills 不是前置条件：缺少它不会导致拒绝继续。若锁文件中没有它，说明这一点，打印同一行以安装它，然后继续。

   始终使用项目范围，即不带 -g 的安装命令。

2. 主机

从 git remote get-url origin 判断：github.com 对应 github；dev.azure.com 或 visualstudio.com 对应 ado；其他情况均视为超出范围并停止。与 docs/agents/issue-tracker.md 的标题行交叉核对；若不匹配，停止并指出两者。

然后使用 ship 自带的预检来验证主机工具，这是唯一存在的主机检查。将其作为不关联问题的检查调用，因此结果只针对主机和配置文件：

.claude/skills/ship/scripts/preflight.sh none

若退出码为 2，且原因是 host-unreachable（缺少 CLI、缺少扩展、尚未登录、没有推送权限），则在此停止并说明原因：设置阶段是唯一有用户在场、可修复身份验证问题的时机。若退出码为 1，且提示 profile missing，则这是此时的预期结果；继续。

预检无法验证 git 远程本身，因此还要运行 git ls-remote --heads origin。此处失败只会在之后显示为 existing branch: remote unreadable，而且运行中的每次推送都会失败。如果使用 Azure DevOps，且已通过 Entra 执行 az login、没有 PAT，则可提出使用跟踪器文档 Auth 行中的仓库级凭据助手；它会从同一个令牌生成 git 密码。

3. 探索

先通读仓库一次，阅读每个部分，再开始交流。右侧列说明探索是否足以解决该部分，还是必须通过访谈（步骤 4）来确定。 首先是测试框架，因为它决定 Local gate 和 Cloud lane 行。其配置文件 docs/agents/harness.md 是唯一有效信号：单独的 scripts/check.sh 或测试框架 CLAUDE.md 区块都不算。若存在：读取其中两行：## Check entry point 下的 Location:，以及 ## Cloud 下的 Setup:；并从仓库根目录运行一次 <Location> full，其中 <Location> 是测试框架配置文件中的那一行，而不是发布配置文件中的。若该次运行以 0 或 1 退出，并在 stdout 上输出一行 JSON，其中包含 rung、verdict 和一个 checks 对象，则入口点符合要求；检查失败仍是符合要求的结果。其他情况均报告为 harness present, check entry point non-conforming: re-run /setup-harness；此时 Local gate over the harness 到此停止：不写入或重写 gate，因为基于该入口点的 gate 无法映射任何内容。现有 gate 仍会在步骤 5 中运行一次，发布配置文件中的 Location: 会记录该 gate；若没有现有 gate，Location: 则记录 scripts/local-gate.sh，这是 /setup-harness 修复入口点后重新运行 setup-skills 时写入的路径；步骤 7 会告知用户，在此之前不存在本地 gate。其他所有事项照常进行，包括 Cloud bootstrap，它绝不会调用 check.sh。若不存在：步骤 4 以未配置测试框架的问题开头。

部分	阅读内容	能否通过探索确定？
主机	步骤 2	是
Worktree	Carry: 来自 git status --ignored --short，仅保留小型点文件（.env*、*.local）；Bootstrap: 除非存在本地 gate 无法负责的 setup 脚本，否则为 None.	是，确认列表
Local gate	若有测试框架，gate 步骤 5 会基于测试框架配置文件中的 Location: 写入 gate；否则依次使用 scripts/local-gate.sh、.claude/skills/ship/scripts/local-gate.sh、scripts/ship/local-gate.sh；锁文件决定运行器（package-lock.json 对应 npm，pnpm-lock.yaml 对应 pnpm，uv.lock 对应 uv run pytest，单独的 pyproject.toml 对应 pytest）；Small node: 的语法遵循运行器；另有一条 docs-class 行，注明已更改文档的路径	位置可以；节点语法需逐项检查
CI	Legs: 每个带有 pull_request 触发器的工作流的每个作业（.github/workflows/*.yml；在 ADO 中为 build-validation 策略指定的管道）；其他工作流在文字中注明为非 PR 工作流；若任一 PR 工作流带有 paths: 筛选器，或根本没有 PR 工作流，则 No-checks legal: yes；若 Legs: None.，这两项组合会将 ci-wait 的无检查宽限期降为零；Push policy:	工作流可确定；推送策略需逐项检查
审查者	每种审查者类型各列一个清单，见下方 ### Reviewers	需逐项检查
编码标准	CLAUDE.md 中指定的路径、CODING_STANDARDS.md、CONTRIBUTING.md、docs/contributing/*	可以，或使用存根
验证	无法通过探索发现；根据测试标记（e2e、integration）、Docker 使用情况和浏览器测试脚本进行初步设定	需逐项检查
版本管理与变更日志	semantic-release 配置、changesets、version-gate 或 bump 脚本、CHANGELOG.md；In-PR requirement:	需逐项检查
PR	.github/pull_request_template.md 或 .azuredevops/pull_request_template.md：是否存在、标题，以及任何关闭引用相对于第一个 ## 标题的位置	是
公共接口	建议使用 Default.	需逐项检查
分类处理	从 triage-labels.md 中 needs-triage 行的右侧列复制	是
文档同步	README.md、docs/、GLOSSARY.md、仓库随附的技能；Agent-facing: 为 docs/agents/、.claude/skills/	是，确认
当前文档	始终使用 context7；出现 Microsoft 技术栈时使用 Microsoft Learn（D365、Azure、Power BI、.NET）；Pinned:	需逐项检查
Cloud lane	PR cap: 3；若有测试框架，Bootstrap: 为 scripts/cloud-ship-bootstrap.sh，由步骤 5 的 Cloud bootstrap 写入；若没有测试框架，则文件存在时使用该路径，否则为 None.	是

另外，为步骤 5 记录三项内容：

• 这些通用机制取代的仓库专属发布脚本：scripts/ship/ 下的 claim、isolate、preflight、poll-pr、ci-wait、merge-and-verify、merge、reflect、release、_lib，以及 .claude/skills/ship/scripts/ 下的 claim、merge-and-verify 和 release；该目录中的其他文件则属于衍生副本自身的机制。
• 主机已有的 triage-labels.md 五种角色标签和 dimension-labels.md 中的十四种维度标签，使用 gh api --paginate "repos/{owner}/{repo}/labels" --jq '.[].name' 获取。请使用分页读取，而不要使用 gh label list，因为它默认只获取 30 个标签，并会静默截断结果。请不区分大小写进行匹配，因为 GitHub 标签名称不区分大小写：大小写不同的标签会记录为重命名，而不是缺失。ADO 中的标签只要使用过就会存在，因此无需读取。
• docs/agents/triage-labels.md 是否已包含 ## Dimension labels 标题。

审查者

检测每种审查者类型，并按 reference/reviewers.md 所述确定其 Resolve:、Workflow: 和 Cap: 行。

4. 展示，然后逐项确认

先一次性展示完整的探索结果：每个章节将读取什么，每项一行。然后只逐项确认需要确认的行，每次一个章节、一个答案，并以推荐答案开头，方便用户用一个词接受。仅在选项确实存在分支时，提供一行说明。已通过探索确定的章节会显示在草稿中；逐项确认时跳过这些章节。

确认顺序及开头推荐答案：

• 没有 harness，仅当第 3 步未找到 harness 配置时首先询问："未找到 harness：先运行 /setup-harness（推荐），或继续而不配置"。选择前者会结束流程且不写入任何内容，并打印“运行 /setup-harness，然后重新运行 /setup-skills”，若仓库缺少该工具，则安装命令为 npx skills add Gharib89/skills --skill setup-harness --agent claude-code -y。选择继续则采用自包含的本地门禁，并跳过云端引导，因此云端引导保持第 3 步探测到的状态。此答案不会记录到任何地方，所以每次运行都会再次询问。
• 本地门禁，小型节点：运行器自身的 Node 语法，并提供仓库测试中的一个示例；以及文档类别值，即变更文档的路径，并提供一个示例。
• CI，推送策略：如果按量计费（私有仓库、ADO 并行作业），则为 one push per review round；否则为 Default.。
• 审查者：列出每个已检测到的审查者及其推断出的触发条件，然后询问“是否有未检测到的审查者？”。接着，只针对 Claude Code 提出一个问题，且仅当探索未发现已有 Claude 工作流时才询问。若草稿中有其他审查者，则以按需触发的回退方案开头，并说明该审查者是此方案的主要替代对象。若草稿中没有审查者，则在一个问题中询问两种方案，并说明取舍；如果发布流程会创建大多数 PR，则优先推荐按需触发，否则优先推荐推送时触发：按需触发（评论作为触发方式，Fallback-for: None.，Cap: 2）会让小型流程运行一轮，并设置一个会生效的上限，任何评论者都可以触发；推送时触发则会审查每次推送，包括人工推送，但其上限仅供参考。这个答案将决定第 5 步搭建的方案；不会再提第二个问题。询问每个审查者的上限：按需触发推荐 2，推送时触发推荐 3，自动执行一次则为 None.。最后询问 Self-review cap:，即一次运行在第 4 阶段进行自我审查的最大轮数：推荐 3；设为 1 则每次运行都只进行一轮，与 Schema 5 之前相同。
• 验证：每个种子配置各一段；如果仓库中没有涉及真实系统的内容，则为 None.。
• 版本管理：先说明探索结果，然后询问 In-PR requirement:，即会改变发布流程行为的那一行。
• 公开接口：除非仓库除 API 外还会发布其他内容（门禁规则、调色板、包输入），否则为 Default.。
• 当前文档，已固定版本：列出仓库清单文件固定了主版本号、且 API 最近有变更的库。

5. 确认并编辑

展示下面所有内容的完整草稿，然后让用户编辑后再写入。在这里进行字段级验证，这是唯一有人在场修复问题的时刻。每个评审者区块都包含模板列出的每一行 Label:，包括 Cap:，且草稿不含十种评审者形态中的任何一种，这些形态都会被 ship 的预检拒绝：逐一检查 reference/reviewers.md 中的每一种。

然后：Self-review cap: 必须是大于等于 1 的整数；每个 Also proven by CI: 都必须指定 ## CI 中定义的一条支路；defer-to-ci 只能与这样的支路一起出现；Host: 必须与步骤 2 一致；十四个标题须按顺序排列；Schema: 行须等于 ship 的 metadata.profile-schema。

来自 ship-profile.md 的 docs/agents/ship.md：包含全部十四个标题；默认化的维度填 None. 或 Default.；移除模板注释。

### Ship 子区块：根据 ship-block.md 创建并移除模板注释，放入父级所选的 CLAUDE.md / AGENTS.md 文件现有的 ## Agent skills 区块中（即包含该区块的文件）。若已存在，则在原处更新，使文件最终恰好包含一个该区块。

基于测试框架的本地门禁，仅当步骤 3 的探测符合约定时适用。check.sh full 会提供其运行的所有门禁，每项检查各对应一个门禁，并使用该检查自身的名称；本地门禁只添加 Ship 所需的内容。

• 不存在：根据 local-gate-harness.sh 创建 scripts/local-gate.sh：将 __CHECK__ 替换为测试框架配置中的 Location: 路径；__DEPS__ 和 __RUNNER__ 使用步骤 3 的 Local gate 行中的值；按照下方自包含项的接线方式接入 secrets；在标记的位置放入 Ship 专用门禁：相对于基准的检查，以及针对每条只能由 CI 证明的 CI 支路执行的 mark <leg> deferred-to-ci。此处的门禁使用检查名称而非支路名称，因此自包含项中的每条支路对应一个门禁的规则不适用；但每个 deferred-to-ci 标记仍须使用 ## CI 中指定的支路名称。
• 已存在：提议将其改写为该模板。移除 check.sh full 已运行的每项门禁，依据其运行的命令匹配，而非依据名称；模板自身的 secrets、deps 和小型流程 tests 将替换旧门禁中的对应项。将 Ship 所需的每项门禁（相对于基准的检查、deferred-to-ci 标记）保留在 Ship 专用位置，并向用户列出所有既不匹配任何检查、也非 Ship 所需的门禁，由用户决定保留或删除。展示差异，确认后写入。

自包含本地门禁，不使用测试框架：

• 不存在：根据 local-gate.sh 创建 scripts/local-gate.sh，每条 CI 支路对应一个门禁，并使用 ## CI 中的支路名称；运行器明确时在本地运行，不明确时使用 deferred-to-ci；将 secrets 接入已检测到的扫描器（gitleaks、ggshield、detect-secrets、trufflehog），否则标记为 unavailable，并添加注释说明需要添加什么。
• 已存在且符合约定（JSON 判定结果包含 verdict、gates、secrets 门禁，以及 --small 和 --base 标志）：保留；Location: 记录其位置。
• 已存在但不符合约定（输出文本、--small 为位置参数、没有 unavailable 状态）：提议按约定重写，同时保留旧门禁运行的每项检查；展示差异，确认后写入。仅当用户同意时，Location: 才改为 scripts/local-gate.sh。

无论执行了哪个本地门禁项，或者不符合约定的探测后保留了现有门禁，都运行一次已创建或保留的门禁（使用示例节点并带上 --small），并检查判定结果的格式：一个包含 verdict、base、lane、gates.secrets 的 JSON 对象。 云端引导，需要有 harness；没有时跳过。根据 cloud-ship-bootstrap.sh 编写 scripts/cloud-ship-bootstrap.sh。它在运行时从 docs/agents/harness.md 读取 Setup: 并运行该云端设置，因此无需为其填入任何内容。按模板的配置注释填写 SCANNER 和 SCANNER_INSTALL。切勿将 GitHub 发布资产下载用作 SCANNER_INSTALL，因为云端会话的网络会屏蔽此类下载，因此应替换现有引导脚本中固定版本的下载，而不是保留它。在标记的位置填入仓库专属的 Ship 步骤。除非某个步骤需要 Ship 独有的内容（例如 live-e2e 凭据或配置文件），否则该步骤属于 harness 云端设置。对于现有引导脚本，建议基于模板重写：删除云端设置已涵盖的每个步骤，按其安装的内容进行匹配；保留其余 Ship 专属步骤；将每个有歧义的步骤列出来供用户确认，并根据用户的回答决定保留或删除；展示差异，并在确认后写入。

PR 模板、编码标准、分诊标签和 ## Dimension labels 部分：遵循 reference/templates.md。写入前，先在草稿中逐项确认。

评审者脚手架，针对用户指定且尚未安装的每位评审者；以及重新运行时，在包含 reviewer-scaffolding 名称的设置部分中：遵循 reference/reviewers.md。

已被取代的 ship 脚本（迁移中的仓库）：列出第 3 步记录的内容，提议删除，并在确认后删除。保留 local-gate.sh、live-e2e、copilot-pr-review-loop 和 cloud-ship-bootstrap.sh（即 ## Cloud lane 中的 Bootstrap:）。

6. 写入，然后验证

写入所有已确认的文件。然后针对新配置运行 ship 的预检：

.claude/skills/ship/scripts/preflight.sh none

报告其 reasons。没有问题的调用不会产生任何自身原因，因此列表应为空；任何 profile missing、profile invalid、skill missing、skill off pin、skills lock unreadable 或 composes pin invalid 原因都需要你在结束前修复。对于最后一种原因，应重新运行刷新命令，因为这表示已安装的 ship 副本格式错误。skill missing 或 skill off pin 原因会指出第 1 步未安装或未固定到指定版本的组合技能步骤，并附上安装它的命令：运行该命令。skills lock unreadable 原因会在任何安装命令之前出现：技能 CLI 会将无法解析的锁文件重写为只包含新条目的文件，因此请先修复其 JSON。

Ship 会根据允许规则匹配的相对路径调用 merge，因此请告知用户在仓库的 .claude/settings.local.json 中，将 Bash(.claude/skills/ship/scripts/merge.sh:*) 添加到 permissions.allow 下；没有这条规则，自动模式可能会拒绝合并。

7. 完成

告知用户：配置文件位于 docs/agents/ship.md，现在可以运行第一个 /ship <issue>，并且已安装 cloud-ship：该仓库上的云端例程会通过单行提示词 Run the cloud-ship skill. 触发它。（该例程会自行选择问题；提示词中不包含仓库名称。）例程本身属于某位操作人员的日程安排，此处不作编写。之后他们可以直接编辑 docs/agents/ship.md。

重新运行

配置文件重新运行：当配置文件已存在时适用；设置部分重新运行：当刷新指出设置部分的模板已变更时适用。这两种情况各对应 reference/re-run.md 中的一段；对符合条件的情况逐一处理。如果两种情况都适用，先处理配置文件重新运行。