skillpack-harvest

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

skillpack-harvest — Editorial workflow for lifting host skills into gbrain

skillpack-harvest — 用于将宿主技能迁移至gbrain的编辑工作流

Convention: see _brain-filing-rules.md for file placement rules. This skill writes into gbrain's own tree, not the brain repo's notes.

This skill is the inverse of

gbrain skillpack scaffold

. Scaffold ships skills downstream (gbrain → host). Harvest lifts proven patterns upstream (host → gbrain) so they become references every other client can scaffold.

约定： 文件放置规则请参考 _brain-filing-rules.md。本技能会写入gbrain自身的目录树，而非brain仓库的笔记目录。

本技能是

gbrain skillpack scaffold

的逆操作。Scaffold用于将技能向下游分发（gbrain → 宿主），Harvest则用于将经过验证的模式向上游迁移（宿主 → gbrain），使其成为所有客户端都能通过脚手架生成的参考技能。

Contract

契约

A harvest is "properly done" when:

The host skill is mature (used in production, recent routing-eval cases pass).
The editorial genericization in Phase 3 has scrubbed every fork-specific reference (names, real entities, internal channels).
```
gbrain skillpack harvest --dry-run
```
previewed the file set.

The real

gbrain skillpack harvest <slug> --from <host>

succeeded with

status: harvested

(no privacy-lint hits).

bun test test/skills-conformance.test.ts

passes on the new

skills/<slug>/SKILL.md

The user has reviewed the diff in gbrain and explicitly approved the commit.

If any of these is incomplete, the skill is NOT yet harvested — the files may sit in gbrain's working tree, but they're not landed.

当满足以下条件时，才算完成一次合规的迁移：

宿主技能已成熟（已投入生产使用，近期routing-eval用例全部通过）。
第3阶段的编辑通用化处理已清除所有分支特定引用（名称、真实实体、内部渠道）。
已通过
```
gbrain skillpack harvest --dry-run
```
预览文件集。
执行真实的
```
gbrain skillpack harvest <slug> --from <host>
```
命令后返回
```
status: harvested
```
（无隐私检查命中项）。

针对新生成的

skills/<slug>/SKILL.md

，

bun test test/skills-conformance.test.ts

测试通过。

用户已查看gbrain中的差异并明确批准提交。

如果以上任意一项未完成，则技能尚未完成迁移——文件可能存放在gbrain的工作目录中，但并未正式落地。

Output Format

输出格式

This skill produces three artifacts in gbrain's working tree:

skills/<harvested-slug>/SKILL.md

(and any sibling files like

routing-eval.jsonl

)

Paired source files at their mirror paths (e.g.
```
src/commands/<slug>.ts
```
) when the host SKILL.md declared them in frontmatter
```
sources:
```
An updated
```
openclaw.plugin.json
```
with the new slug added to
```
skills:
```
(sorted)

The session output to the user is a one-line success summary plus a list of files written. JSON mode (

--json

) returns the full

HarvestResult

shape for machine consumption.

本技能会在gbrain的工作目录中生成三类产物：

skills/<harvested-slug>/SKILL.md

（以及

routing-eval.jsonl

等同级文件）

镜像路径下的配对源文件（例如，若宿主SKILL.md在前置元数据
```
sources:
```
中声明了源文件，则会生成
```
src/commands/<slug>.ts
```
）
更新后的
```
openclaw.plugin.json
```
，其中
```
skills:
```
数组会添加新的slug并排序

向用户输出的会话内容为一行成功摘要加上已写入文件列表。JSON模式（

--json

）会返回完整的

HarvestResult

结构供机器读取。

Anti-Patterns

反模式

Skipping the dry-run. Always preview first. Files land in gbrain's working tree; cleanup is a
```
git checkout
```
away, but you shouldn't need to.
Trusting the linter alone. The default regex set catches the common cases. It doesn't catch every proper noun. Phase 3 (the editorial pass) is the primary defense.
Harvesting
--no-lint
without justification. The lint exists for a reason. If you bypass it, document why in the commit.
Harvesting a skill that's still in flux. Wait until the host version stabilizes. Otherwise you'll harvest, then re-harvest, then re-harvest, and that churns gbrain's bundle for no benefit.
Moving files instead of copying. Harvest is a copy. The host retains its skill. Don't
```
rm -rf
```
the source after harvesting.
Harvesting batch (multiple skills at once). Not supported, and for good reason — the editorial review per skill is real work.

跳过预演（dry-run）：务必先进行预览。文件会存入gbrain的工作目录，虽然可以通过
```
git checkout
```
清理，但最好不要走到这一步。
仅依赖检查器：默认正则集只能捕获常见情况，无法识别所有专有名词。第3阶段的编辑处理才是主要的防御手段。
无正当理由使用
--no-lint
：检查器的存在是有意义的。如果要绕过它，请在提交中说明原因。
迁移仍在变动的技能：等待宿主版本稳定后再进行迁移。否则会反复迁移，无端造成gbrain技能包的混乱。
移动而非复制文件：迁移是复制操作，宿主会保留其技能。迁移后不要删除源文件。
批量迁移（同时迁移多个技能）：不支持该操作，且有充分理由——每个技能的编辑审查都是实打实的工作。

When to invoke

调用时机

The user developed a skill in their host fork (Wintermute, Neuromancer, Zion, etc.) and wants other gbrain clients to be able to use it
A skill has proven itself in production and is ready to generalize
The user explicitly asks to "harvest" or "publish" a skill upstream

Do NOT invoke when:

The skill is still in flux locally — let it stabilize first
The skill references private content that can't be generalized
The user just wants to share a one-off draft (use a gist instead)

用户在宿主分支（Wintermute、Neuromancer、Zion等）中开发了技能，希望其他gbrain客户端能够使用该技能
技能已在生产环境中验证，准备好进行通用化处理
用户明确要求将技能向上游“迁移”或“发布”

请勿在以下情况调用：

技能在本地仍处于变动状态——先让它稳定下来
技能引用了无法通用化的私有内容
用户仅想分享一次性草稿（改用gist即可）

Preconditions

前置条件

Before running this skill, confirm:

The skill is mature. Recent
```
routing-eval.jsonl
```
cases pass; the skill has been used in production at least a few times.
The skill is generalizable. Strip-test in your head: replace every fork-specific name. Does it still make sense as a skill?
The user owns the gbrain checkout. The harvest writes into gbrain's working tree. They'll review and commit. Don't harvest into a checkout the user doesn't intend to commit from.

运行本技能前，请确认：

技能已成熟：近期
```
routing-eval.jsonl
```
用例全部通过；技能已在生产环境中使用过至少几次。
技能可通用化：在脑中进行剥离测试：替换所有分支特定名称后，该技能是否仍有意义？
用户拥有gbrain的检出目录权限：迁移会写入gbrain的工作目录，用户需要进行审查和提交。不要将技能迁移到用户不打算提交的检出目录中。

Workflow

工作流

Phase 1 — Plan

第1阶段 — 规划

Ask the user:

What slug should the harvested skill have? (Slugs must be kebab-case, globally unique in the gbrain bundle.)
Which host repo is the source? (Path to repo root, not to the skill directory — e.g.
```
~/git/wintermute
```
, not
```
~/git/wintermute/skills/foo
```
.)
Should paired source files come along? (Check the host SKILL.md's frontmatter
```
sources:
```
array.)

询问用户：

迁移后的技能应使用什么slug？（slug必须为短横线分隔格式，且在gbrain技能包中全局唯一。）
源宿主仓库是哪个？（仓库根目录路径，而非技能目录——例如
```
~/git/wintermute
```
，而非
```
~/git/wintermute/skills/foo
```
。）
是否需要同步配对源文件？（查看宿主SKILL.md的前置元数据
```
sources:
```
数组。）

Phase 2 — Dry-run + privacy-lint preview

第2阶段 — 预演 + 隐私检查预览

Run the CLI with

--dry-run

bash

gbrain skillpack harvest <slug> --from <host-repo-root> --dry-run

The output shows:

Which files would land in gbrain's tree
Whether paired sources are included
(Implicit) The skill's frontmatter triggers — read them and check they generalize

Do not skip the dry-run. The privacy linter only runs on a real harvest, but the dry-run preview lets you see the files before they land. Spot-check the SKILL.md and any paired source for things the linter might miss (proper nouns, internal project names, etc.).

使用

--dry-run

参数运行CLI：

bash

gbrain skillpack harvest <slug> --from <host-repo-root> --dry-run

输出内容包括：

哪些文件会存入gbrain的目录树
是否包含配对源文件
（隐含）技能的前置元数据触发条件——请阅读并确认其已通用化

请勿跳过预演。隐私检查器仅在真实迁移时运行，但预演预览可以让你在文件落地前查看内容。抽查SKILL.md和所有配对源文件，找出检查器可能遗漏的内容（专有名词、内部项目名称等）。

Phase 3 — Genericization checklist (the editorial pass)

第3阶段 — 通用化检查清单（编辑处理）

Before running the real harvest, walk the host's

skills/<slug>/

files and apply this checklist. If anything matches, edit the host file FIRST, then run harvest.

Fork-specific names → generic phrasing
- ```
Wintermute
```
  →
```
your OpenClaw
```
  (or
```
OpenClaw deployment
```
  )
- ```
Neuromancer
```
  ,
```
Zion
```
  ,
```
<personal-fork-name>
```
  → same treatment
- Personal first names (
```
garry
```
  ,
```
jane
```
  , etc.) →
```
the user
```
  /
```
you
```
  / a generic placeholder
Real entities → placeholders
- Real people, companies, deals, funds → placeholder slugs (
```
alice-example
```
  ,
```
acme-example
```
  ,
```
fund-a
```
  , etc.)
- Email addresses → strip entirely OR use
```
example@example.com
```
- Internal Slack channels →
```
#some-channel
```
  or strip
- Specific tracker IDs / Linear ticket numbers → strip
Fork-specific conventions → references
- Mentions of
```
<host-repo>/docs/...
```
  files → either lift the doc into gbrain OR replace with a generic placeholder explanation
- Mentions of
```
<host-repo>/skills/<other-fork-only-skill>
```
  → either decide to harvest that one too, or replace with a generic pattern reference
Triggers array generalizes
- Read every entry in frontmatter
```
triggers:
```
  . None should reference the user's name, fork name, or internal tools.
- "Have garry sign off on it" → "have the user sign off on it"
routing-eval.jsonl examples are scrubbed
- Open
```
skills/<slug>/routing-eval.jsonl
```
  . Every
```
intent
```
  field gets the same scrub as
```
triggers:
```
  .
Code comments + log strings
- If a paired source is going to be harvested, walk it for the same private-pattern leaks. Comments are the most common hiding spot.

在执行真实迁移前，遍历宿主的

skills/<slug>/

文件并应用以下检查清单。如果发现匹配项，请先编辑宿主文件，再执行迁移。

分支特定名称 → 通用表述
- ```
Wintermute
```
  →
```
你的OpenClaw
```
  （或
```
OpenClaw部署实例
```
  ）
- ```
Neuromancer
```
  、
```
Zion
```
  、
```
<个人分支名称>
```
  → 采用相同处理方式
- 个人名字（
```
garry
```
  、
```
jane
```
  等） →
```
用户
```
  /
```
你
```
  / 通用占位符
真实实体 → 占位符
- 真实人物、公司、交易、基金 → 占位符slug（
```
alice-example
```
  、
```
acme-example
```
  、
```
fund-a
```
  等）
- 电子邮件地址 → 完全删除或使用
```
example@example.com
```
- 内部Slack频道 →
```
#some-channel
```
  或删除
- 特定跟踪器ID / Linear工单编号 → 删除
分支特定约定 → 引用内容
- 提及
```
<host-repo>/docs/...
```
  文件 → 要么将文档迁移至gbrain，要么替换为通用占位符说明
- 提及
```
<host-repo>/skills/<other-fork-only-skill>
```
  → 要么决定同时迁移该技能，要么替换为通用模式引用
触发条件数组已通用化
- 阅读前置元数据
```
triggers:
```
  中的每一项。不得引用用户名、分支名称或内部工具。
- 示例：将“让garry签字确认”改为“让用户签字确认”
routing-eval.jsonl示例已清理
- 打开
```
skills/<slug>/routing-eval.jsonl
```
  。每个
```
intent
```
  字段都要像
```
triggers:
```
  一样进行清理。
代码注释 + 日志字符串
- 如果要迁移配对源文件，请遍历文件查找相同的隐私泄露模式。注释是最常见的隐藏点。

Phase 4 — Real harvest

第4阶段 — 真实迁移

Once Phase 3 is complete, run the real harvest:

bash

gbrain skillpack harvest <slug> --from <host-repo-root>

Default behavior:

Path-confinement + symlink rejection at file copy
Privacy linter runs against
```
~/.gbrain/harvest-private-patterns.txt
```
(plus built-in defaults:
```
\bWintermute\b
```
, email, Slack channels)
On any match → rollback (delete the harvested files) + exit non-zero
```
openclaw.plugin.json
```
updated to add the slug, sorted

Outcomes:

```
harvested
```
— success, manifest updated, files in gbrain's tree
```
lint_failed
```
— privacy linter caught something. Go back to Phase 3, scrub the host file, retry.
```
slug_collision
```
— gbrain already has a skill at that slug. Either use a different slug, or pass
```
--overwrite-local
```
if you really mean to replace.

完成第3阶段后，执行真实迁移：

bash

gbrain skillpack harvest <slug> --from <host-repo-root>

默认行为：

文件复制时会进行路径限制和符号链接拒绝
隐私检查器会对照
```
~/.gbrain/harvest-private-patterns.txt
```
（加上内置默认规则：
```
\bWintermute\b
```
、电子邮件、Slack频道）运行
一旦匹配到内容 → 回滚（删除已迁移文件）并返回非零退出码
更新
```
openclaw.plugin.json
```
以添加slug并排序

结果：

```
harvested
```
— 成功，清单已更新，文件存入gbrain目录树
```
lint_failed
```
— 隐私检查器检测到问题。回到第3阶段，清理宿主文件后重试。
```
slug_collision
```
— gbrain中已存在该slug的技能。要么使用其他slug，要么确实需要替换时传入
```
--overwrite-local
```
参数。

Phase 5 — Verify in gbrain

第5阶段 — 在gbrain中验证

After a successful harvest:

```
bun test test/skills-conformance.test.ts
```
— confirms the new SKILL.md meets the frontmatter contract.
```
gbrain skillpack check --strict
```
— confirms no drift between bundle and gbrain's own checkout.
```
gbrain skillpack list
```
— confirms the slug shows up in the bundle.

Review the diff:

cd <gbrainRoot> && git diff -- skills/<slug>/

Commit the additions in gbrain (do NOT commit any leftover files in the host repo — harvest is a copy, not a move).

迁移成功后：

执行
```
bun test test/skills-conformance.test.ts
```
— 确认新的SKILL.md符合前置元数据契约。
执行
```
gbrain skillpack check --strict
```
— 确认技能包与gbrain自身检出目录之间无差异。
执行
```
gbrain skillpack list
```
— 确认slug已出现在技能包中。

查看差异：

cd <gbrainRoot> && git diff -- skills/<slug>/

在gbrain中提交新增内容（请勿提交宿主仓库中的残留文件——迁移是复制操作，而非移动操作）。

Phase 6 — Downstream announcement (optional)

第6阶段 — 下游通知（可选）

If other gbrain clients should pick up the new skill:

Note it in
```
CHANGELOG.md
```
under "Skills added" for the next release
Tag the user / contributor in the PR if the skill came from someone outside the core team

如果希望其他gbrain客户端获取新技能：

在
```
CHANGELOG.md
```
的“新增技能”部分记录该技能，用于下一个版本发布
如果技能来自核心团队外部的贡献者，请在PR中标记该用户/贡献者

Bypass:

--no-lint

绕过检查：

--no-lint

The privacy linter is the safety net. The editorial pass is the primary defense. If you've completed Phase 3 thoroughly and the linter is still firing on a false positive, use

--no-lint

bash

gbrain skillpack harvest <slug> --from <host-repo-root> --no-lint

Document the bypass in the commit message. Future maintainers should be able to see WHY the lint was bypassed (e.g. "Wintermute appears in a citation, not a real reference — verified manually").

Never bypass the linter on a casual basis. The whole point of the default-on lint is that real names occasionally slip through the editorial pass.

隐私检查器是安全网，编辑处理才是主要防御手段。如果已彻底完成第3阶段，但检查器仍误报，可以使用

--no-lint

：

bash

gbrain skillpack harvest <slug> --from <host-repo-root> --no-lint

请在提交信息中记录绕过检查的原因。未来的维护者需要知道为什么要绕过检查（例如：“Wintermute出现在引用中，而非真实引用——已手动验证”）。

切勿随意绕过检查。默认开启检查的意义在于，真实名称偶尔会在编辑处理中被遗漏。

What harvest does NOT do

迁移不包含的操作

It does NOT move files (it copies). The host's
```
skills/<slug>/
```
stays in place.
It does NOT auto-scrub names. The editorial pass is human-driven.
It does NOT publish to npm or a remote bundle. It writes to gbrain's working tree; the user commits + ships via the normal gbrain release process.
It does NOT support
```
--all
```
(no batch harvest). One skill at a time keeps the editorial review tractable.

不会移动文件（只会复制）。宿主的
```
skills/<slug>/
```
会保留原位。
不会自动清理名称。编辑处理由人工完成。
不会发布到npm或远程技能包。只会写入gbrain的工作目录；用户需通过gbrain的常规发布流程提交并分发。
不支持
```
--all
```
参数（无批量迁移）。一次迁移一个技能才能保证编辑审查的可操作性。

Files this skill touches

本技能涉及的文件

gbrain's
```
skills/<slug>/
```
— every file in the host skill dir (copy)
gbrain's mirror path for declared paired sources (e.g.
```
src/commands/<slug>.ts
```
if the host SKILL.md declares it in frontmatter)
gbrain's
```
openclaw.plugin.json
```
— adds the slug to
```
skills:
```
array, sorted alphabetically

gbrain的
```
skills/<slug>/
```
— 宿主技能目录中的所有文件（复制）
gbrain中已声明配对源文件的镜像路径（例如，若宿主SKILL.md在前置元数据中声明了源文件，则会生成
```
src/commands/<slug>.ts
```
）
gbrain的
```
openclaw.plugin.json
```
— 向
```
skills:
```
数组添加slug并按字母顺序排序

skillpack-harvest

Original

Translation

skillpack-harvest — Editorial workflow for lifting host skills into gbrain

skillpack-harvest — 用于将宿主技能迁移至gbrain的编辑工作流

Contract

契约

Output Format

输出格式

Anti-Patterns

反模式

When to invoke

调用时机

Preconditions

前置条件

Workflow

工作流

Phase 1 — Plan

第1阶段 — 规划

Phase 2 — Dry-run + privacy-lint preview

第2阶段 — 预演 + 隐私检查预览

Phase 3 — Genericization checklist (the editorial pass)

第3阶段 — 通用化检查清单（编辑处理）

Phase 4 — Real harvest

第4阶段 — 真实迁移

Phase 5 — Verify in gbrain

第5阶段 — 在gbrain中验证

Phase 6 — Downstream announcement (optional)

第6阶段 — 下游通知（可选）

Bypass:
`--no-lint`

绕过检查：
`--no-lint`

What harvest does NOT do

迁移不包含的操作

Files this skill touches

本技能涉及的文件

skillpack-harvest

Original

Translation

skillpack-harvest — Editorial workflow for lifting host skills into gbrain

skillpack-harvest — 用于将宿主技能迁移至gbrain的编辑工作流

Contract

契约

Output Format

输出格式

Anti-Patterns

反模式

When to invoke

调用时机

Preconditions

前置条件

Workflow

工作流

Phase 1 — Plan

第1阶段 — 规划

Phase 2 — Dry-run + privacy-lint preview

第2阶段 — 预演 + 隐私检查预览

Phase 3 — Genericization checklist (the editorial pass)

第3阶段 — 通用化检查清单（编辑处理）

Phase 4 — Real harvest

第4阶段 — 真实迁移

Phase 5 — Verify in gbrain

第5阶段 — 在gbrain中验证

Phase 6 — Downstream announcement (optional)

第6阶段 — 下游通知（可选）

Bypass: --no-lint

绕过检查：--no-lint

What harvest does NOT do

迁移不包含的操作

Files this skill touches

本技能涉及的文件

Bypass:
`--no-lint`

绕过检查：
`--no-lint`