initialise-skills

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

initialise-skills

initialise-skills（技能初始化）

Populate and keep accurate the per-skill

config.json

files that the shared agent skills (

changelog

send-it

cleanup-repo

linear-sync

triage-pr

, …) read at runtime. Run inside the host repo, it detects repo facts, maps them onto each installed skill's config schema, and writes accurate configs — without ever clobbering a value a human deliberately set.

It is dry-run first and idempotent: the first step always previews the diff, writes happen only after you confirm, and a re-run with nothing new to detect leaves every file byte-for-byte unchanged.

填充并维护共享Agent技能（

changelog

、

send-it

、

cleanup-repo

、

linear-sync

、

triage-pr

等）在运行时读取的各技能

config.json

文件。在宿主仓库内运行时，它会检测仓库事实，将其映射到每个已安装技能的配置架构，并写入准确的配置——绝不会覆盖人为手动设置的值。

它具备先试运行和幂等性特性：第一步总会预览差异，仅在你确认后才执行写入；若没有新的检测内容，重新运行会让所有文件保持字节级完全一致。

How it decides what to write

写入逻辑说明

For each installed skill it loads two things: the skill's own

config.example.json

(which defines the set of keys to reconcile) and the existing

config.json

(which may be absent on a fresh install). Each key is then classified by a three-way comparison — example placeholder vs existing value vs detected value:

Status	Meaning	Action
`inferred`	No value yet, or still the example placeholder	Write the detected value
`unchanged`	Existing value already equals what we detected	No-op
`drift`	A real value that differs from detection — a deliberate edit	Keep it; report both values
`needs-manual-input`	No detector and no value (e.g. a Linear slug with no MCP)	Leave for you to supply
`manual-kept`	A real value we have no detector for	Keep it
`unknown-kept`	A key in `config.json` no skill template knows about	Keep it, untouched

Detection is keyed by config-key name, not by skill, so one detector serves every skill that uses a key (one

baseBranch

detector covers

changelog

send-it

; one

issueKeys

detector covers

changelog

cleanup-repo

linear-sync

). See

references/detectable-keys.md

for the full table of keys, their detection sources, and fallbacks.

preflight

is intentionally skipped: it self-detects its base branch and workspaces and reads an optional

preflight.config.json

at the repo root, not an in-bundle

config.json

— so there is nothing for this skill to populate. (Its one trace here is the

.gitignore

step below: when preflight is installed, its

.preflight-summary.json

scratch output is added to the repo's

.gitignore

对于每个已安装的技能，它会加载两类内容：技能自身的

config.example.json

（定义需要协调的键集合）和已有的

config.json

（全新安装时可能不存在）。随后通过三方对比（示例占位符 vs 现有值 vs 检测值）对每个键进行分类：

状态	含义	操作
`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

。

preflight

技能被刻意跳过：它会自行检测基础分支和工作区，并读取仓库根目录下的可选

preflight.config.json

，而非技能包内的

config.json

——因此本工具无需为其填充内容。（本工具与它唯一的关联是下面的

.gitignore

步骤：当安装

preflight

时，本工具会确保宿主仓库根目录的

.gitignore

排除其

.preflight-summary.json

临时输出文件。）

The

.gitignore

step

.gitignore

处理步骤

The

preflight

skill writes

.preflight-summary.json

to the repo root on every real run, so without an ignore rule it surfaces as an untracked change after a

/send-it

run. When

preflight

is installed, this skill ensures the host repo's root

.gitignore

excludes it — the one mutation it makes outside a skill's

config.json

. The edit is append-only and idempotent: it adds the commented entry only when absent (creating

.gitignore

if there is none), and never reorders or removes existing lines. The dry-run report shows the pending edit (

will add …

); a re-run after writing reports

already ignored

preflight

技能每次实际运行时都会向仓库根目录写入

.preflight-summary.json

，若未添加忽略规则，

/send-it

运行后该文件会显示为未跟踪的变更。当安装

preflight

时，本工具会确保宿主仓库根目录的

.gitignore

排除该文件——这是本工具在技能

config.json

之外做出的唯一修改。该编辑是仅追加且幂等的：仅当条目不存在时才添加注释行（若

.gitignore

不存在则创建），绝不会重新排序或删除现有行。试运行报告会显示待执行的编辑（

will add …

）；写入后重新运行会报告

already ignored

。

The

skills.lock

step

skills.lock

处理步骤

Alongside the config reconcile, this skill emits a committed .claude/skills.lock
at the repo root — a machine-readable inventory of which skill versions are installed and where they came from:

json

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

skills
— a full inventory of every installed bundle (including
```
preflight
```
and this skill), read from each
```
SKILL.md
```
```
metadata.version
```
. Keys are sorted, so a re-run with no version changes is a byte-stable no-op (the file only rewrites when a version actually moves). The lock lives at the fixed
```
.claude/skills.lock
```
path regardless of where the bundles were vendored (
```
skills/
```
,
```
.claude/skills/
```
,
```
.agents/skills/
```
), and consumers commit it.
source
/
ref
— provenance the script cannot derive (skills.sh records nowhere where a consumer installed from). Supply them as
```
facts.lockSource
```
/
```
facts.lockRef
```
in the write step's stdin (see step 2); an existing lock's values are preserved when omitted. When neither is available the field is written as
```
null
```
and the report flags it (
```
source/ref not supplied
```
) — never fabricated.

This is the foundation for detecting which repos are behind — see Checking for updates below.

在协调配置的同时，本工具会在仓库根目录生成一个已提交的**

.claude/skills.lock

**文件——这是一个机器可读的清单，记录了已安装技能的版本及其来源：

json

{ "source": "https://github.com/acme-skunkworks/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
```
的形式提供；若已存在锁文件，省略时会保留其原有值。若两者均无法获取，该字段会被写入为
```
null
```
，且报告会标记（
```
source/ref not supplied
```
）——绝不会凭空捏造。

这是检测哪些仓库版本落后的基础——请查看下方的检查更新部分。

Process

操作流程

Dry run. From the host repo root, run the bundled script for a machine-readable preview:
bash
```
node <skills-dir>/initialise-skills/scripts/initialise.mjs --dry-run --json
```
```
<skills-dir>
```
is wherever the bundles are installed (e.g.
```
skills/
```
,
```
.claude/skills/
```
,
```
.agents/skills/
```
); the script auto-detects its siblings relative to its own location, so usually you can just run it from the repo root. Parse the JSON:
```
skills[]
```
with per-key
```
status
```
, plus
```
driftKeys
```
,
```
manualKeys
```
, and
```
totals
```
.
Fill the facts. For each
```
needs-manual-input
```
Linear key (
```
linearTeamName
```
,
```
linearWorkspaceSlug
```
), fetch the value via the Linear MCP when it is available —
```
mcp__linear-server__list_teams
```
for the team name, and the workspace slug from the team/organisation — otherwise ask the user. Collect these into a
```
facts
```
object. Also add the lock provenance here:
```
lockSource
```
(the source repo the skills were installed from — the agent-skills repo URL) and
```
lockRef
```
(the ref installed from; default
main
, the fleet convention, unless a tag/SHA was pinned). Skip either when an existing
```
.claude/skills.lock
```
already records it — its value is preserved.
Present the diff and confirm. Show the human report (re-run without
```
--json
```
, or render the parsed JSON). Call out the
```
inferred
```
keys that will be written, the
```
drift
```
keys that will be kept, and the
```
needs-manual-input
```
keys. For each
drift
key, ask whether to accept the detected value (the per-key opt-in). Gather the accepted ones into an
```
acceptDrift
```
map keyed by skill name, e.g.
```
{ "changelog": ["issueKeys"] }
```
. This is the confirmation gate — do not write before it.

Write. Re-run with

--write

, piping the gathered facts and drift opt-ins as stdin JSON:

bash

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

Report what was written from the returned

totals

, plus the

gitignore

field (its

status

—

added

created

present

, or

negated

; the field is absent entirely when

preflight

isn't installed, as the

.gitignore

step is skipped) and the

lock

field (its

status

—

written

unchanged

, or

would-write

;

needsFacts: true

means

lockSource

lockRef

still need supplying).

Confirm idempotency. Run the dry run once more; every key should now be
```
unchanged
```
(apart from drifts you chose to keep and any still-missing manual values). When
```
preflight
```
is installed,
```
gitignore.status
```
should be
```
present
```
(or
```
negated
```
, if the repo deliberately un-ignores the file — also a stable no-op); when it isn't, the
```
.gitignore
```
step is skipped and there's no
```
gitignore
```
field to check.
```
lock.status
```
should be
```
unchanged
```
. This proves the configs, the
```
.gitignore
```
, and the
```
skills.lock
```
are stable and a future re-run is a no-op.
GitHub App & token check. If this repo will run the shared Claude workflows (
```
reusable-claude*.yml
```
and their caller stubs), the GitHub App must be installed and the
```
CLAUDE_CODE_OAUTH_TOKEN
```
repository Actions secret set — the workflows authenticate with it and fail on an empty token (A-646). The required secret is CLAUDE_CODE_OAUTH_TOKEN
, not
ANTHROPIC_API_KEY
.
Probe for the secret (best-effort — skip silently if
```
gh
```
is unavailable or unauthenticated; a repo that runs no Claude workflows needs neither). Run the listing and the name-check as two separate steps and read each result — do not collapse them into one
```
gh … | grep
```
pipe, which would report the same failure for a
```
gh
```
error and a genuine absence, hiding the can't-verify case:
bash
```
# 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
```
- present (step 1 succeeds and lists the name) → report OK; nothing to do.
- absent (step 1 succeeds but the name is missing) → warn and remind the operator to run /install-github-app
  , which installs the App and adds the secret.
- can't verify (step 1 itself errors — e.g. a
```
403
```
  without repo-admin scope, or
```
gh
```
  not installed) → surface it as "couldn't verify the token — please confirm
```
CLAUDE_CODE_OAUTH_TOKEN
```
  is set manually", never block or fail the run. A can't-tell is not an absence.
The App install itself can't be reliably introspected without the App's own token, so the secret's presence is the reliable proxy; the
```
/install-github-app
```
reminder covers installing the App and setting the secret together.
Multi-bundle repos — one manual step. If this repo itself ships several independently-versioned skill bundles,
```
send-it
```
's
```
bundleVersioning
```
is not auto-written (it isn't in
```
send-it
```
's
```
config.example.json
```
key set, so detection has nothing to populate). Add it to
```
send-it/config.json
```
by hand —
```
{ "root": "<bundle-dir>", "manifest": "package.json", "skillFile": "SKILL.md" }
```
— to enable the per-bundle version-bump check. Single-package repos skip this.

试运行。从宿主仓库根目录运行捆绑脚本，获取机器可读的预览结果：
bash
```
node <skills-dir>/initialise-skills/scripts/initialise.mjs --dry-run --json
```
```
<skills-dir>
```
是技能包的安装路径（例如
```
skills/
```
、
```
.claude/skills/
```
、
```
.agents/skills/
```
）；脚本会根据自身位置自动检测同级技能包，因此通常只需从仓库根目录运行即可。解析JSON结果：包含每个键的
```
status
```
的
```
skills[]
```
数组，以及
```
driftKeys
```
、
```
manualKeys
```
和
```
totals
```
字段。
补充事实信息。对于每个标记为
```
needs-manual-input
```
的Linear键（
```
linearTeamName
```
、
```
linearWorkspaceSlug
```
），若Linear MCP可用则通过其获取值——团队名称通过
```
mcp__linear-server__list_teams
```
获取，工作区slug从团队/组织信息中获取——否则询问用户。将这些信息收集到
```
facts
```
对象中。同时在此处添加锁文件来源信息：
```
lockSource
```
（技能安装源仓库的URL——即agent-skills仓库的URL）和
```
lockRef
```
（安装时使用的引用；默认值为
main
，这是团队约定，除非固定了标签/SHA）。若已存在
```
.claude/skills.lock
```
文件且已记录这些值，可跳过填写——原有值会被保留。
展示差异并确认。展示面向人工的报告（重新运行时去掉
```
--json
```
参数，或渲染解析后的JSON结果）。突出显示即将写入的
```
inferred
```
键、将被保留的
```
drift
```
键，以及
```
needs-manual-input
```
键。对于每个
drift
键，询问是否接受检测到的值（按键逐个确认）。将用户接受的键收集到
```
acceptDrift
```
映射中，键为技能名称，例如
```
{ "changelog": ["issueKeys"] }
```
。这是确认环节——未确认前不得执行写入操作。

执行写入。添加

--write

参数重新运行脚本，并将收集到的事实信息和偏差确认结果通过标准输入以JSON格式传入：

bash

echo '{"facts":{"linearTeamName":"…","linearWorkspaceSlug":"…","lockSource":"https://github.com/acme-skunkworks/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

）。

验证幂等性。再次运行试运行；除用户选择保留的偏差值和仍未补充的手动值外，所有键的状态都应为
```
unchanged
```
。若安装了
```
preflight
```
，
```
gitignore.status
```
应显示为
```
present
```
（或
```
negated
```
，若仓库刻意取消忽略该文件——这也是稳定的无操作状态）；若未安装
```
preflight
```
，则会跳过
```
.gitignore
```
步骤，无需检查该字段。
```
lock.status
```
应显示为
```
unchanged
```
。这证明配置、
```
.gitignore
```
和
```
skills.lock
```
均处于稳定状态，未来重新运行时不会产生任何变更。
GitHub应用与令牌检查。若本仓库将运行共享的Claude工作流（
```
reusable-claude*.yml
```
及其调用存根），则必须安装GitHub应用，并设置
```
CLAUDE_CODE_OAUTH_TOKEN
```
仓库Actions密钥——工作流通过该密钥进行身份验证，若令牌为空则会失败（A-646）。所需的密钥是**
```
CLAUDE_CODE_OAUTH_TOKEN
```
，而非
```
ANTHROPIC_API_KEY
```
**。
探测密钥状态（尽力而为——若
```
gh
```
不可用或未认证则静默跳过；不运行Claude工作流的仓库无需这两者）。将列出密钥和名称检查分为两个独立步骤并分别读取结果——不要合并为一个
```
gh … | grep
```
管道命令，因为该命令会将
```
gh
```
执行错误和密钥实际缺失两种情况报告为相同的失败结果，从而掩盖无法验证的情况：
bash
```
# 步骤1——列出仓库的Actions密钥；若此处非零退出则表示"无法验证"
gh secret list --repo <owner>/<repo> --app actions
# 步骤2——仅当步骤1成功时，检查密钥名称是否在输出中
```
- 已存在（步骤1成功且输出中包含该名称）→ 报告正常；无需操作。
- 不存在（步骤1成功但输出中无该名称）→ 发出警告，并提醒操作人员运行**
```
/install-github-app
```
  **，该命令会安装应用并添加密钥。
- 无法验证（步骤1本身出错——例如无仓库管理员权限导致的
```
403
```
  ，或未安装
```
gh
```
  ）→ 提示"无法验证令牌——请手动确认
```
CLAUDE_CODE_OAUTH_TOKEN
```
  已设置"，绝不阻止或终止运行。无法确认不等于不存在。
若无应用自身的令牌，无法可靠地检查应用是否已安装，因此密钥的存在状态是可靠的替代指标；
```
/install-github-app
```
的提醒会同时覆盖应用安装和密钥设置操作。无论哪种情况，本工具都能完整运行。
多技能包仓库——手动步骤。若本仓库本身包含多个独立版本化的技能包，则
```
send-it
```
的
```
bundleVersioning
```
不会被自动写入（它不在
```
send-it
```
的
```
config.example.json
```
键集合中，因此检测逻辑无法为其填充内容）。需手动将其添加到
```
send-it/config.json
```
中——格式为
```
{ "root": "<bundle-dir>", "manifest": "package.json", "skillFile": "SKILL.md" }
```
——以启用按技能包的版本升级检查。单包仓库可跳过此步骤。

Reviewing an existing config

查看现有配置

To inspect what a repo's skills are currently configured with — without reconciling or writing anything — run the read-only review:

bash

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

For each installed skill it prints its full

config.json

: every key's current value, its classification (

inferred

unchanged

drift

manual-kept

needs-manual-input

unknown-kept

— see the table above), and a one-line description of what the key is and where its value comes from, drawn from

references/detectable-keys.md

. Keys a consumer set that no skill template knows about show as

unknown-kept

(kept verbatim, no description), and template keys not yet present in

config.json

show as

— not set

, so the review is the whole picture rather than just the pending diff a dry-run would show. The human text shows each key's

used by … — <detection source>

line, and — for an unset key — the

fallback:

default that applies until it's configured (set keys omit it, since the live value already shows what's in effect). Add

--json

for the machine-readable form (a

skills[]

array of

{ key, value, isSet, status, usedBy, detectionSource, fallback }

entries, plus

totals

). It never writes to disk and skips the

.gitignore

step.

若要查看仓库中技能的当前配置——无需协调或写入任何内容——可运行只读的查看命令：

bash

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

参数可获取机器可读格式（包含

{ key, value, isSet, status, usedBy, detectionSource, fallback }

条目的

skills[]

数组，以及

totals

字段）。该命令绝不会写入磁盘，且会跳过

.gitignore

步骤。

Changing a setting later

后续修改配置

Once a consumer's

config.json

exists, hand-editing it is a supported way to change a setting — you don't have to route every change through this skill. Open

skills/<name>/config.json

(or wherever the bundle is vendored), change the value, and save. It is a real file the consumer owns; the shared skills read it at runtime.

A manual edit like that survives future
initialise-skills
re-runs. On the next run the reconcile classifies your value as

drift

— a real value that differs from what detection would produce — and keeps it, reporting both the kept value and the detected one (see the status table above). It is never silently overwritten: drift is only replaced if you explicitly opt in for that key (the per-key

acceptDrift

gate in step 3). So a deliberate manual edit and a detected fact coexist — the tool reconciles the facts it can detect without clobbering the ones you set by hand.

Prefer

--set <skill>.<key>=<value>

below when you want the same change made through the tool — it validates the key against the skill's

config.example.json

and preserves key order and formatting — but a direct hand-edit is equally valid and equally safe.

一旦用户的

config.json

存在，手动编辑是修改配置的支持方式——无需每次变更都通过本工具操作。打开

skills/<name>/config.json

（或技能包安装的其他路径），修改值并保存。这是用户拥有的真实文件，共享技能会在运行时读取它。

此类手动编辑会在未来重新运行
initialise-skills
时保留。下次运行时，协调逻辑会将你的值分类为

drift

——即与检测结果不同的实际值——并保留原值，同时报告原值和检测值（见上方状态表）。绝不会被静默覆盖：仅当你明确为该键确认接受检测值时（步骤3中的按键

acceptDrift

环节），偏差值才会被替换。因此，人为手动编辑的内容与检测到的事实可以共存——工具会协调可检测的事实，同时不会覆盖你手动设置的内容。

当你希望通过工具进行相同变更时，建议使用下方的

--set <skill>.<key>=<value>

方式——它会根据技能的

config.example.json

验证键的有效性，并保留键的顺序和格式——但直接手动编辑同样有效且安全。

Setting an arbitrary value

设置任意值

Detection, the stdin

facts

, and

acceptDrift

between them cover every value the script can derive or accept — but not a value you simply want to choose (a non-default base branch, a bespoke changelog directory, a boolean toggle). For those,

--set <skill>.<key>=<value>

writes an arbitrary value straight into a named skill's

config.json

bash

undefined

检测逻辑、标准输入的

facts

和

acceptDrift

共同覆盖了脚本可推导或接受的所有值——但不包括你想要自行选择的值（非默认基础分支、定制化变更日志目录、布尔开关等）。对于此类情况，可使用

--set <skill>.<key>=<value>

直接将任意值写入指定技能的

config.json

：

bash

undefined

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

添加--write参数重新运行以应用变更

node <skills-dir>/initialise-skills/scripts/initialise.mjs
--set changelog.baseBranch=develop --write


The flag is **repeatable** and the address is `<skill>.<key>` — the skill's bundle
directory name, then a top-level key. The value is parsed as JSON (`true` / `42` /
`["A"]` type correctly) and falls back to a bare string when it isn't valid JSON
(so `develop` stays `"develop"`). It is validated up front, before anything is
written: the skill must be installed, the key must exist in that skill's
`config.example.json` (unknown keys are **refused**, never silently created), and
the value's type must match that key's example placeholder (so a string can't land
in a boolean field). Any failure exits non-zero and touches nothing.

`--set` rides the normal reconcile — detection still runs and your values are
layered on top, winning over what a detector would produce for the same key — and
goes through the same merge/serialise path, so key order and formatting are
preserved and a re-run with the same value is a no-op. It is a write mode, so it
**cannot be combined with `--review`** (which is read-only). In the report a set
key shows as `set to <value> (was <old>)`.

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`设置的键会显示为`set to <value> (was <old>)`。

Flags

参数说明

```
--dry-run
```
(default) — detect, merge and report; write nothing.
```
--write
```
— apply the reconcile to each skill's
```
config.json
```
.
```
--review
```
— read-only. Print every installed skill's full current config: each key's current value, its classification (the same six statuses), and a short description sourced from
```
references/detectable-keys.md
```
. Unlike the dry-run it shows the current value of every key — including
```
unknown-kept
```
keys no template knows about — so it is a complete picture, not just the pending diff. Writes nothing and skips the
```
.gitignore
```
step. See Reviewing an existing config.
```
--set <skill>.<key>=<value>
```
— repeatable. Write an arbitrary value into a named skill's
```
config.json
```
(a value detection wouldn't produce). The key must exist in that skill's
```
config.example.json
```
and the value's type must match its placeholder, else it's refused. Rides the normal reconcile (dry-run first;
```
--write
```
to apply) and overrides detection for that key. Cannot be combined with
```
--review
```
. See Setting an arbitrary value.
```
--json
```
— emit the machine-readable report (parse this to drive steps 2–3, or to consume the
```
--review
```
snapshot); human text otherwise.
```
--repo-root <path>
```
— the host repo the detectors scan (default: cwd).
```
--skills-dir <path>
```
— where the sibling bundles live (default: auto-detected relative to this script).
stdin JSON —
```
{ "facts": { … }, "acceptDrift": { "<skill>": ["<key>"] } }
```
, read when stdin is piped (not a TTY). Each
```
acceptDrift
```
key may be a skill name (
```
"changelog"
```
) or the repo-relative config path (
```
"skills/changelog/config.json"
```
); its value is an array of key names.
```
facts
```
also carries the lock provenance
```
lockSource
```
/
```
lockRef
```
(see step 2).

```
--dry-run
```
（默认）——执行检测、合并并报告；不执行写入。
```
--write
```
——将协调结果应用到每个技能的
```
config.json
```
。
```
--review
```
——只读模式。打印每个已安装技能的完整当前配置：每个键的当前值、分类（与上述六种状态一致），以及来自
```
references/detectable-keys.md
```
的简短描述。与试运行不同，它会显示每个键的当前值——包括技能模板未定义的
```
unknown-kept
```
键——因此能展示完整的配置情况，而非仅待变更差异。不会写入任何内容，且会跳过
```
.gitignore
```
步骤。详见查看现有配置。
```
--set <skill>.<key>=<value>
```
——可重复使用。将任意值写入指定技能的
```
config.json
```
（检测逻辑无法生成的值）。键必须存在于该技能的
```
config.example.json
```
中，且值的类型必须与占位符匹配，否则会被拒绝。基于正常协调流程运行（先试运行；需添加
```
--write
```
参数以应用），并覆盖该键的检测结果。无法与
```
--review
```
组合使用。详见设置任意值。
```
--json
```
——输出机器可读的报告（可解析此报告以驱动步骤2–3，或获取
```
--review
```
的快照）；否则输出面向人工的文本。
```
--repo-root <path>
```
——检测器扫描的宿主仓库路径（默认：当前工作目录）。
```
--skills-dir <path>
```
——同级技能包的存放路径（默认：根据本脚本位置自动检测）。
标准输入JSON——
```
{ "facts": { … }, "acceptDrift": { "<skill>": ["<key>"] } }
```
，当标准输入为管道输入（而非终端）时读取。
```
acceptDrift
```
的键可以是技能名称（
```
"changelog"
```
）或仓库相对配置路径（
```
"skills/changelog/config.json"
```
）；其值为键名数组。
```
facts
```
还包含锁文件来源信息
```
lockSource
```
/
```
lockRef
```
（见步骤2）。

Checking for updates

检查更新

To see which installed skills are behind the source repo, run the bundled

check-updates.mjs

against a checkout of the source (the consumer holds only its old vendored copies, so the target versions come from the source):

bash

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

It diffs the consumer's

.claude/skills.lock

against the source's bundle versions — at

--ref

(via

git show

) when given, else the source working tree — and prints the per-skill bump list:

updates

(behind — the actionable list), plus

added

(new upstream skills),

removed

downgrades

(consumer ahead), and

upToDate

--lock <path>

targets a specific consumer's lock (default

<cwd>/.claude/skills.lock

), so a fleet orchestrator can check any repo without changing directory. See

references/skills-lock.md

for the lock schema.

若要查看哪些已安装技能落后于源仓库版本，可针对源仓库的检出版本运行捆绑的

check-updates.mjs

脚本（用户仅持有旧的本地副本，因此目标版本来自源仓库）：

bash

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

它会将用户的

.claude/skills.lock

与源仓库的技能包版本进行对比——若指定

--ref

则通过

git show

获取对应版本，否则使用源仓库的工作区版本——并打印按技能分类的升级清单：

updates

（落后版本——需处理的列表），以及

added

（上游新增技能）、

removed

（已移除技能）、

downgrades

（用户版本超前）和

upToDate

（已更新至最新）。

--lock <path>

可指定特定用户的锁文件路径（默认：

<cwd>/.claude/skills.lock

），因此集群编排工具无需切换目录即可检查任意仓库。锁文件的架构请查看

references/skills-lock.md

。

Safety

安全性说明

Dry-run first, write only after confirmation. Nothing is written without an explicit
```
--write
```
pass gated on the user's go-ahead.
Never clobbers deliberate edits. Drift is preserved unless you opt in per key.
No deletes, no reordering. Existing keys keep their order; only changed keys are touched; consumer-added keys are left alone. A malformed existing
```
config.json
```
is skipped (reported, never overwritten).
The
.gitignore
edit is append-only. One file touched outside a skill's
```
config.json
```
is the repo's root
```
.gitignore
```
, and only to append the
```
.preflight-summary.json
```
entry when it is missing — never reordering or removing existing lines, and a no-op once present.
The
skills.lock
write is deterministic and byte-stable. The other file touched outside a
```
config.json
```
is
```
.claude/skills.lock
```
, fully regenerated with sorted keys and no timestamp — so it only rewrites when a version actually changes, and a no-op run leaves it byte-identical. It preserves an existing lock's
```
source
```
/
```
ref
```
and never fabricates them.
The GitHub App / token probe is read-only.
```
gh secret list
```
returns secret names only, never values, and the skill makes no GitHub writes of any kind — on an absent or unverifiable secret it only ever prints a reminder.

先试运行，确认后再写入。无明确的
```
--write
```
参数且未获得用户确认时，不会执行任何写入操作。
绝不覆盖人为手动编辑内容。偏差值会被保留，除非你按键确认接受检测值。
无删除、无重排序。现有键会保持原有顺序；仅修改变更的键；用户添加的键会完全保留。若已有的
```
config.json
```
格式错误，会跳过处理（仅报告，绝不覆盖）。
.gitignore
编辑仅追加。在技能
```
config.json
```
之外修改的唯一文件是仓库根目录的
```
.gitignore
```
，且仅当
```
.preflight-summary.json
```
条目缺失时才追加——绝不会重新排序或删除现有行，一旦条目存在即为无操作。
skills.lock
写入具有确定性和字节稳定性。另一个在
```
config.json
```
之外修改的文件是
```
.claude/skills.lock
```
，它会以排序后的键完全重新生成，且不包含时间戳——因此仅当版本实际变更时才会重写，无操作运行时会保持字节级一致。它会保留已有锁文件的
```
source
```
/
```
ref
```
值，绝不会凭空捏造。
GitHub应用/令牌探测为只读。
```
gh secret list
```
仅返回密钥名称，绝不会返回值；本工具不会对GitHub执行任何写入操作——若密钥不存在或无法验证，仅会打印提醒信息。

Prerequisites

前置条件

The skills whose configs you want populated are installed alongside this one.
A git repository with an
```
origin
```
remote for full base-branch / issue-key detection (both degrade to sensible fallbacks when absent).
The Linear MCP server for the team name / workspace slug (optional — those two keys are flagged for manual input without it).
The
```
gh
```
CLI authenticated with repo-admin scope enables the GitHub App / token probe (step 6). Without that scope (or without
```
gh
```
at all) the probe can't read the secret list, so it degrades to a "couldn't verify — confirm
```
CLAUDE_CODE_OAUTH_TOKEN
```
manually" note — a can't-tell, never a failure. The textual
```
/install-github-app
```
reminder is the separate absent outcome, emitted only when the probe succeeds and finds the secret genuinely missing. Either way the skill still runs fully.

需填充配置的技能已与本工具一同安装。
具备
```
origin
```
远程仓库的git仓库（用于完整检测基础分支/问题键；若缺失则会降级为合理的回退方案）。
获取团队名称/工作区slug所需的Linear MCP服务器（可选——若无该服务器，这两个键会被标记为需要手动输入）。
已认证且具备仓库管理员权限的
```
gh
```
CLI（用于执行GitHub应用/令牌探测，步骤6）。若无该权限（或未安装
```
gh
```
），探测无法读取密钥列表，因此会降级为提示"无法验证——请手动确认
```
CLAUDE_CODE_OAUTH_TOKEN
```
已设置"——无法确认不等于失败。面向文本的
```
/install-github-app
```
提醒仅在探测成功且确认密钥确实缺失时才会发出。无论哪种情况，本工具都能完整运行。

initialise-skills

Original

Translation

initialise-skills

initialise-skills（技能初始化）

How it decides what to write

写入逻辑说明

The
`.gitignore`
step

`.gitignore`
处理步骤

The
`skills.lock`
step

`skills.lock`
处理步骤

Process

操作流程

Reviewing an existing config

查看现有配置

Changing a setting later

后续修改配置

Setting an arbitrary value

设置任意值

dry-run first (default) — preview the change, write nothing

先试运行（默认）——预览变更，不执行写入

re-run with --write to apply

添加--write参数重新运行以应用变更

Flags

参数说明

Checking for updates

检查更新

Safety

安全性说明

Prerequisites

前置条件

initialise-skills

Original

Translation

initialise-skills

initialise-skills（技能初始化）

How it decides what to write

写入逻辑说明

The .gitignore step

.gitignore处理步骤

The skills.lock step

skills.lock处理步骤

Process

操作流程

Reviewing an existing config

查看现有配置

Changing a setting later

后续修改配置

Setting an arbitrary value

设置任意值

dry-run first (default) — preview the change, write nothing

先试运行（默认）——预览变更，不执行写入

re-run with --write to apply

添加--write参数重新运行以应用变更

Flags

参数说明

Checking for updates

检查更新

Safety

安全性说明

Prerequisites

前置条件

The
`.gitignore`
step

`.gitignore`
处理步骤

The
`skills.lock`
step

`skills.lock`
处理步骤