Skip to content

skillpack-anatomy.md

Latest commit

 

History

History
112 lines (90 loc) · 4.96 KB

skillpack-anatomy.md

File metadata and controls

112 lines (90 loc) · 4.96 KB
Raw

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

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