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.mdindex 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.jsonindex 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.tsindex 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.tsindex 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', 'blockedByAgentFilterfunction 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.tsindex 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');+ });+});