Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

OpenClaw: never suggest a skill the agent's model cannot use

garrytand2b010b52dea
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 86da4d739c..75164a3097 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -24,6 +24,14 @@ identifiers and attribution are available in the pre-removal Git revision
- Pinned skills for Hermes (`gbrain skills pin add <id> --catalog hermes-user`) go in a marked block in `$HERMES_HOME/SOUL.md` while the resolver is on. With no pins there is no block, and SOUL.md is never created.
- `gbrain doctor`'s `skill_resolver` check now covers Hermes, and warns when Hermes's allowlist no longer approves the hook.
+### The OpenClaw skill resolver no longer suggests skills the agent cannot use
+
+**`gbrain setup openclaw --skill-loading resolve` now leaves out of each agent's suggestions the skills OpenClaw hides from that agent's model.** Before, the catalog came from the agent's skill folders alone, so a suggestion could name a skill that is not eligible on the host, that the agent's skill filter excludes, or that OpenClaw dropped at load, and the model could not open it.
+
+- Setup reads `openclaw skills list --json --agent <id>` for each agent and adds every catalog skill it does not show the model (`modelVisible` false, or not listed) to that agent's `exclude_ids`. It names those skills, and tags the ones OpenClaw did not list with `skill_resolver_host_load_cut`.
+- When the command fails, or lists none of the catalog's skills, nothing is filtered and setup says why. With no openclaw on PATH nothing changes.
+- Run setup again after changing which skills an agent can use; the plugin reads the new list from its state file without a gateway reload.
+
## [0.60.699.0] - 2026-11-12
### The Ubicloud gate VMs run a current git
diff --git a/docs/guides/error-codes.md b/docs/guides/error-codes.md
index 8d6a62a3d7..9adf3a3bc2 100644
--- a/docs/guides/error-codes.md
+++ b/docs/guides/error-codes.md
@@ -4786,7 +4786,7 @@ More: [docs/guides/skill-resolver.md#skill_resolver_config_unreadable](../../doc
| Meaning | Why | Next step | Who acts · consent | Verify | Exit | Retryable |
|---|---|---|---|---|---|---|
-| OpenClaw lists fewer skills than the agent's skill directories hold, so some suggestions name skills OpenClaw dropped at load (skills.limits.maxCandidatesPerRoot) and skills_read cannot open them. | The request itself was wrong or no longer matches the brain; nothing was changed. | Raise skills.limits.maxCandidatesPerRoot in openclaw.json, or split the skill root. | agent | `repeat the read that failed` | 1 | no |
+| OpenClaw does not list some skills in the agent's skill directories (dropped at load by skills.limits.maxCandidatesPerRoot), so setup leaves them out of the agent's suggestions. | The request itself was wrong or no longer matches the brain; nothing was changed. | Raise skills.limits.maxCandidatesPerRoot in openclaw.json, or split the skill root, then run setup again. | agent | `repeat the read that failed` | 1 | no |
More: [docs/guides/skill-resolver.md#skill_resolver_host_load_cut](../../docs/guides/skill-resolver.md#skill_resolver_host_load_cut)
diff --git a/docs/guides/skill-resolver.md b/docs/guides/skill-resolver.md
index 08261c0fd7..328b0e062a 100644
--- a/docs/guides/skill-resolver.md
+++ b/docs/guides/skill-resolver.md
@@ -198,6 +198,16 @@ gateway's Node process instead:
loaded plugin exits 3 with `skill_resolver_plugin_not_installed` and the
commands still to run; it never reports a partial install as done.
+Setup also asks OpenClaw which skills each agent's model can use
+(`openclaw skills list --json --agent <id>`, its `modelVisible` field). A
+skill in the agent's directories that OpenClaw hides from it (not eligible on
+this host, outside the agent's skill filter, model invocation off) or does not
+list at all (cut at load, see `skill_resolver_host_load_cut`) goes into that
+agent's `exclude_ids` and is never suggested, and setup names it. If the
+command fails, or lists none of the catalog's skills (usually a different
+workspace), nothing is filtered and setup says so. Run setup again after you
+change which skills an agent can use.
+
The plugin never adds to or edits OpenClaw's own skill list. On each real user
turn (`before_prompt_build`; inter-session and other internal turns are
skipped) it puts up to 3 suggestions with at least a description match in
@@ -628,6 +638,8 @@ run. Run `gbrain setup openclaw --skill-loading resolve --agent <id>`.
### skill_resolver_host_load_cut
-OpenClaw lists fewer skills than the agent's skill directories hold (it caps
-each root with `skills.limits.maxCandidatesPerRoot`), so a suggestion can name
-a skill `skills_read` cannot open. Raise that limit or split the root.
+OpenClaw does not list some of the skills in the agent's skill directories (it
+caps each root with `skills.limits.maxCandidatesPerRoot`), so `skills_read`
+could not open them. Setup leaves those skills out of the agent's suggestions
+and names them. To get them back, raise that limit or split the root, then run
+setup again.
diff --git a/src/core/error-registry.ts b/src/core/error-registry.ts
index 5de3c80547..2717d14278 100644
--- a/src/core/error-registry.ts
+++ b/src/core/error-registry.ts
@@ -765,7 +765,7 @@ export const CODES = {
skill_resolver_worker_stuck: { class: 'retryable', summary: 'The OpenClaw skill-resolver worker missed the turn deadline three times in a row, so it was restarted with backoff.', docs: 'docs/guides/skill-resolver.md#skill_resolver_worker_stuck', suggestion: 'Check the deadline-miss rate with gbrain doctor --only skill_resolver; a loaded host misses more often.' },
skill_resolver_worker_unavailable: { class: 'retryable', summary: 'The OpenClaw skill-resolver worker is restarting after a crash or a stall, so this turn proceeded without suggestions.', docs: 'docs/guides/skill-resolver.md#skill_resolver_worker_unavailable', suggestion: 'Nothing to do if it is rare; gbrain doctor --only skill_resolver shows the rate.' },
skill_resolver_state_missing: { class: 'caller', summary: 'The OpenClaw skill-resolver state file has no entry for this agent, so the self-test had nothing to run.', docs: 'docs/guides/skill-resolver.md#skill_resolver_state_missing', suggestion: 'Run gbrain setup openclaw --skill-loading resolve --agent <id>.' },
- skill_resolver_host_load_cut: { class: 'caller', summary: 'OpenClaw lists fewer skills than the agent\'s skill directories hold, so some suggestions name skills OpenClaw dropped at load (skills.limits.maxCandidatesPerRoot) and skills_read cannot open them.', docs: 'docs/guides/skill-resolver.md#skill_resolver_host_load_cut', suggestion: 'Raise skills.limits.maxCandidatesPerRoot in openclaw.json, or split the skill root.' },
+ skill_resolver_host_load_cut: { class: 'caller', summary: 'OpenClaw does not list some skills in the agent\'s skill directories (dropped at load by skills.limits.maxCandidatesPerRoot), so setup leaves them out of the agent\'s suggestions.', docs: 'docs/guides/skill-resolver.md#skill_resolver_host_load_cut', suggestion: 'Raise skills.limits.maxCandidatesPerRoot in openclaw.json, or split the skill root, then run setup again.' },
skill_resolver_internal: { class: 'server', summary: 'The skill resolver failed unexpectedly; a scrubbed trace (no turn text) was written under skill-index/logs/.', docs: 'docs/guides/skill-resolver.md#skill_resolver_internal', suggestion: 'Run gbrain skills index status and report the trace if it repeats.', fix: { argv: ['gbrain', 'skills', 'index', 'status', '--json'], consent: [], actor: 'agent', requires_exclusive: false, why: 'Shows each catalog and its last build error; changes nothing.' } },
skill_source_invalid: { class: 'caller', exit: 2, summary: 'The --from-json catalog or --routing file is not valid (not JSON, a malformed entry, over 10,000 skills or 8 MB, or a routing file over 1 MB), so nothing was built.', docs: 'docs/guides/skill-resolver.md#skill_source_invalid', suggestion: 'Pass a JSON array of {id, name, description, triggers?, routing?, body?, path?, eligible?} objects.' },
skill_source_unreadable: { class: 'caller', summary: 'A --dir or --routing path (or, for `gbrain skills library`, gbrain\'s own source in a compiled binary) does not exist or cannot be read, so nothing was built.', docs: 'docs/guides/skill-resolver.md#skill_source_unreadable', suggestion: 'Pass an existing directory (or file) you can read; for the Node library from a compiled binary, download the release asset.' },
diff --git a/src/core/setup/openclaw-skill-plugin.ts b/src/core/setup/openclaw-skill-plugin.ts
index da9b2088e1..94778d97c6 100644
--- a/src/core/setup/openclaw-skill-plugin.ts
+++ b/src/core/setup/openclaw-skill-plugin.ts
@@ -16,6 +16,14 @@
* the plugin's index.js;
* - the plugin itself under <OpenClaw state dir>/gbrain/gbrain-skill-resolver.
*
+ * Each agent's catalog is checked against what OpenClaw shows that agent's
+ * model (`openclaw skills list --json --agent <id>`, `modelVisible`): a
+ * skill OpenClaw hides from it (ineligible on this host, left out by the
+ * agent's skill filter, model invocation disabled, or cut at load) is added
+ * to the agent's exclude_ids, so it is never suggested. With no openclaw on
+ * PATH, or a list that names none of the catalog's skills, nothing is
+ * filtered and the result says so.
+ *
* OpenClaw's CLI (install --link, enable, the conversation-access grant) runs
* only when the plugin files changed or OpenClaw's config does not show the
* plugin installed, enabled and allowed, so a mode flip, a pin change or a
@@ -36,7 +44,7 @@ import { logsDir, skillIndexRoot } from '../skills/resolver/paths.ts';
import { readDirSources } from '../skills/resolver/sources.ts';
import { openclawConfigPath, openclawStateDir, parseJson5ish, resolveOpenclawWorkspace } from './brain-first.ts';
import { openclawSkillLoaderJs, openclawSkillWorkerJs } from './openclaw-skill-plugin-code.ts';
-import { pinnedBlockFor } from './skill-pins.ts';
+import { catalogSkillIds, pinnedBlockFor } from './skill-pins.ts';
import { readResolverConfig } from './skill-resolver-config.ts';
import { laneTurnSettings } from '../skills/resolver/config.ts';
@@ -193,16 +201,23 @@ function selfTest(node: string, dir: string, agentId: string, message: string, r
return { ok: false, detail: `the plugin's self-test under ${node} failed (${doc.code ?? lastLine(r.output)})` };
}
-function hostCount(run: Run, bin: string, agentId: string): number | null {
+/** What `openclaw skills list --json --agent <id>` lists for one agent, and which of those its model can use (modelVisible; else eligible and not hidden); null when the call or its JSON fails. */
+function hostSkills(run: Run, bin: string, agentId: string): { listed: Set<string>; visible: Set<string> } | null {
const r = run([bin, 'skills', 'list', '--json', '--agent', agentId]);
if (!r.ok) return null;
try {
- const j = JSON.parse(r.output) as unknown;
- const list = Array.isArray(j) ? j : Array.isArray((j as { skills?: unknown })?.skills) ? (j as { skills: unknown[] }).skills : null;
- return list ? list.length : null;
+ const j = JSON.parse(r.output.slice(r.output.indexOf('{'))) as unknown;
+ const list = Array.isArray((j as { skills?: unknown })?.skills) ? (j as { skills: Array<Record<string, unknown>> }).skills : null;
+ if (!list) return null;
+ const named = list.filter((e) => e && typeof e.name === 'string');
+ const shows = (e: Record<string, unknown>) => (typeof e.modelVisible === 'boolean' ? e.modelVisible
+ : e.eligible === true && e.disabled !== true && e.blockedByAgentFilter !== true && e.blockedByAllowlist !== true);
+ return { listed: new Set(named.map((e) => e.name as string)), visible: new Set(named.filter(shows).map((e) => e.name as string)) };
} catch { return null; }
}
+const someNames = (ids: string[]) => `${ids.slice(0, 10).join(', ')}${ids.length > 10 ? ` and ${ids.length - 10} more` : ''}`;
+
export interface OpenclawSkillSyncOptions {
mode: 'live' | 'shadow' | null;
agents: string[] | 'all' | null;
@@ -270,14 +285,24 @@ export async function syncOpenclawSkillPlugin(opts: OpenclawSkillSyncOptions): P
}
if (skills < 1) { out.notes.push(`agent ${id}: no model-invocable skill in ${dirs.join(', ')}, so it was skipped`); continue; }
out.steps.push({ step: 'catalog', action: fresh ? 'keep' : 'write', detail: `${catalog}: ${skills} skills from ${dirs.join(', ')}` });
+ const host = bin ? hostSkills(run, bin, id) : null;
+ const catalogIds = dryRun && !fresh ? readDirSources(dirs).skills.map((s) => s.id) : [...(catalogSkillIds(home, catalog) ?? [])];
+ let hidden: string[] = [];
+ if (bin && !host) out.notes.push(`agent ${id}: \`openclaw skills list --json --agent ${id}\` failed, so skills OpenClaw hides from this agent were not filtered out of ${catalog}`);
+ else if (host && !catalogIds.some((n) => host.listed.has(n))) out.notes.push(`agent ${id}: OpenClaw lists none of ${catalog}'s skills for this agent, so the catalog was not filtered (check that the agent's workspace is ${dirs[0]})`);
+ else if (host) hidden = catalogIds.filter((n) => !host.visible.has(n));
+ const cut = host ? hidden.filter((n) => !host.listed.has(n)) : [];
+ const shut = hidden.filter((n) => !cut.includes(n));
+ if (shut.length) out.notes.push(`agent ${id}: ${shut.length} skill(s) OpenClaw hides from this agent's model (ineligible on this host, outside its skill filter, or model invocation off) are never suggested: ${someNames(shut)}`);
+ if (cut.length) out.notes.push(`agent ${id}: OpenClaw does not list ${cut.length} of ${catalog}'s skills (dropped at load by skills.limits.maxCandidatesPerRoot, or not in its skill roots), so they are never suggested: ${someNames(cut)} (skill_resolver_host_load_cut)`);
const pins = dryRun ? { block: '', ids: [], unknown: [] as string[] } : pinnedBlockFor(home, catalog, 'openclaw');
agents[id] = {
mode: opts.mode ?? before?.mode ?? 'live', catalog, skill_dirs: dirs,
- top_k: lane.top_k, min_match: lane.min_match, exclude_ids: lane.exclude_ids,
+ top_k: lane.top_k, min_match: lane.min_match, exclude_ids: [...new Set([...lane.exclude_ids, ...hidden])],
live_fraction: tune.live_fraction ?? before?.live_fraction ?? 1, pins_route: tune.pins_route ?? before?.pins_route ?? 'system',
pinned_block: pins.block, pinned_ids: pins.ids, owner_sender_ids: tune.owner_sender_ids ?? before?.owner_sender_ids ?? [],
};
- out.agents.push({ id, mode: agents[id]!.mode, catalog, skills, pins: pins.ids.length, unknown_pins: pins.unknown });
+ out.agents.push({ id, mode: agents[id]!.mode, catalog, skills: skills - hidden.length, pins: pins.ids.length, unknown_pins: pins.unknown });
if (pins.unknown.length) out.notes.push(`agent ${id}: pinned skill(s) not in ${catalog}, left out of the block: ${pins.unknown.join(', ')} (skill_resolver_pin_unknown)`);
}
if (out.agents.length === 0) return fail({ code: 'skill_resolver_setup_incomplete', message: `The skill resolver was not turned on for any agent: ${out.notes.join('; ')}. Nothing was written.` });
@@ -332,12 +357,6 @@ export async function syncOpenclawSkillPlugin(opts: OpenclawSkillSyncOptions): P
if (!loaded) return fail({ code: 'skill_resolver_plugin_not_installed', message: `\`openclaw plugins inspect ${OPENCLAW_SKILL_PLUGIN_ID} --runtime --json\` does not show the plugin loaded with before_prompt_build (${lastLine(inspect.output)}).`, commands: [shown([bin, 'plugins', 'inspect', OPENCLAW_SKILL_PLUGIN_ID, '--runtime', '--json'])], argv: [bin, 'plugins', 'inspect', OPENCLAW_SKILL_PLUGIN_ID, '--runtime', '--json'], recovery: `partial: files written, ${commands.length} of ${commands.length} commands ran, but OpenClaw does not load the plugin; check the inspect output, then gbrain doctor --only skill_resolver` });
out.steps.push({ step: 'verify', action: 'run', detail: 'openclaw loads it with before_prompt_build' });
}
- if (bin) {
- for (const a of out.agents) {
- const n = hostCount(run, bin, a.id);
- if (n !== null && n < a.skills) out.notes.push(`agent ${a.id}: OpenClaw lists ${n} skills but ${a.catalog} holds ${a.skills}; OpenClaw dropped some at load (skills.limits.maxCandidatesPerRoot), and skills_read cannot open those (skill_resolver_host_load_cut)`);
- }
- }
const node = deps.nodeBin !== undefined ? deps.nodeBin : which('node');
if (!node) out.notes.push('no node on PATH, so the plugin self-test did not run; the gateway runs it under its own Node');
else {
diff --git a/test/openclaw-skill-plugin.test.ts b/test/openclaw-skill-plugin.test.ts
index 8a4469d7e8..ed654af29d 100644
--- a/test/openclaw-skill-plugin.test.ts
+++ b/test/openclaw-skill-plugin.test.ts
@@ -12,6 +12,9 @@
* on live turns, nothing on shadow, internal or off turns, commits a retried
* turn once, refuses a library writable by others, gives up on a stuck worker
* within the deadline and logs each miss; a brainless home stays brainless.
+ * PR 2: a skill OpenClaw hides from the agent's model, or does not list, is
+ * excluded and never suggested; a failed list or one naming none of the
+ * catalog filters nothing.
*/
import { afterAll, describe, expect, setDefaultTimeout, test } from 'bun:test';
import { chmodSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
@@ -45,7 +48,7 @@ case "$1 $2" in
"config set") node -e 'const f=require("fs"),p=process.argv[1],c=JSON.parse(f.readFileSync(p,"utf8"));const id=process.argv[2].split(".")[2];c.plugins.entries[id].hooks={allowConversationAccess:true};f.writeFileSync(p,JSON.stringify(c))' "$cfg" "$3";;
"plugins inspect") [ -n "$INSPECT_BROKEN" ] && { echo '{"status":"error"}'; exit 0; }; echo '{"status":"loaded","hooks":["before_prompt_build"]}';;
"plugins uninstall") ;;
- "skills list") echo '[]' > /dev/null; exit 1;;
+ "skills list") [ -n "$SKILLS_LIST_JSON" ] && { echo "[plugins] loaded"; cat "$SKILLS_LIST_JSON"; exit 0; }; exit 1;;
esac
`;
@@ -211,6 +214,51 @@ describe.skipIf(!NODE)('gbrain setup openclaw --skill-loading', () => {
});
});
+describe.skipIf(!NODE)('the OpenClaw eligibility filter', () => {
+ const listed = (b: Box, skills: object[]) => { const f = join(b.root, 'skills-list.json'); writeFileSync(f, JSON.stringify({ workspaceDir: join(b.state, 'workspace'), skills })); return { SKILLS_LIST_JSON: f }; };
+
+ test('a skill OpenClaw hides from the agent, or does not list, goes into exclude_ids and is never suggested', async () => {
+ const b = box();
+ const env = listed(b, [
+ { name: 'deploy-service', eligible: true, disabled: false, blockedByAgentFilter: false },
+ { name: 'email-triage', eligible: true, disabled: false, blockedByAgentFilter: true, modelVisible: false },
+ { name: 'weather', eligible: false, modelVisible: false },
+ ]);
+ const r = await setup(b, ['--skill-loading', 'resolve'], env);
+ expect(r.exitCode).toBe(0);
+ expect([...readState(b).agents.main.exclude_ids].sort()).toEqual(['calendar-sync', 'email-triage']);
+ expect(r.resolver.agents[0]).toMatchObject({ id: 'main', skills: 1 });
+ const notes = r.resolver.notes.join('\n');
+ expect(notes).toContain('hides from this agent' + "'" + 's model');
+ expect(notes).toContain('email-triage');
+ expect(notes).toMatch(/does not list 1 of openclaw-main's skills.*calendar-sync.*skill_resolver_host_load_cut/);
+ const out = drive(b, [['turn', { text: 'deploy the service to production, triage the email inbox and sync the calendar', id: 'm1' }]]);
+ expect(out[0].appendContext).toContain('deploy-service');
+ expect(out[0].appendContext).not.toContain('email-triage');
+ expect(out[0].appendContext).not.toContain('calendar-sync');
+ });
+
+ test('a list naming none of the catalog' + "'" + 's skills filters nothing and says so', async () => {
+ const b = box();
+ const r = await setup(b, ['--skill-loading', 'resolve'], listed(b, [{ name: 'weather', eligible: true, modelVisible: true }]));
+ expect(r.exitCode).toBe(0);
+ expect(readState(b).agents.main.exclude_ids).toEqual([]);
+ expect(r.resolver.agents[0].skills).toBe(3);
+ expect(r.resolver.notes.join('\n')).toContain('lists none of openclaw-main' + "'" + 's skills for this agent, so the catalog was not filtered');
+ });
+
+ test('a failed list, or no openclaw on PATH, filters nothing', async () => {
+ const b = box();
+ const r = await setup(b, ['--skill-loading', 'resolve']);
+ expect(r.exitCode).toBe(0);
+ expect(readState(b).agents.main.exclude_ids).toEqual([]);
+ expect(r.resolver.notes.join('\n')).toContain('--agent main' + String.fromCharCode(96) + ' failed, so skills OpenClaw hides from this agent were not filtered');
+ const none = box({ openclaw: false });
+ expect((await setup(none, ['--skill-loading', 'resolve'])).exitCode).toBe(3);
+ expect(readState(none).agents.main.exclude_ids).toEqual([]);
+ });
+});
+
describe.skipIf(!NODE)('gbrain skills pin', () => {
test('validates against the catalog, updates the plugin state hot, and survives --skill-loading off', async () => {
const b = box();