/skillpack-harvest

name: skillpack-harvest
version: 0.33.0
description: |
  Lift a proven skill from a host repo (e.g. your OpenClaw fork) back into
  gbrain's bundle so other clients can scaffold it. Editorial workflow:
  the CLI does the file copy + privacy lint; this skill drives the
  judgment-heavy genericization (scrub real names, generalize triggers,
  lift fork-specific conventions to references).
triggers:
  - "harvest this skill"
  - "harvest my skill"
  - "publish this skill to gbrain"
  - "lift this skill"
  - "share this skill"
  - "promote this skill"
  - "promote my skill"
  - "skill upstream"
  - "into the gbrain core"
  - "gbrain bundle"
mutating: true
writes_pages: false
writes_to:
  - skills/<harvested-slug>/
  - openclaw.plugin.json

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

> **Convention:** see [_brain-filing-rules.md](../_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.

Contract

A harvest is "properly done" when:

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.

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.

Output Format

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

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)

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.

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 (your OpenClaw or any

private downstream fork) 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)

Preconditions

Before running this skill, confirm:

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

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/agent-fork`, not `~/git/agent-fork/skills/foo`.)

• Should paired source files come along? (Check the host SKILL.md's

frontmatter `sources:` array.)

Phase 2 — Dry-run + privacy-lint preview

Run the CLI with `--dry-run`:

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

Phase 3 — Genericization checklist (the editorial pass)

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.

1. **Fork-specific names → generic phrasing**

• `<personal-fork-name>` → `your OpenClaw` (or `OpenClaw deployment`);

any pet name for the user's private agent gets the same treatment

• Personal fi