skillpack-harvest

# 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. ## When it fails Follow the [agent operator protocol](../conventions/agent-operator-protocol.md) for any gbrain error `code`, exit code, `[AGENT]` block or notice block. Specific to this skill: - `lint_failed`: the privacy linter caught a real name or private detail; go back to Phase 3 and replace it with placeholders (`alice-example`, `acme-example`, `fund-a`). - `gbrain skillpack check --strict` reports drift after the harvest: regenerate the bundle and re-run; never ship a drifting skillpack. ## 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`: ```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.). ### 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 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 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 — the canonical private fork name, email addresses, Slack channels; see `src/core/skillpack/harvest-lint.ts`) - 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. ### Phase 5 — Verify in gbrain After a successful harvest: 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) 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 ## Bypass: `--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. "the fork name 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. ## 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, without removing OpenClaw-native plugin fields like `id`, `configSchema`, or `contracts`