Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
Skill resolver catalogs: document the new sources and name them in RESOLVER_FEATURES
garrytana460dad54201
diff --git a/docs/architecture/key-files/skills.md b/docs/architecture/key-files/skills.mdindex ee94ff1238..a438979a3d 100644--- a/docs/architecture/key-files/skills.md+++ b/docs/architecture/key-files/skills.md@@ -51,7 +51,7 @@ Contract schemas: `docs/schemas/skill-resolver.v1.*.json`. Every module under- `src/core/skills/resolver/tokenize.ts` — `splitWords` (shared with `scoreSkillMatch` in `skill-catalog.ts`) and `lexTerms`, the frozen Step 1 term rule (stopwords, light stemming); CJK runs become overlapping bigrams. Vectors: `test/fixtures/skill-resolver/tokenizer-vectors.json`.- `src/core/skills/resolver/index-format.ts` — `index.bin` (magic `GBSKIDX1`, JSON header, field-length averages, per-skill lengths, sorted term dictionary, flat postings with per-field tf, per-skill meta), byte-identical for identical records; `VARIANT_PARAMS` (D and T constants), `fieldText`, `summaryOf` (the description cut at 120 characters), `IndexReader` (lazy postings and meta reads).- `src/core/skills/resolver/build.ts` — `buildSkillIndex` under the catalog lease (variant choice: T at a 25% trigger-or-routing share, kept down to 20%; publication only while the lease is held and the directory exists, receipt written last), `catalogStatus` (content tier: re-reads the source and re-hashes the index), `removeSkillIndex` (rename then delete, so a concurrent build fails `skill_index_removed`), `listCatalogs`, `sessionStatus`, `dirFingerprintSlice`, `catalogHash`.-- `src/core/skills/resolver/sources.ts` — the three sources: `--dir` (real paths only, symlinks out of the root skipped, breadth-first, first id wins, plugin namespace from `.claude-plugin/plugin.json`, stat fingerprint), `--bundled` (dynamic import of `src/core/skills/bundled.ts`, never the operations table) and `--from-json` (8 MB, 10,000 entries); `applyRouting`; bounds (`MAX_SKILLS`, `MAX_DIRS_VISITED`, `MAX_DEPTH`).+- `src/core/skills/resolver/sources.ts` — the four sources: `--dir` (real paths only, symlinks out of the root skipped, breadth-first, first id wins, plugin namespace from `.claude-plugin/plugin.json`, stat fingerprint), `--bundled` (dynamic import of `src/core/skills/bundled.ts`, never the operations table), `--from-json` (`JSON_INPUT_CAP_BYTES` 64 MB, 10,000 entries, bodies trimmed to 4 KB, a snapshot over `JSON_SOURCE_CAP_BYTES` kept trimmed; an adapter list or OpenClaw's `skills list --json` as is, name as id; with `--dir`, `mergeSkillFolders` takes bodies, paths and triggers by name) and `--claude-plugins` (`readClaudePluginSources`: enabled user-scope plugins from `installed_plugins.json` and `settings.json`, as `<plugin>:<skill>`); `applyRouting`; bounds (`MAX_SKILLS`, `MAX_DIRS_VISITED`, `MAX_DEPTH`).- `src/core/skills/resolver/frontmatter.ts` — bounded SKILL.md reader (64 KB file, 4 KB body): name, description, `when_to_use`, triggers, `disable-model-invocation`.- `src/core/skills/resolver/routing.ts` — one RESOLVER-style routing file's table and compact-list rows, skipping the generated skills block.- `src/core/skills/resolver/session.ts` — session state (`sessions/<sha256(scope, harness, id)>.json`: ids and counters only), `commitSession` under a short lease, file and id caps, 7-day GC with a per-run work bound; every commit (sync or async) then starts an async GC pass after it settles, at most once per `GC_INTERVAL_MS` (10 min) per home by the mtime of `logs/session-gc.stamp`, so new sessions keep deduping past `MAX_SESSION_FILES`.diff --git a/docs/guides/skill-resolver.md b/docs/guides/skill-resolver.mdindex 88c2a2c51b..d3525dac02 100644--- a/docs/guides/skill-resolver.md+++ b/docs/guides/skill-resolver.md@@ -38,10 +38,12 @@ One catalog per skill set. Names are 1-64 characters of `a-z`, `0-9`, `_` and| Harness | Build | Notes ||---|---|---|| Claude Code | `gbrain skills index build --catalog claude-user --dir ~/.claude/skills --harness claude-code` | Plugin skills get their `<plugin>:` prefix from `.claude-plugin/plugin.json`. |+| Claude Code plugins | `gbrain skills index build --catalog claude-plugins --claude-plugins ~/.claude --harness claude-code` | The enabled user-scope plugins (`enabledPlugins` in `settings.json`, install paths from `plugins/installed_plugins.json`), each skill as `<plugin>:<skill>`. || Codex | `gbrain skills index build --catalog codex-user --dir ~/.codex/skills --harness codex` | Suggestion lines carry the SKILL.md path; Codex opens it. || Hermes, qm | `--dir <skills dir> --harness hermes` (or `qm`) | The id is the name the loader takes. || Pi, Cursor | `--dir <skills dir> --harness pi` (or `cursor`) | Suggestion lines carry the SKILL.md path; the agent reads the file. |-| OpenClaw and other adapters | `gbrain skills index build --catalog openclaw-main --from-json - --harness openclaw` | The adapter pipes its skill list (schema below) and owns rebuilds. |+| OpenClaw | `openclaw skills list --json \| gbrain skills index build --catalog openclaw-main --from-json - --dir <skills dir> --harness openclaw` | The list builds as is: the name is the id, and a skill OpenClaw hides from the model is skipped as ineligible. Each listed skill takes its body, path and triggers from the `--dir` skill of the same name; folder-only skills stay out. |+| Other adapters | `gbrain skills index build --catalog <name> --from-json - --harness <h>` | The adapter pipes its skill list (schema below) and owns rebuilds. || gbrain's own skills | `gbrain skills index build --catalog gbrain --bundled` | Rebuilt when the gbrain version changes. |- `--dir` is repeatable; earlier directories win duplicate ids (the loser is@@ -52,7 +54,10 @@ One catalog per skill set. Names are 1-64 characters of `a-z`, `0-9`, `_` andthe skills they name.- `--scope project` marks a cloned repository's skills: their blocks show idsand names only, never their summaries, because the text came from someone else.-- Bounds: 10,000 skills per catalog, 64 KB per SKILL.md, 8 MB of JSON.+- Bounds: 10,000 skills per catalog, 64 KB per SKILL.md, 64 MB of JSON. JSON+ bodies are trimmed to the 4 KB the ranker reads, and a snapshot over 8 MB is+ kept trimmed. An invalid JSON entry fails with `skill_source_invalid`, naming+ the entry and the field.- Several catalogs merge on one turn: `--catalog user --catalog project`.Each ranks with its own variant; the session's no-repeat set and budget areshared.@@ -69,10 +74,11 @@ recorded in the receipt.`gbrain setup claude-code --skill-loading resolve` (or `codex`) turns on aper-turn hook that puts the block in front of the model on every prompt:-1. It builds the user catalog `claude-code-user` from `~/.claude/skills`- (Codex: `codex-user` from `~/.agents/skills` and `$CODEX_HOME/skills`).- With no skill found it stops with `skill_resolver_setup_incomplete` and- writes nothing else.+1. It builds the user catalog `claude-code-user` from `~/.claude/skills` and+ `claude-code-plugins` from the enabled Claude Code plugins (Codex:+ `codex-user` from `~/.agents/skills` and `$CODEX_HOME/skills`). With no+ skill found it stops with `skill_resolver_setup_incomplete` and writes+ nothing else.2. It sets `skills.resolver.enabled` and `skills.resolver.harnesses` in`~/.gbrain/config.json`. A brainless install stays brainless: the fileholds no engine, so nothing reads it as a brain.@@ -205,10 +211,11 @@ median 267 tokens (Claude Code), 268 (Hermes), 270 (qm), 334 (Codex) and 339`resolve` never rebuilds. When the source changed it still answers from theexisting index with `meta.index_stale: true` and writes `stale.stamp` once (alater stale turn leaves it alone; a `--from-json -` catalog, which only its-adapter rebuilds, never gets one); the-rebuild runs from `gbrain skills index build` (which prints the exact command-in `skills index status`). For a `--dir` catalog the turn checks file sizes and-mtimes, at most 1,024 per turn and a full sweep at most once a minute;+adapter rebuilds, never gets one); the rebuild runs from+`gbrain skills index build` (which prints the exact command in+`skills index status`). For a `--dir` or `--claude-plugins` catalog the turn+checks file sizes and mtimes, at most 1,024 per turn and a full sweep at most+once a minute;`skills index status` re-reads the source and re-hashes the index. A bundledcatalog is stale after a gbrain upgrade; a `--from-json` catalog is neverrebuilt by gbrain: the adapter passes `expected_catalog_hash` and rebuildsdiff --git a/src/core/skills/resolver/index.ts b/src/core/skills/resolver/index.tsindex 84af8815b8..90c12e3d9e 100644--- a/src/core/skills/resolver/index.ts+++ b/src/core/skills/resolver/index.ts@@ -31,7 +31,7 @@ import { gcSessionsAsync, resetSession, sessionKey } from './session.ts';* harnesses, the warm handle (openCatalog), the worker-thread build* (buildSkillIndexOffThread) and gcSkillSessions.*/-export const RESOLVER_FEATURES: readonly string[] = ['min_match_strength', 'exclude_1024', 'mismatch_catalog_hash', 'named_past_budget', 'previous_user_message', 'harness_pi', 'harness_cursor', 'open_catalog', 'build_off_thread', 'gc_sessions'];+export const RESOLVER_FEATURES: readonly string[] = ['min_match_strength', 'exclude_1024', 'mismatch_catalog_hash', 'named_past_budget', 'previous_user_message', 'harness_pi', 'harness_cursor', 'openclaw_skills_list', 'from_json_with_dirs', 'claude_plugins', 'open_catalog', 'build_off_thread', 'gc_sessions'];/** One bounded pass (at most 1,000 files, async I/O) deleting session files idle for 7 days; returns how many it deleted. Commits already run one at most every 10 minutes. */export async function gcSkillSessions(opts: { home?: string; now?: number } = {}): Promise<number> {diff --git a/test/skill-resolver-catalogs.test.ts b/test/skill-resolver-catalogs.test.tsindex f5a81d0217..164684d87c 100644--- a/test/skill-resolver-catalogs.test.ts+++ b/test/skill-resolver-catalogs.test.ts@@ -19,7 +19,7 @@ import { chmodSync, existsSync, mkdirSync, mkdtempSync, readdirSync, rmSync, wriimport { tmpdir } from 'node:os';import { join } from 'node:path';import { runCli } from './helpers/cli-spawn.ts';-import { buildSkillIndex, catalogStatus, resolveSkills, ResolverError } from '../src/core/skills/resolver/index.ts';+import { buildSkillIndex, catalogStatus, resolveSkills, RESOLVER_FEATURES, ResolverError } from '../src/core/skills/resolver/index.ts';setDefaultTimeout(60_000);const CLI = join(import.meta.dir, '..', 'src', 'cli.ts');@@ -52,6 +52,7 @@ describe('OpenClaw skills list --json', () => {expect(rec.catalog.skipped.map((s) => [s.id, s.reason]).sort()).toEqual([['off-agent', 'ineligible'], ['off-allowlist', 'ineligible'], ['off-disabled', 'ineligible'], ['off-eligible', 'ineligible'], ['off-hidden', 'ineligible']]);const t = await resolveSkills({ message: 'deploy the widget service', harness: 'openclaw' }, { home, catalogs: ['oc'] });expect(t.output.suggestions[0]?.id).toBe('deploy-widget');+ expect(RESOLVER_FEATURES).toContain('openclaw_skills_list');});test('with --dir folders: bodies, paths and triggers come from the folder skill of the same name; folder-only skills stay out', async () => {@@ -69,6 +70,7 @@ describe('OpenClaw skills list --json', () => {expect(t.output.suggestions.map((s) => [s.id, s.path])).toEqual([['deploy-widget', path]]);expect((await resolveSkills({ message: 'not listed skill' }, { home, catalogs: ['oc'] })).output.suggestions.map((s) => s.id)).not.toContain('not-listed');expect((await catalogStatus('oc', { home })).fresh).toBe(true);+ expect(RESOLVER_FEATURES).toContain('from_json_with_dirs');});test('an invalid entry names itself and the field; an id-less plain list points at the OpenClaw shape', async () => {@@ -117,6 +119,7 @@ describe('Claude Code plugin skills (--claude-plugins)', () => {expect(ids).toEqual(['acme-tools:deploy', 'beta:notes']);expect(rec.catalog.skill_count).toBe(2);expect((await catalogStatus('claude-code-plugins', { home })).fresh).toBe(true);+ expect(RESOLVER_FEATURES).toContain('claude_plugins');});test('enabling a plugin makes the catalog stale, and the recorded rebuild picks it up', async () => {