Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

Skill resolver: a JSON list with when_to_use builds the same index as its SKILL.md folder

garrytanb26f8c23b382
diff --git a/docs/guides/skill-resolver.md b/docs/guides/skill-resolver.md
index d4f7b5ac67..8265d7a936 100644
--- a/docs/guides/skill-resolver.md
+++ b/docs/guides/skill-resolver.md
@@ -168,7 +168,10 @@ The JSON Schemas are checked in under `docs/schemas/`:
- `skill-resolver.v1.turn-output.json`: the `--json` result. Everything outside
`meta` is byte-identical for the same index, input and session state.
- `skill-resolver.v1.build-input.json`: the `--from-json` catalog,
- `[{id, name, description?, triggers?, routing?, body?, path?, eligible?}]`.
+ `[{id, name, description?, when_to_use?, triggers?, routing?, body?, path?,
+ eligible?, disable_model_invocation?}]`. With the same fields a SKILL.md
+ folder has (`when_to_use`, `disable-model-invocation`), a JSON build gives
+ the same `catalog_hash` and `index_hash` as the folder build.
- `skill-resolver.v1.build-receipt.json`: the build receipt, also saved as
`receipt.json` beside the index.
diff --git a/docs/schemas/skill-resolver.v1.build-input.json b/docs/schemas/skill-resolver.v1.build-input.json
index f15d9447bb..4ee7d5ef57 100644
--- a/docs/schemas/skill-resolver.v1.build-input.json
+++ b/docs/schemas/skill-resolver.v1.build-input.json
@@ -25,6 +25,10 @@
"description": {
"type": "string"
},
+ "when_to_use": {
+ "type": "string",
+ "description": "Frontmatter when_to_use; ranked with the description, as a SKILL.md folder build does."
+ },
"triggers": {
"type": "array",
"items": {
@@ -47,6 +51,10 @@
"eligible": {
"type": "boolean",
"description": "false: never indexed (recorded as skipped: ineligible)."
+ },
+ "disable_model_invocation": {
+ "type": "boolean",
+ "description": "true: never indexed (recorded as skipped: not_model_invocable), like disable-model-invocation in SKILL.md."
}
}
},
@@ -73,6 +81,10 @@
"description": {
"type": "string"
},
+ "when_to_use": {
+ "type": "string",
+ "description": "Frontmatter when_to_use; ranked with the description, as a SKILL.md folder build does."
+ },
"body": {
"type": "string"
},
@@ -105,6 +117,10 @@
},
"modelVisible": {
"type": "boolean"
+ },
+ "disable_model_invocation": {
+ "type": "boolean",
+ "description": "true: never indexed (recorded as skipped: not_model_invocable), like disable-model-invocation in SKILL.md."
}
}
}
diff --git a/src/core/skills/resolver/index.ts b/src/core/skills/resolver/index.ts
index 84c9953650..92e9ce03e3 100644
--- a/src/core/skills/resolver/index.ts
+++ b/src/core/skills/resolver/index.ts
@@ -35,7 +35,7 @@ import { gcSessionsAsync, resetSession, sessionKey } from './session.ts';
* {"context"}) and the lane's Codex project catalog (codex-project-<hash>,
* the .agents/skills dirs from the project root to cwd).
*/
-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', 'harness_hermes_lane', 'codex_project_catalog'];
+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', 'from_json_when_to_use', 'claude_plugins', 'open_catalog', 'build_off_thread', 'gc_sessions', 'harness_hermes_lane', 'codex_project_catalog'];
/** 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/src/core/skills/resolver/sources.ts b/src/core/skills/resolver/sources.ts
index 5d74f120ac..bd2e727c67 100644
--- a/src/core/skills/resolver/sources.ts
+++ b/src/core/skills/resolver/sources.ts
@@ -196,7 +196,7 @@ export async function readBundledSource(): Promise<SourceRead> {
}
function invalid(message: string): ResolverError {
- return new ResolverError('skill_source_invalid', message, { suggestion: 'Pass a JSON array of {id, name, description, triggers?, routing?, body?, path?, eligible?} objects, or OpenClaw\'s skills list --json output as is (at most 10,000 entries, 64 MB).' });
+ return new ResolverError('skill_source_invalid', message, { suggestion: 'Pass a JSON array of {id, name, description, when_to_use?, triggers?, routing?, body?, path?, eligible?, disable_model_invocation?} objects, or OpenClaw\'s skills list --json output as is (at most 10,000 entries, 64 MB).' });
}
const optStr = (v: unknown) => v === undefined || typeof v === 'string';
@@ -208,14 +208,14 @@ const OPENCLAW_HIDDEN = ['disabled', 'blockedByAllowlist', 'blockedByAgentFilter
function badField(o: Record<string, unknown>, openclaw: boolean): string | null {
if (!openclaw && (typeof o.id !== 'string' || !o.id.trim() || o.id.length > MAX_ID)) return `id (a required string of at most ${MAX_ID} characters)`;
if (typeof o.name !== 'string' || !o.name.trim() || (openclaw && o.name.length > MAX_ID)) return 'name (a required string)';
- for (const f of ['description', 'body', 'path'] as const) if (!optStr(o[f])) return `${f} (a string)`;
+ for (const f of ['description', 'when_to_use', 'body', 'path'] as const) if (!optStr(o[f])) return `${f} (a string)`;
for (const f of ['triggers', 'routing'] as const) if (!optStrList(o[f])) return `${f} (an array of strings)`;
- for (const f of ['eligible', ...(openclaw ? [...OPENCLAW_HIDDEN, 'modelVisible'] : [])]) if (!optBool(o[f])) return `${f} (a boolean)`;
+ for (const f of ['eligible', 'disable_model_invocation', ...(openclaw ? [...OPENCLAW_HIDDEN, 'modelVisible'] : [])]) if (!optBool(o[f])) return `${f} (a boolean)`;
return null;
}
/**
- * An adapter's catalog snapshot: `[{id, name, description, triggers?, routing?, body?, path?, eligible?}]`,
+ * An adapter's catalog snapshot: `[{id, name, description, when_to_use?, triggers?, routing?, body?, path?, eligible?, disable_model_invocation?}]`,
* `{skills: [...]}`, or OpenClaw's `skills list --json` document.
*/
export function readJsonSource(text: string): SourceRead {
@@ -240,13 +240,16 @@ export function readJsonSource(text: string): SourceRead {
throw invalid(`Entry ${i}${named} is not a valid skill: ${bad} is wrong or missing.${hint}`);
}
const id = (openclaw ? o.name as string : o.id as string).trim();
- if (o.eligible === false || (openclaw && (OPENCLAW_HIDDEN.some(f => o[f] === true) || o.modelVisible === false))) { skipped.push({ reason: 'ineligible', id }); return; }
+ const at = typeof o.path === 'string' && o.path ? { path: o.path } : {};
+ if (o.disable_model_invocation === true) { skipped.push({ reason: 'not_model_invocable', id, ...at }); return; }
+ if (o.eligible === false || (openclaw && (OPENCLAW_HIDDEN.some(f => o[f] === true) || o.modelVisible === false))) { skipped.push({ reason: 'ineligible', id, ...at }); return; }
if (seen.has(id)) { skipped.push({ reason: 'duplicate_id', id, kept: id }); return; }
seen.set(id, id);
- skills.push({ id, name: cut(cleanText(o.name), MAX_NAME), description: cut(cleanText(o.description ?? ''), MAX_DESCRIPTION),
+ const whenToUse = cut(cleanText(o.when_to_use ?? ''), MAX_DESCRIPTION);
+ skills.push({ id, name: cut(cleanText(o.name), MAX_NAME), description: cut(cleanText(o.description ?? ''), MAX_DESCRIPTION), ...(whenToUse ? { whenToUse } : {}),
triggers: boundTriggers(((o.triggers as string[] | undefined) ?? []).map(cleanText).filter(Boolean)),
routing: ((o.routing as string[] | undefined) ?? []).map(cleanText).filter(Boolean).slice(0, MAX_ROUTING_ROWS),
- body: typeof o.body === 'string' ? boundBody(o.body) : '', ...(typeof o.path === 'string' && o.path ? { path: o.path } : {}) });
+ body: typeof o.body === 'string' ? boundBody(o.body) : '', ...at });
});
if (bytes <= JSON_SOURCE_CAP_BYTES) return { kind: 'json', skills, skipped, snapshot: text };
for (const e of list) { const o = e as Record<string, unknown>; if (typeof o.body === 'string') o.body = boundBody(o.body); }
diff --git a/test/skill-resolver-catalogs.test.ts b/test/skill-resolver-catalogs.test.ts
index d555dc4866..e3652710a9 100644
--- a/test/skill-resolver-catalogs.test.ts
+++ b/test/skill-resolver-catalogs.test.ts
@@ -233,3 +233,29 @@ describe('harness-owned entries in a skills root (HARN-52)', () => {
expect(await stale(b.home)).toBe(true);
});
});
+
+describe('a JSON list equal to a folder builds the same index (HARN-52)', () => {
+ test('when_to_use and disable_model_invocation: one catalog built from folders and from JSON has equal catalog_hash and index_hash', async () => {
+ const root = tmp('skres-parity-');
+ const write = (dir: string, fm: string, body: string) => { mkdirSync(join(root, dir), { recursive: true }); writeFileSync(join(root, dir, 'SKILL.md'), `---\n${fm}\n---\n${body}\n`); return join(root, dir, 'SKILL.md'); };
+ const deploy = write('deploy', 'name: deploy\ndescription: Ship a service\nwhen_to_use: when the user asks for a zebrafinch release', 'Run the tests, then deploy.');
+ const notes = write('notes', 'name: notes\ndescription: Take meeting notes', 'Write the notes.');
+ const hidden = write('hidden', 'name: hidden\ndescription: Internal helper\ndisable-model-invocation: true', 'Never offered.');
+ const homeA = tmp();
+ const a = await buildSkillIndex({ catalog: 'p', dirs: [root] }, { home: homeA });
+ const list = [
+ { id: 'deploy', name: 'deploy', description: 'Ship a service', when_to_use: 'when the user asks for a zebrafinch release', body: 'Run the tests, then deploy.\n', path: deploy },
+ { id: 'hidden', name: 'hidden', description: 'Internal helper', disable_model_invocation: true, body: 'Never offered.\n', path: hidden },
+ { id: 'notes', name: 'notes', description: 'Take meeting notes', body: 'Write the notes.\n', path: notes },
+ ];
+ const homeB = tmp();
+ const b = await buildSkillIndex({ catalog: 'p', fromJson: JSON.stringify(list), fromJsonStdin: true }, { home: homeB });
+ expect(b.catalog.skipped).toEqual(a.catalog.skipped);
+ expect(b.catalog.skipped.map((s) => s.reason)).toEqual(['not_model_invocable']);
+ expect([b.catalog.catalog_hash, b.index.index_hash]).toEqual([a.catalog.catalog_hash, a.index.index_hash]);
+ const top = (await resolveSkills({ message: 'zebrafinch release' }, { home: homeB, catalogs: ['p'] })).output.suggestions.map((s) => s.id);
+ expect(top).toEqual(['deploy']);
+ expect(await codeAndMessage(buildSkillIndex({ catalog: 'q', fromJson: JSON.stringify([{ id: 'x', name: 'x', when_to_use: 3 }]), fromJsonStdin: true }, { home: homeB }))).toEqual(['skill_source_invalid', expect.stringContaining('when_to_use (a string)')]);
+ expect(RESOLVER_FEATURES).toContain('from_json_when_to_use');
+ });
+});