skillpack-harvest — Editorial workflow for lifting host skills into 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.

gbrain skillpack scaffold

Contract

1. The host skill is mature (used in production, recent routing-eval cases pass).
2. The editorial genericization in Phase 3 has scrubbed every fork-specific reference (names, real entities, internal channels).

3. gbrain skillpack harvest --dry-run

   previewed the file set.
4. The real

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

   succeeded with

   status: harvested

   (no privacy-lint hits).

5. bun test test/skills-conformance.test.ts

   passes on the new

   skills/<slug>/SKILL.md

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

Output Format

1. skills/<harvested-slug>/SKILL.md

   (and any sibling files like

   routing-eval.jsonl

   )
2. Paired source files at their mirror paths (e.g.

   src/commands/<slug>.ts

   ) when the host SKILL.md declared them in frontmatter

   sources:

3. An updated

   openclaw.plugin.json

   with the new slug added to

   skills:

   (sorted)

--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.

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

• 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)

Preconditions

1. The skill is mature. Recent

   routing-eval.jsonl

   cases pass; the skill has been used in production at least a few times.
2. The skill is generalizable. Strip-test in your head: replace every fork-specific name. Does it still make sense as a skill?
3. 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.

Workflow

Phase 1 — Plan

• 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.)

Phase 2 — Dry-run + privacy-lint preview

--dry-run

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

• 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

Phase 3 — Genericization checklist (the editorial pass)

skills/<slug>/

1. 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
2. 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
3. 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
4. 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"
5. routing-eval.jsonl examples are scrubbed
   • Open

     skills/<slug>/routing-eval.jsonl

     . Every

     intent

     field gets the same scrub as

     triggers:

     .
6. 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.

Phase 4 — Real harvest

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

• 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

• 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.

Phase 5 — Verify in gbrain

1. bun test test/skills-conformance.test.ts

   — confirms the new SKILL.md meets the frontmatter contract.

2. gbrain skillpack check --strict

   — confirms no drift between bundle and gbrain's own checkout.

3. gbrain skillpack list

   — confirms the slug shows up in the bundle.
4. Review the diff:

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

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

Phase 6 — Downstream announcement (optional)

• 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

Bypass:

--no-lint

--no-lint

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

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.

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