Skip to content

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.md
index 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.md
index 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`, `_` and
the skills they name.
- `--scope project` marks a cloned repository's skills: their blocks show ids
and 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 are
shared.
@@ -69,10 +74,11 @@ recorded in the receipt.
`gbrain setup claude-code --skill-loading resolve` (or `codex`) turns on a
per-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 file
holds 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 the
existing index with `meta.index_stale: true` and writes `stale.stamp` once (a
later 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 bundled
catalog is stale after a gbrain upgrade; a `--from-json` catalog is never
rebuilt by gbrain: the adapter passes `expected_catalog_hash` and rebuilds
diff --git a/src/core/skills/resolver/index.ts b/src/core/skills/resolver/index.ts
index 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.ts
index 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, wri
import { 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 () => {