kit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Kit

套件

Say	Do
`kit` , `sync` , `update` , `refresh` , `upgrade` , `install` , `setup` , `init` , `start` , `starter-pack` , with no source named	Sync. Re-arm every app at the latest version, cloning the harness first if it is missing. Bare `kit` means this, in every directory, a Repo-Dev checkout included.
any of those followed by a source, such as `sync cyber-skills`	One source. `harness.py sync <source>` , matched as a substring. Named a source, meant that source.
`fix` , `doctor` , `repair` , `troubleshoot` , `conflict`	Fix. Something installed wrong, or two things collided.

Never ask which. Sync is idempotent, so there is no separate Install mode to pick wrong: running it where the harness already exists syncs it instead of breaking it. Releasing this package is Repo-Dev work and is not a mode here.

Everything below the two modes is reference. Read one when the task names it.

One collection, one harness.

collection.toml

records which skills this machine carries. Kit fetches

harness-core

from GitHub and runs its local script; it does not install package managers, runtimes, or shell hooks. Source of truth for anything not here: the harness README.

输入指令	执行操作
`kit` , `sync` , `update` , `refresh` , `upgrade` , `install` , `setup` , `init` , `start` , `starter-pack` ，未指定源名称	同步。将所有应用更新至最新版本，如果harness缺失则先克隆它。在任何目录下直接输入 `kit` 都执行此操作，包括Repo-Dev检出目录。
上述任一指令后跟源名称，例如 `sync cyber-skills`	单一源同步。执行 `harness.py sync <source>` ，按子字符串匹配源名称。指定源后仅同步该源。
`fix` , `doctor` , `repair` , `troubleshoot` , `conflict`	修复。用于解决安装错误或组件冲突问题。

无需询问具体操作。同步是幂等操作，因此没有单独的安装模式会导致误操作：在已存在harness的环境中运行该指令只会进行同步，不会破坏现有环境。发布此包属于Repo-Dev的工作范畴，不在本操作模式内。

以下内容为参考信息，仅在执行对应任务时阅读。

一个技能集合对应一个harness。

collection.toml

记录了本机搭载的所有技能。套件从GitHub获取

harness-core

并运行其本地脚本；它不会安装包管理器、运行时或shell钩子。本文档未覆盖内容的权威来源：harness README。

Report it while it runs

运行过程中记录日志

Install and Sync fan out over every source and every app. That takes minutes. Keep the whole log:

bash

set -o pipefail
git -C ~/.harness-core pull --ff-only
python3 ~/.harness-core/harness.py sync 2>&1 | tee /tmp/kit.log

Never pipe it through
tail
or
head
. That discards the failures and replaces the harness exit code with the pager's, so a run that died a third of the way through reads as a clean success.

If it outruns your tool timeout, background it, say so in chat, and report progress rather than going quiet. The harness prints one line per repo and ends in a count, so

tail -1 /tmp/kit.log

is the position.

安装和同步操作会遍历所有源和应用，耗时数分钟。请保留完整日志：

bash

set -o pipefail
git -C ~/.harness-core pull --ff-only
python3 ~/.harness-core/harness.py sync 2>&1 | tee /tmp/kit.log

切勿通过
tail
或
head
管道处理日志。这会丢弃失败信息，并且将harness的退出码替换为分页工具的退出码，导致运行三分之一就失败的任务被误判为成功完成。

如果操作超时，请将其置于后台运行，在聊天中告知，并报告进度而非保持沉默。harness会为每个仓库打印一行日志，最后输出统计信息，因此

tail -1 /tmp/kit.log

可查看当前进度。

Fetch and sync

获取并同步

bash

git clone --depth 1 https://github.com/yoshi-ortiz/harness-core.git ~/.harness-core 2>/dev/null \
  || git -C ~/.harness-core pull --ff-only
python3 ~/.harness-core/harness.py sync

The checkout must already have

git

and Node/npm.

yq

is no longer needed: the manifest is TOML and

tomllib

is standard library. Kit does not install them or add a PATH shim. Use the same Git fetch from Git Bash or PowerShell on Windows. Start a new agent session after syncing because skill lists are read at session start.

bash

git clone --depth 1 https://github.com/yoshi-ortiz/harness-core.git ~/.harness-core 2>/dev/null \
  || git -C ~/.harness-core pull --ff-only
python3 ~/.harness-core/harness.py sync

执行此操作前需已安装

git

和Node/npm。不再需要

yq

：清单采用TOML格式，

tomllib

为Python标准库。套件不会安装这些工具或添加PATH别名。在Windows系统的Git Bash或PowerShell中使用相同的Git获取命令。同步完成后请启动新的agent会话，因为技能列表在会话启动时读取。

Sync

同步

bash

git -C ~/.harness-core pull --ff-only
python3 ~/.harness-core/harness.py sync

Sync is the idempotent re-fetch. Pulling the checkout first refreshes

collection.toml

and the harness code, so a source added upstream arrives with it. There is no separate installer upgrade path.

It fans out over every source in
collection.toml
. Naming one after

sync

filters to sources whose name contains it, so re-fetching twenty-odd repos to update the one that was asked for never happens; see the table above.

python3 ~/.harness-core/harness.py status

prints what is selected, what was detected, and how many skills are installed. Read it before and after.

bash

git -C ~/.harness-core pull --ff-only
python3 ~/.harness-core/harness.py sync

同步是幂等的重新获取操作。先拉取检出内容可刷新

collection.toml

和harness代码，因此上游新增的源会同步到本地。没有单独的安装程序升级路径。

它会遍历
collection.toml
中的所有源。在

sync

后指定一个源名称会过滤出名称包含该字符串的源，避免为了更新一个指定源而重新获取二十多个仓库；详情见上方表格。

python3 ~/.harness-core/harness.py status

会打印已选择的源、检测到的内容以及已安装的技能数量。请在操作前后执行该命令查看状态。

Fix

修复

Every command above starts with the same literal text,

python3 ~/.harness-core/harness.py

, so one standing permission rule covers every mode. A path built from

$HARNESS_DIR

reads as a different command each time and has to be approved again on every run. Relocate the checkout by cloning it elsewhere and writing your own rule; the default path stays literal so the common case is approved once.

Start with

harness status

. It is read-only and answers the two questions that matter first, which agents were detected and which categories are on.

Symptom	Cause	Do
A skill in the repo never arrives	Its manifest entry names a subset, so a skill added later is not in the list	Make the entry bare, or add the new name to the list
A whole category is absent	`selected:` omits it	`harness onboard` , or `--all` to clear the selection
An app cannot see a new skill	Skill lists load at session start	Start a new chat
A skill behaves like an older version	A stale directory survived a rename; nothing deletes it	Remove it from that app's skills dir, then `harness sync`
A skill I just edited syncs without my edit	Sync clones the source from GitHub; an uncommitted or unpushed edit is not there yet	Commit and push, then sync. To test the edit itself, run it from the checkout
agy or Cursor sees nothing while Claude Code is fine	Those dirs are populated by `sync-skills.sh` , not the `skills` CLI	`harness sync` , which runs it after every install
An edit to `collection.toml` changed nothing	Editing installs nothing	`harness sync`

--dry-run

before any run that fans out. Never fix by hand-editing an app's skills dir and stopping there, the manifest is the source of truth and the next sync undoes anything it does not know about.

上述所有命令都以相同的文本开头：

python3 ~/.harness-core/harness.py

，因此一条权限规则即可覆盖所有模式。基于

$HARNESS_DIR

构建的路径每次会被识别为不同的命令，每次运行都需要重新授权。可通过将检出内容克隆到其他位置并编写自定义规则来重新定位；默认路径保持固定，以便常见场景只需授权一次。

先执行

harness status

。该命令为只读，可先回答两个关键问题：检测到哪些agent，以及启用了哪些分类。

症状	原因	解决方法
仓库中的某个技能始终未出现	其清单条目指定了子集，因此后续添加的技能不在列表中	将条目改为无限制，或在列表中添加新技能名称
整个分类缺失	`selected:` 配置中遗漏了该分类	执行 `harness onboard` ，或使用 `--all` 清除选择限制
应用无法识别新技能	技能列表在会话启动时加载	启动新的聊天会话
技能表现为旧版本	重命名后残留了过期目录；没有自动删除机制	从该应用的技能目录中删除过期目录，然后执行 `harness sync`
刚编辑的技能同步后未包含修改内容	同步操作从GitHub克隆源；未提交或未推送的修改不会被同步	提交并推送修改，然后执行同步。如需测试修改内容，请直接从检出目录运行
agy或Cursor无任何内容，而Claude Code正常	这些目录由 `sync-skills.sh` 而非 `skills` CLI填充	执行 `harness sync` ，该操作会在每次安装后运行 `sync-skills.sh`
编辑 `collection.toml` 后无任何变化	编辑操作不会自动安装内容	执行 `harness sync`

在执行任何遍历操作前使用

--dry-run

。切勿通过手动编辑应用的技能目录来修复问题，清单是权威来源，下一次同步会覆盖所有未记录的修改。

Add a skill

添加技能

harness add owner/repo [skill]

records the source and installs it.

--category <name>

files it,

--no-save

installs without touching the manifest.

Name skills only for a subset. A list naming every skill in a repo behaves like a bare entry and then rots, because the repo adds a skill and the list silently stops handing it out. Check a repo's set with

npx skills add <repo> -l

Never pass

--all

npx skills add

harness add owner/repo [skill]

会记录源信息并安装该技能。

--category <name>

用于指定分类，

--no-save

仅安装技能而不修改清单。

仅在需要子集时指定技能名称。列出仓库中所有技能的条目会表现为无限制条目，随后会失效，因为仓库添加新技能后列表不会自动更新。使用

npx skills add <repo> -l

查看仓库的技能集合。

切勿向

npx skills add

传递

--all

参数。

Where skills land

技能存储位置

npx skills add

writes the canonical copy to

~/.agents/skills/

, then symlinks it per agent. Claude Code and Pi are handled by the

skills

CLI. agy, Codex, and Cursor are not, and

scripts/sync-skills.sh

closes that gap after every install. Agents on a mounted OS partition are synced too, with relative symlinks that survive the remount, and anything without a

.harness-managed

marker is left alone.

npx skills add

会将标准副本写入

~/.agents/skills/

，然后为每个agent创建符号链接。Claude Code和Pi由

skills

CLI处理。agy、Codex和Cursor则不通过该CLI处理，

scripts/sync-skills.sh

会在每次安装后填补这一空白。挂载分区上的agent也会被同步，使用相对符号链接可在重新挂载后保留，未标记

.harness-managed

的内容不会被修改。

Release

发布

Tagging the harness is documented once, in the harness README. Copying it here is how the two drift.

harness的打标流程仅在harness README中有文档记录。在此处复制文档会导致两者内容不一致。