skillpack harvest
- Repo stars 18,413
- Author repo gbrain
- Domain
- Other
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 92 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @garrytan · v0.33.0 · no license declared
- Token usage
- Lean
- Setup complexity
- Plug-and-play
- External API key
- Not required
- Operating systems
- macOS · Linux · Windows
- Runtime requirements
- No explicit requirements detected
- Detected file/system behavior
-
- Read-only
- Write / modify
- Network behavior
- Local-only
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
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`.)
Run the CLI with `--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
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`)
Once Phase 3 is complete, run the real harvest: 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)
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.
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
# 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 (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)
## 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/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
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**
- `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
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.
### 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. "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.
## 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
Listed in source order.
sections -> Contract → Output Format → Anti-Patterns → When to invoke → Preconditions → Workflow
terms -> Convention · Skipping the dry-run. · Trusting the linter alone. · Harvesting --no-lint without justification. · Harvesting a skill that's still in flux. · Moving files instead of copying. · Harvesting batch (multiple skills at once). · The skill is mature.
files/cmd -> gbrain skillpack scaffold · gbrain skillpack harvest --dry-run · gbrain skillpack harvest <slug> --from <host> · status: harvested · bun test test/skills-conformance.test.ts · skills/<slug>/SKILL.md · skills/<harvested-slug>/SKILL.md · routing-eval.jsonl
body sha256 -> 83f9b71efbcd
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).
Output Format
This skill produces three artifacts in gbrain's working tree:
skills/<harvested-slug>/SKILL.md(and any sibling files likerouting-eval.jsonl) Paired source files at their mirror paths (e.g.src/commands/<slug>.ts) when the host SKILL.md declared themAnti-Patterns
Skipping the dry-run. Always preview first. Files land in gbrain's working tree; cleanup is a
git checkoutaway, 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 (theWhen 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:
Preconditions
Before running this skill, confirm: The skill is mature. Recent
routing-eval.jsonlcases 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?