Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

docs(key-files): spring-loaded skill index entry

garrytane6d50a996003
diff --git a/docs/architecture/key-files/skills.md b/docs/architecture/key-files/skills.md
index 163b71c357..5cd34d0f92 100644
--- a/docs/architecture/key-files/skills.md
+++ b/docs/architecture/key-files/skills.md
@@ -9,6 +9,8 @@ Current behavior and load-bearing invariants; history belongs in Git and CHANGEL
- `skills/skillpack-check/SKILL.md` — report-only health protocol. `actions[]` is untrusted proposal data, not execution authority; schema, service, page and paid embedding changes require separate explicit action/scope approval. `test/skillpack-check-report-only.test.ts` executes the documented reporting snippet against a hostile synthetic action and proves it creates no file.
+- `src/cli/commands/bundled-skill.ts` + `src/core/skills/{bundled,spring-index,index-block}.ts` + `src/core/skills/bundled-skills.generated.ts` + `src/core/setup/skills-block.ts` + `src/core/bootstrap/harness-skills-index.ts` + `scripts/{generate-bundled-skills.ts,check-skills-embedded.sh}` — the opt-in spring-loaded skill index (`--skill-loading spring`; user docs: `docs/guides/setup.md` "Skill loading (opt-in)"). `gbrain bundled-skill [<name>] [--asset <path>] [--json]` is pre-connect and engine-free (`thinClient: 'none'`, `skipStartupHooks`): it prints a bundled skill or a file it names from the embedded map, where a name or asset is a lookup key and never a path; the set is the plugin lane (`skills/plugin-lanes.json`), `owner` audience on the host and `downstream` only on a thin client (host-only skills answer `skill_not_found`). The embedded module is generated (`bun run scripts/generate-bundled-skills.ts`, `--check` fails when stale) and holds only membership, audience and asset lists; description and triggers are read from the embedded SKILL.md at runtime. `spring-index.ts` renders one line per skill from frontmatter `triggers:` under `SKILL_INDEX_BUDGET_BYTES` (6144), trimming triggers before ever dropping a skill and refusing (`SkillIndexTooLarge`) rather than truncating. `skills-block.ts` writes the `<!-- gbrain:skills:begin/end -->` block beside the brain-first block in the same file, records the choice in `<configDir>/skill-loading.json`, refuses to write when the recorded launcher (`<launcher> bundled-skill --json`) serves another catalog, adds one `Bash(<launcher> bundled-skill:*)` allow rule on Claude Code only when absent and removes it only when it added it, and backs `setup --skills-index-only`; `setup`, `connect --install`, `harness connect --install` and `bootstrap harness` (`harness-skills-index.ts`) share it, and a requested index that cannot be written exits non-zero. doctor `harness_wiring` (`withSkillsIndex`) reports a stale, absent or damaged index as information and warns only when the launcher is gone or the record is unreadable; `check-resolvable` and `skill_currency` read past the block through `skillsIndexedIn`. `check-skills-embedded.sh` compiles a binary and proves it serves every bundled file byte-identical to `skills/` (`test/bundled-skill-cli.test.ts`, `test/spring-skill-index.test.ts`, `test/setup-skill-loading.test.ts`, `test/skill-loading-lanes.test.ts`).
+
- `src/core/audit-skill-brain-first.ts` — snapshot+diff JSONL audit at `~/.gbrain/audit/skill-brain-first-YYYY-Www.jsonl` (ISO-week rotated, honors `GBRAIN_AUDIT_DIR` via shared `resolveAuditDir()`). `recordBrainFirstRun(results)` reads the previous snapshot at `~/.gbrain/audit/skill-brain-first-snapshot.json`, diffs against current results, writes transition events (`detected | resolved | fixed`) one line per change, then atomically overwrites the snapshot via `.tmp + rename`. **Transition-only writes** — a stable brain produces 0 audit lines per doctor run. `readRecentBrainFirstEvents(days)` is the readback path for the future `skill_brain_first_trend` doctor check. Snapshot file is last-writer-wins under concurrent doctor runs; subsequent runs reconcile.
- `src/core/skill-brain-first.ts` — pure analyzer. `analyzeSkillBrainFirst(skillPath, content): SkillBrainFirstResult` walks the compliance ladder for every SKILL.md: (1) absent external-lookup pattern → `no_external`; (2) `brain_first: exempt` frontmatter → `exempt_frontmatter`; (3) canonical `> **Convention:** see [conventions/brain-first.md](../...)` callout → `compliant_callout`; (4) explicit `## Phase 1: Brain` heading → `compliant_phase`; (5) first `gbrain search`/`query`/`get_page` reference precedes first external pattern in the BODY (frontmatter stripped) → `compliant_position`; (6) else `missing_brain_first` warn. External pattern set: word-boundary regex over `web_search`, `web_fetch`, `exa`, `perplexity`, `happenstance`, `crustdata`, `captain_api`, `firecrawl`. Position scan is BODY-ONLY so a `tools: [web_search]` frontmatter declaration doesn't false-flag the skill. The 40-name `FORMERLY_HARDCODED_EXEMPT` list is preserved so doctor can emit a "this used to be auto-exempt, declare `brain_first: exempt` if still appropriate" hint. Consumed by 3 surfaces: doctor check, skillify-check item 12, dry-fix MISSING_RULE_PATTERNS.