initialise-skills

initialise-skills

填充并确保各技能的 config.json 文件准确无误，供共享的 Agent 技能（changelog、send-it、cleanup-repo、linear-sync、triage-pr，……）在运行时读取。在宿主仓库中运行时，它会检测仓库信息，将其映射到每个已安装技能的配置架构，并写入准确的配置，同时绝不覆盖人工有意设置的值。

它始终先进行试运行，并且具备幂等性：第一步始终预览差异，只有在你确认后才会写入；如果重新运行时没有检测到新内容，每个文件都会保持逐字节不变。

如何决定写入哪些内容

对于每个已安装的技能，它会加载两项内容：技能自身的 config.example.json（定义要协调的键集合）以及现有的 config.json（全新安装时可能不存在）。随后，它会通过三方比较对每个键进行分类——示例占位值、现有值和检测到的值：

状态	含义	操作
inferred	尚无值，或仍是示例占位值	写入检测到的值
unchanged	现有值已等于检测到的值	不作更改
drift	实际值与检测结果不同——这是有意编辑的	保留；报告两个值
needs-manual-input	没有检测器，也没有值（例如没有 MCP 时的 Linear slug）	留待你填写
manual-kept	这是实际值，但没有对应的检测器	保留
unknown-kept	config.json 中存在技能模板未包含的键	保留，不作更改

检测依据是配置的键名，而非技能，因此一个检测器可以服务于所有使用该键的技能（一个 baseBranch 检测器同时适用于 changelog、send-it；一个 issueKeys 检测器同时适用于 changelog、cleanup-repo、linear-sync）。完整的键列表、检测来源和回退方案，请参阅 references/detectable-keys.md。Changelog 的 monorepo 门控（affectedPackages / packageRoots），以及如何将宿主仓库切换为单包或 monorepo，请参阅 references/monorepo-config.md。

有意跳过 preflight：它会自行检测基分支和工作区，并读取仓库根目录下的 可选 preflight.config.json，而不是随包提供的 config.json——因此此技能无需为其填充任何内容。（它在此处唯一的关联是下面的 .gitignore 步骤：安装了 preflight 时，会将其 .preflight-summary.json 临时输出加入仓库的 .gitignore。）

.gitignore 步骤

有两个协调步骤会修改宿主仓库根目录下的 .gitignore：

1. Preflight 临时文件（A-569）。 preflight 技能每次实际运行时，都会将 .preflight-summary.json 写入仓库根目录，因此如果没有忽略规则，运行 /send-it 后它就会显示为未跟踪的更改。安装了 preflight 时，此技能会确保宿主仓库根目录下的 .gitignore 将其排除。此编辑是仅追加且幂等的：仅当注释条目不存在时才添加（如果没有 .gitignore 则创建），并且绝不会调整或删除此条目的现有行。

2. 移除技能配置忽略规则（A-812）。 一些使用方（尤其是 A-812 修复前从 npm-package-template 生成的仓库）错误地将 .claude/skills/*/config.json 和 .agents/skills/*/config.json 加入 Git 忽略。这种模式仅适用于agent-skills 源仓库（skills/*/config.json，A-615——确保 skills add --copy 不会打包 ACME 标识信息），以及作为模板种子防护规则。在使用方仓库中，解析后的 config.json 必须提交。此技能会移除这些错误的使用方忽略规则（以及附带的注释块），以便 CI 和全新克隆的仓库能加载可运行的配置。它绝不会修改源仓库的 skills/*/config.json 规则。

试运行报告会显示待处理的编辑（will add … / will strip …）；写入后重新运行，则会报告 already ignored / no erroneous skill-config ignore rules。

skills.lock 步骤

除了配置协调之外，此技能还会在仓库根目录生成并提交一个 .claude/skills.lock 文件——一份机器可读的清单，记录已安装的技能版本及其来源：

{ "source": "https://github.com/rheged-studio/agent-skills", "ref": "main",
  "skills": { "changelog": "1.2.0", "send-it": "2.1.3", "…": "…" } }

• skills — 所有已安装套件的完整清单（包括 preflight 和此技能），读取自每个 SKILL.md 的 metadata.version。键按排序排列，因此在版本没有变化时重新运行不会产生任何字节变化（只有版本实际变动时才会重写文件）。无论套件存放在何处（skills/、.claude/skills/、.agents/skills/），锁定文件都位于固定路径 .claude/skills.lock，使用者应当提交此文件。
• source / ref — 脚本无法推导的来源信息（skills.sh 不会记录使用者从何处安装）。请在写入步骤的标准输入中将其作为 facts.lockSource / facts.lockRef 提供（见步骤 2）；若省略，则保留现有锁定文件中的值。如果两者均不可用，相应字段将写入 null，并在报告中标记（source/ref not supplied）——绝不捏造信息。

这是检测哪些仓库落后的基础——请参见下文的检查更新。

流程

1. 试运行。 在宿主仓库根目录运行捆绑脚本，获取机器可读的预览：

   node <skills-dir>/initialise-skills/scripts/initialise.mjs --dry-run --json
   

   <skills-dir> 是套件的安装位置（例如 skills/、.claude/skills/、.agents/skills/）；脚本会根据自身位置自动检测同级目录，因此通常只需从仓库根目录运行即可。解析 JSON：skills[] 中包含各键的 status，另有 driftKeys、manualKeys 和 totals。

2. 填写事实信息。 对每个需要人工输入的 Linear 键（linearTeamName、linearWorkspaceSlug，以及启用捕获时的 followUpProject），如果可以使用 Linear MCP，则通过它获取值：团队名称使用 mcp__linear-server__list_teams，兜底汇总项目使用 mcp__linear-server__list_projects（Rheged 体系：Follow-up issues——而非每个仓库各自的项目；如果可以，triage-pr 会继承 PR 当前的 Linear 项目，A-1541），工作区 slug 则从团队／组织获取；否则询问用户。将这些值收集到 facts 对象中。还需在此处添加锁定文件来源信息：lockSource（技能所安装自的源仓库——agent-skills 仓库 URL）和 lockRef（安装时使用的 ref；默认为 main，这是整个集群的惯例，除非固定了标签／SHA）。如果现有 .claude/skills.lock 已记录其中任一项，则跳过该项——其值会保留。

3. 展示差异并确认。 展示人工可读的报告（不带 --json 重新运行，或渲染解析后的 JSON）。指出将要写入的 inferred 键、将保留的 drift 键，以及需要人工输入的 needs-manual-input 键。对于每个 drift 键，询问是否接受检测到的值（逐键选择加入）。将接受的键收集到以技能名称为键的 acceptDrift 映射中，例如 { "changelog": ["issueKeys"] }。这是确认关卡——确认前不要写入。

4. 写入。 使用 --write 重新运行，并将收集到的事实信息和 drift 选择通过标准输入以 JSON 形式传入：

   echo '{"facts":{"linearTeamName":"…","linearWorkspaceSlug":"…","followUpProject":"…","lockSource":"https://github.com/rheged-studio/agent-skills","lockRef":"main"},"acceptDrift":{"changelog":["issueKeys"]}}' \
     | node <skills-dir>/initialise-skills/scripts/initialise.mjs --write --json
   

   根据返回的 totals 报告写入内容，以及 gitignore 字段（其 status 为 added、created、present 或 negated；如果未安装 preflight，则完全不会出现该字段，因为会跳过 .gitignore 步骤），并报告 lock 字段（其 status 为 written、unchanged 或 would-write；needsFacts: true 表示仍需提供 lockSource / lockRef）。

5. 确认幂等性。 再运行一次试运行；此时每个键都应为 unchanged（你选择保留的偏差以及仍缺失的手动设置值除外）。安装了 preflight 时，gitignore.status 应为 present （如果仓库有意取消对该文件的忽略，也可能是 negated——这同样是稳定的 无操作）；未安装时，会跳过 .gitignore 步骤，也就没有需要检查的 gitignore 字段。lock.status 应为 unchanged。这证明配置、.gitignore 和 skills.lock 都保持稳定，未来重新运行时不会产生任何更改。

6. GitHub App 和令牌检查。 如果此仓库将运行共享的 Claude 工作流 （reusable-claude*.yml 及其调用存根），必须安装 GitHub App，并设置 仓库 Actions 密钥 CLAUDE_CODE_OAUTH_TOKEN——工作流会使用该密钥进行身份验证， 若令牌为空则会失败（A-646）。必需的密钥是 CLAUDE_CODE_OAUTH_TOKEN，而不是 ANTHROPIC_API_KEY。

   探测该密钥（尽力而为——如果 gh 不可用或未通过身份验证，则静默跳过；不运行 Claude 工作流的仓库不需要该密钥）。将密钥列表和名称检查作为两个独立步骤 运行，并分别读取结果——不要将两者合并成一个 gh … | grep 管道，否则 gh 出错和确实缺少密钥都会报告相同的失败，导致无法确认的情况被掩盖：

   # step 1 — list the repo's Actions secrets; a non-zero exit here is "can't verify"
   gh secret list --repo <owner>/<repo> --app actions
   # step 2 — only when step 1 succeeded, check whether the name is in that output
   

   • 存在（步骤 1 成功且列出了该名称）→ 报告正常；无需处理。
   • 缺失（步骤 1 成功，但未找到该名称）→ 警告并提醒操作人员运行 /install-github-app，以安装 App 并添加密钥。
   • 无法确认（步骤 1 本身出错——例如，没有仓库管理员权限时返回 403， 或未安装 gh）→ 提示“无法确认令牌——请手动确认已设置 CLAUDE_CODE_OAUTH_TOKEN”，绝不要阻止运行或使其失败。无法判断不等于 缺失。

   没有 App 自身的令牌，就无法可靠地检查 App 是否已安装，因此密钥是否存在是可靠的 代理指标；/install-github-app 提醒会同时涵盖安装 App 和设置密钥。

7. 多 bundle 仓库——一个手动步骤。 如果此仓库本身包含多个独立版本管理的技能 bundle，send-it 的 bundleVersioning 不会自动写入（它不在 send-it 的 config.example.json 键集合中，因此检测没有可填充的内容）。请手动将其添加到 send-it/config.json—— { "root": "<bundle-dir>", "manifest": "package.json", "skillFile": "SKILL.md" } ——以启用每个 bundle 的版本递增检查。单包仓库可跳过此步骤。

检查现有配置

若要检查仓库中技能当前的配置，而不进行协调或写入任何内容，请运行只读检查：

node <skills-dir>/initialise-skills/scripts/initialise.mjs --review

对于每个已安装的技能，此命令都会打印其完整的 config.json：每个键的当前值、 分类（inferred / unchanged / drift / manual-kept / needs-manual-input / unknown-kept——见上表），以及对该键用途和取值来源的一行 说明，说明取自 references/detectable-keys.md。 消费者设置但任何技能模板都不认识的键会显示为 unknown-kept（原样保留，不显示 说明）；尚未出现在 config.json 中的模板键会显示为 — not set，因此检查结果 涵盖全部信息，而不仅仅是试运行会显示的待处理差异。人类可读文本会显示每个键的 used by … — <detection source> 行；对于未设置的键，还会显示在配置该键之前生效的 fallback: 默认值（已设置的键不会显示该项，因为当前值已表明实际生效的内容）。 添加 --json 可获取机器可读格式（一个 skills[] 数组，其中包含 { key, value, isSet, status, usedBy, detectionSource, fallback } 条目，以及 totals）。此命令 不会写入磁盘，并会跳过 .gitignore 步骤。

之后更改设置

消费者的 config.json 创建后，手动编辑是受支持的设置更改方式——无需通过此技能来处理每一次更改。打开 skills/<name>/config.json（或该技能包存放的位置），更改相应值，然后保存。它是由消费者拥有的真实文件；共享技能会在运行时读取该文件。

这样的手动编辑在之后重新运行 initialise-skills 时也会保留。下次运行时，协调过程会将你的值归类为 drift——即与检测结果不同的真实值——并予以保留，同时报告保留值和检测值（参见上文的状态表）。它绝不会被悄悄覆盖：只有你明确为该键选择启用（第 3 步中按键设置的 acceptDrift 门控）时，才会替换 drift。因此，刻意进行的手动编辑和检测到的事实可以共存——工具会协调它能检测到的事实，而不会覆盖你手动设置的内容。

如果你想通过工具进行相同的更改，建议使用下面的 --set <skill>.<key>=<value>——它会根据技能的 config.example.json 验证键，并保留键的顺序和格式——不过，直接手动编辑同样有效且安全。

设置任意值

检测、stdin facts 和 acceptDrift 三者涵盖了脚本能够推导或接受的所有值，但不包括你只是想要_选择_的值（例如非默认的基础分支、自定义的变更日志目录或布尔切换项）。对于这些值，--set <skill>.<key>=<value> 会将任意值直接写入指定技能的 config.json：

# dry-run first (default) — preview the change, write nothing
node <skills-dir>/initialise-skills/scripts/initialise.mjs \
  --set changelog.baseBranch=develop \
  --set changelog.affectedPackages=false

# re-run with --write to apply
node <skills-dir>/initialise-skills/scripts/initialise.mjs \
  --set changelog.baseBranch=develop --write

此标志可重复使用，其地址格式为 <skill>.<key>——先是技能包目录名，然后是顶层键。值会解析为 JSON（正确处理 true、42、["A"] 等类型）；如果不是有效 JSON，则回退为纯字符串（因此 develop 会保留为 "develop"）。写入任何内容前，程序会先进行验证：技能必须已安装；键必须存在于该技能的 config.example.json 中（未知键会被拒绝，绝不会悄悄创建）；并且值的类型必须与该键的示例占位值匹配（因此字符串不能写入布尔字段）。任何验证失败都会以非零状态退出，且不会修改任何内容。

--set 会通过常规协调流程执行——检测仍会运行，而你指定的值会叠加在检测结果之上，同一键的值以你指定的为准——并经过相同的合并与序列化流程，因此会保留键的顺序和格式，使用相同的值重新运行时也不会产生变化。它是一种写入模式，因此不能与 --review 同时使用（--review 仅供读取）。在报告中，被设置的键会显示为 set to <value> (was <old>)。

标志

• --dry-run（默认）——检测、合并并报告；不写入任何内容。
• --write——将协调结果应用到每个技能的 config.json。
• --review——**只读。**打印每个已安装技能的完整当前配置： 每个键的当前值、其分类（相同的六种状态），以及来自 references/detectable-keys.md 的简短说明。与 dry-run 不同，它会显示每个键的当前值——包括模板中不存在的 unknown-kept 键——因此展示的是完整情况，而不只是待处理的差异。不会写入任何内容，也会跳过 .gitignore 步骤。参见 审查现有配置。
• --set <skill>.<key>=<value>——**可重复使用。**将任意值写入指定技能的 config.json（检测不会生成的值）。该键必须存在于该技能的 config.example.json 中，且值的类型必须与其占位符匹配，否则将拒绝写入。此选项会执行常规协调（先 dry-run； 使用 --write 应用），并覆盖该键的检测结果。不能与 --review 一起使用。参见设置任意值。
• --json——输出机器可读报告（解析此报告以驱动步骤 2–3，或 获取 --review 快照）；否则输出人类可读文本。
• --repo-root <path>——检测器扫描的主仓库（默认：cwd）。
• --skills-dir <path>——同级 bundle 所在目录（默认：相对于此脚本自动检测）。
• stdin JSON——{ "facts": { … }, "acceptDrift": { "<skill>": ["<key>"] } }， 在 stdin 被管道传入时读取（而非 TTY）。每个 acceptDrift 键可以是技能 名称（"changelog"），也可以是相对于仓库的配置路径 （"skills/changelog/config.json"）；其值是键名数组。facts 还包含锁定来源信息 lockSource / lockRef（参见步骤 2）。

检查更新

要查看已安装技能相对于源仓库的落后情况，请针对源仓库的检出版本运行附带的 check-updates.mjs（使用方只有旧版 vendored 副本，因此目标版本取自源仓库）：

node <skills-dir>/initialise-skills/scripts/check-updates.mjs \
  --source <path-to-agent-skills-checkout> [--ref <tag-or-sha>] [--json]

该脚本会将使用方的 .claude/skills.lock 与源仓库的 bundle 版本进行比较—— 如果指定了 --ref，则使用该引用（通过 git show），否则使用源仓库的工作树——并输出 各技能的升级列表：updates（落后——可执行的列表），以及 added （上游新增的技能）、removed、downgrades（使用方版本较新）和 upToDate。 --lock <path> 用于指定某个使用方的锁文件（默认 <cwd>/.claude/skills.lock）， 因此 fleet 编排器无需切换目录即可检查任意仓库。有关锁文件架构，请参见 references/skills-lock.md。

安全性

• 先试运行，确认后再写入。 未经用户明确同意，不会执行带有 --write 的写入操作。
• 绝不覆盖有意修改的内容。 除非你选择逐项启用，否则会保留偏差。
• 不删除，不重新排序。 现有键保持原有顺序；只处理有变更的键；保留使用者添加的键。如果现有 config.json 格式错误，则跳过（会报告，但绝不覆盖）。
• 对 .gitignore 的修改范围有限。 除技能的 config.json 外，本技能只会修改仓库根目录下的 .gitignore，以便（1）在缺少 .preflight-summary.json 时将其追加进去（A-569——绝不重新排序或删除与该条目相关的现有行）；（2）移除错误的 .claude/.agents 技能配置忽略规则，以免阻止使用者提交已填充的 config.json（A-812）。绝不会修改 Agent 技能源规则 skills/*/config.json。
• skills.lock 写入过程确定且字节稳定。 除 config.json 外，另一处会修改的文件是 .claude/skills.lock，该文件会完全重新生成，键按排序排列且不含时间戳——因此只有版本实际变更时才会重写，无操作运行则会保持字节级完全一致。会保留现有锁文件中的 source/ref，绝不凭空创建这些字段。
• GitHub App / 令牌探测为只读操作。 gh secret list 只会返回密钥名称，不会返回值；本技能不会以任何方式写入 GitHub——如果密钥不存在或无法验证，只会打印提醒。

先决条件

• 你要填充配置的技能与本技能一起安装。
• 一个带有 origin 远程仓库的 Git 仓库，以便完整检测基础分支 / Issue 键（如果缺少这些信息，两者都会回退到合理的默认值）。
• 用于获取团队名称 / 工作区 slug 的 Linear MCP 服务（可选——没有它时，这两个键会标记为需要手动输入）。
• 使用具有仓库管理员权限的 gh CLI 进行身份验证，即可启用 GitHub App / 令牌探测（步骤 6）。如果没有该权限（或未安装 gh），探测就无法读取密钥列表，因此会回退为“无法验证——请手动确认 CLAUDE_CODE_OAUTH_TOKEN”的提示——这是无法判断，而非失败。文本形式的 /install-github-app 提醒是单独的缺失结果，仅在探测成功且确认密钥确实缺失时才会发出。无论哪种情况，技能仍会完整运行。