gbrain/docs/skillpack-anatomy.md

Skillpack anatomy

The canonical one-page reference for what a third-party gbrain skillpack looks like. The reference pack at examples/skillpack-reference/ is the live artifact this page describes; clone its tree and you have a 10/10 starting point.

Tree

my-skillpack/
├── skillpack.json                # manifest (cathedral fields declared)
├── skills/
│   └── <skill-slug>/
│       ├── SKILL.md              # frontmatter + body, agent-readable
│       └── routing-eval.jsonl    # >= 5 intents pinning trigger -> skill
├── runbooks/
│   └── bootstrap.md              # post-scaffold display (NOT an executor)
├── test/
│   └── *.test.ts                 # bun:test unit tests
├── e2e/
│   └── *.test.ts                 # integration tests, gated on DATABASE_URL
├── evals/
│   └── *.judge.json              # LLM-judge eval configs (>= 3 cases each)
├── CHANGELOG.md                  # Keep-a-Changelog shape
├── LICENSE                       # SPDX-matching text
├── README.md
└── .gitignore

gbrain skillpack init <name> scaffolds this exact tree, pre-filled with stubs that score 10/10 on gbrain skillpack doctor . --quick immediately. Replace the stubs with real content, run the doctor between edits, and gbrain skillpack pack produces a deterministic <name>-<version>.tgz ready to publish to the registry.

How the agent uses a scaffolded pack

After gbrain skillpack scaffold <source> lands the files:

1. The user's agent walks skills/*/SKILL.md frontmatter and reads each pack's triggers: array on startup or per-message.
2. When a user phrasing matches a trigger, the agent reads that SKILL.md body top-to-bottom as in-context instructions.
3. gbrain DISPLAYS runbooks/bootstrap.md once after the scaffold but does NOT auto-execute it. The agent decides whether to walk the steps. This is the codex T1 supply-chain hardening: an auto-walker would let a malicious pack mutate the user's brain on install, which is how npm postinstall attacks happen.

How the doctor scores a pack

Ten binary dimensions. Each is checked by a pure function in src/core/skillpack/rubric.ts and returns {passed, detail, fix_hint}. The doctor walks them in order and prints the score + per-dimension status + paste-ready fix for every failure.

Core dimensions (5; must all pass to publish at any tier)

#	Name	Description	Auto-fixable
1	manifest_valid	skillpack.json passes the v1 schema validator	no
2	skills_have_skill_md	every listed skill has SKILL.md with valid frontmatter (name, description, triggers)	no
3	routing_evals_present	every skill has routing-eval.jsonl with >= 5 intents	yes
4	skills_have_unique_triggers	no two skills in this pack share an exact trigger phrase (MECE)	no
5	changelog_present_and_current	CHANGELOG.md present and contains an entry for the current version	yes

Quality badges (5; earn for tier eligibility)

#	Name	Description	Auto-fixable
6	unit_tests_present	pack declares unit_tests[] with at least one matching test file	yes
7	e2e_tests_present	pack declares e2e_tests[] with at least one matching test file	yes
8	llm_eval_present	pack declares llm_evals[] with >= 1 file containing >= 3 cases	yes
9	bootstrap_runbook_present	pack declares runbooks.bootstrap and the file is non-empty	yes
10	license_present	LICENSE file exists at the pack root (informational badge)	yes

Generated from src/core/skillpack/rubric.ts by bun run scripts/build-skillpack-anatomy.ts.

Tier eligibility

Tier	Requirement
endorsed	All 5 core + all 5 badges, plus Garry's endorsements.json overlay in the registry repo
community	All 5 core + >= 3 of 5 badges. Default tier on PR merge.
experimental	All 5 core + < 3 badges
blocked	Any core dimension fails

CLI reference (third-party path)

# Publisher side
gbrain skillpack init my-pack         # scaffold the tree
gbrain skillpack doctor my-pack       # see the score + fix hints
gbrain skillpack doctor my-pack --fix --yes  # auto-scaffold missing pieces
gbrain skillpack pack my-pack         # deterministic tarball + SHA-256

# Consumer side
gbrain skillpack search <query>       # browse the registry
gbrain skillpack info <name>          # show full pack metadata
gbrain skillpack scaffold <source>    # owner/repo, https, ./dir, ./*.tgz
gbrain skillpack registry --url X     # point at a custom registry

Brain-resident packs

A brain/source repo can carry its own publishable skillpack (brain_resident: true in skillpack.json, plus a schema_pack declaration). Scaffold one with:

gbrain skillpack init-brain-pack <name>   # inside the brain repo; --dry-run to preview

Connecting harnesses discover the pack on gbrain sources add, and remote agents reach it over MCP via the source-scoped list_brain_skillpack op + get_skill --source_id (gated by the mcp.publish_skills config key). The anatomy above applies unchanged — a brain-resident pack is a normal pack that happens to live inside a brain repo.

See also

• examples/skillpack-reference/ — the live 10/10 reference pack
• docs/designs/SKILLPACK_REGISTRY_V1_SPEC.md — strategic spec + decisions
• docs/guides/skillpacks-as-scaffolding.md — v0.36 scaffold/reference model