Skip to content

armgit / Orkas

Public Imported from GitHub
0

Orkas is an open-source (MIT), local-first AI team for your desktop: a Commander turns your goal into to-dos and coordinates 16 built-in specialist agents plus Claude Code, Codex, OpenCode, OpenClaw and Hermes, with projects, scheduled automations and connectors. Free app for macOS & Windows; built-in models or your own keys.

Inline ROOT path header in skill / agent-index system-prompt blocks; expose agent_id

wyt625e9d46e2ab
diff --git a/src/core-agent/src/skills/loader.ts b/src/core-agent/src/skills/loader.ts
index 27ab1eff..7d809371 100644
--- a/src/core-agent/src/skills/loader.ts
+++ b/src/core-agent/src/skills/loader.ts
@@ -78,6 +78,15 @@ export class SkillLoader {
* `lang` selects which description (zh / en) is rendered; falls back per
* `pickDescription`. Defaults to `'en'` for safety in non-UI callers.
*/
+ // Default convenience renderer for hosts without their own block builder.
+ // **Orkas does NOT use this in production** — it ships its own renderer
+ // at `src/main/model/core-agent/skill-registry.ts::renderSkillLines` that
+ // (a) decides Source label by the resolved root path (basename collides
+ // when both roots end in `/skills`) and (b) inlines `<ROOT>/<id>/SKILL.md`
+ // patterns + resolved ROOT values right in the block so the LLM doesn't
+ // need to consult a separate path-constants section. Other hosts may use
+ // this default helper, in which case Source is taken from the dirs[]
+ // basename.
renderSystemPromptBlock(lang: 'zh' | 'en' = 'en'): string {
const skills = this.list();
if (!skills.length) return "";
diff --git a/src/core-agent/test/skills.test.ts b/src/core-agent/test/skills.test.ts
index 9aec9fe3..a79d73bf 100644
--- a/src/core-agent/test/skills.test.ts
+++ b/src/core-agent/test/skills.test.ts
@@ -152,7 +152,10 @@ describe("SkillLoader", () => {
const block = loader.renderSystemPromptBlock();
expect(block).toContain("## Available skills");
// Each entry carries a `Source` tag (dir basename) so the LLM can pick
- // the right path prefix without probing both roots.
+ // the right path prefix without probing both roots. (Note: Orkas's
+ // production renderer in skill-registry.ts uses richer formatting with
+ // inline ROOT path headers; this default helper stays minimal and is
+ // only consumed by other hosts / by these tests.)
expect(block).toContain("**alpha** (Source: custom) — alpha desc");
expect(block).toContain("**beta** (Source: builtin) — beta desc");
// id must never be shown twice — the name==id invariant holds.
diff --git a/src/main/features/group_chat/bus.ts b/src/main/features/group_chat/bus.ts
index 91a7eae2..53fbbbb6 100644
--- a/src/main/features/group_chat/bus.ts
+++ b/src/main/features/group_chat/bus.ts
@@ -1289,12 +1289,15 @@ async function buildCommanderSystemPrompt(uid: string, cid: string): Promise<str
// Stable sections first (cache-friendly), runtime injection last.
// chat_shared_rules.md is appended BEFORE the runtime block in
// chat_commander.md so it stays in the cached prefix.
+ // Note: skill / agent ROOT path constants are NOT passed in here anymore —
+ // they live inline in the rendered `agents_index` block (built by
+ // `buildAgentsIndexBlock`) and the `## Available skills` block (built by
+ // `skill-registry.renderSkillLines`), so the LLM sees ROOT values right
+ // next to the entries that consume them. Reintroducing $*_dir vars would
+ // recreate the cross-section path-constants design that mis-fires under
+ // training-prior layouts.
const main = prompts.load('chat_commander', {
contexts_dir: path_.resolve(paths_.userContextsDir(uid)),
- builtin_agents_dir: path_.resolve(paths_.BUILTIN_AGENTS_DIR),
- custom_agents_dir: path_.resolve(paths_.userAgentsDir(uid)),
- builtin_skills_dir: path_.resolve(paths_.BUILTIN_SKILLS_DIR),
- custom_skills_dir: path_.resolve(paths_.userSkillsDir(uid)),
agents_index: allAgentsList,
plan_state: formatPlanForPrompt(plan),
os: process.platform === 'darwin' ? 'macOS' : process.platform === 'win32' ? 'Windows' : process.platform,
@@ -1325,29 +1328,59 @@ function appendLanguageDirective(prompt: string): string {
return `${prompt}\n\n---\n\n${buildLanguageDirective()}`;
}
-async function buildAgentsIndexBlock(_uid: string): Promise<string> {
- // listAgents() reads from the active uid context (set by activateUser at boot
- // / on user switch); no uid arg needed.
+// Render the agents-index block injected into commander's system prompt.
+//
+// Format:
+// `\`read_file(<ROOT>/<id>/agent.json)\` — ROOT by Source:\n` +
+// `- custom: <abs path>\n` +
+// `- builtin: <abs path>\n` +
+// `Use these ROOT values verbatim. \`id:\` is tool-call input only — prose mentions agents as @<name>.\n\n` +
+// per-entry lines `- @<name> (Source: custom|builtin, id: <agent_id>) — desc` + optional `\n inputs_schema: <slim json>`
+//
+// Why expose id and ROOT inline (changed 2026-05): the prior layout hid
+// agent_id (to discourage hex-id leak in user prose) and put paths in a
+// separate `## Resource locations` section. That forced commander to run
+// `search_files` for the matching agent.json, extract id from the dir
+// segment, then `read_file` — two LLM round-trips. The hidden-id design
+// also relied on the LLM to navigate path constants between sections.
+// Now: id is shown next to its entry (one round-trip read), and the ROOT
+// values live right next to the entries so there is nothing to construct.
+// Hex-id leak prevention shifts to (a) the explicit "prose uses @<name>"
+// hint here, and (b) the existing `@<id>` → `@<name>` rewrite in router.
+// Exported (with `_…ForTest` suffix mirroring `_cidStateForTest` below) so
+// the agents-index format can be pinned by fixture without spinning up the
+// full bus pipeline. Treat as test-only — production callers stay inside
+// `buildCommanderSystemPrompt`.
+export async function _buildAgentsIndexBlockForTest(uid: string): Promise<string> {
+ return buildAgentsIndexBlock(uid);
+}
+
+async function buildAgentsIndexBlock(uid: string): Promise<string> {
const { getCurrentLang } = await import('../../i18n');
const { pickDescription } = await import('#core-agent');
const lang = getCurrentLang();
+ const customRoot = path.resolve(userAgentsDir(uid));
+ const builtinRoot = path.resolve(BUILTIN_AGENTS_DIR);
+ const header = [
+ '`read_file(<ROOT>/<id>/agent.json)` — ROOT by Source:',
+ `- custom: ${customRoot}`,
+ `- builtin: ${builtinRoot}`,
+ 'Use these ROOT values verbatim. `id:` is tool-call input only — prose mentions agents as @<name>.',
+ '',
+ ].join('\n');
try {
const list = (await agentsFeat.listAgents()).filter((a: any) => a.enabled !== false);
- if (!list.length) return '(no agents)';
- return list.map((a: any) => {
+ if (!list.length) return `${header}(no agents)`;
+ const entries = list.map((a: any) => {
const name = a.name || a.agent_id;
const description = pickDescription(a, lang);
const desc = description ? ` — ${description}` : '';
- // Lead with `@<name>` so the LLM picks up the calling convention
- // visually; id is hidden — exposing hex strings in prompts trains
- // the LLM to leak them in user-visible text too.
- const head = `- ${buildMention(name)} (Source: ${a.source})${desc}`;
+ const head = `- ${buildMention(name)} (Source: ${a.source}, id: ${a.agent_id})${desc}`;
// Inline a slimmed inputs_schema (id / type / required / default /
// label / options / min / max / accept) so commander knows what
// params each agent expects when phrasing its `@<name>` dispatch
// text. Stripped of UI-only narrative fields (description /
- // placeholder) — those bloat the prompt without helping the LLM
- // extract values.
+ // placeholder) — those bloat the prompt without helping extraction.
const inputs = Array.isArray(a.inputs) ? a.inputs : null;
if (inputs && inputs.length) {
const slim = inputs.map((f: any) => {
@@ -1358,17 +1391,16 @@ async function buildAgentsIndexBlock(_uid: string): Promise<string> {
}
return head;
}).join('\n');
- } catch { return '(no agents)'; }
+ return `${header}${entries}`;
+ } catch { return `${header}(no agents)`; }
}
async function buildAgentInGroupSystemPrompt(
- uid: string,
+ _uid: string,
agent: { name?: string; description?: string; workflow?: string; agent_id: string; inputs?: unknown },
workingDir: string,
): Promise<string> {
const { prompts } = await import('../../prompts/loader');
- const path_ = await import('node:path');
- const paths_ = await import('../../paths');
// Render the agent's declared inputs schema so the LLM knows when to
// emit a fenced agent-input-form block. UI-only narrative fields
// (description, placeholder) are stripped — the model needs id / type
@@ -1381,14 +1413,15 @@ async function buildAgentInGroupSystemPrompt(
return rest;
});
const inputsSchemaJson = slimmed.length ? JSON.stringify(slimmed) : '';
+ // Skill ROOT path constants are NOT passed in here either — the
+ // skill-registry render block embeds them inline, see commander
+ // counterpart above.
const main = prompts.load('chat_agent_in_group', {
name: agent.name || '',
agent_id: agent.agent_id,
description: agent.description || '(not provided)',
workflow: (agent.workflow || '').trim() || '(not provided)',
inputs_schema: inputsSchemaJson || '(none)',
- builtin_skills_dir: path_.resolve(paths_.BUILTIN_SKILLS_DIR),
- custom_skills_dir: path_.resolve(paths_.userSkillsDir(uid)),
working_dir: workingDir,
});
const shared = prompts.load('chat_shared_rules', {});
diff --git a/src/main/model/core-agent/skill-registry.ts b/src/main/model/core-agent/skill-registry.ts
index b606933a..09f84426 100644
--- a/src/main/model/core-agent/skill-registry.ts
+++ b/src/main/model/core-agent/skill-registry.ts
@@ -42,11 +42,40 @@ function skillSourceLabel(source: string): 'builtin' | 'custom' {
return path.resolve(source) === BUILTIN_ROOT_RESOLVED ? 'builtin' : 'custom';
}
-async function renderSkillLines(specs: SkillSpec[]): Promise<string> {
+// Render the system-prompt block listing every skill the LLM can use.
+//
+// Format:
+// `## Available skills (skills)\n\n` +
+// `\`read_file(<ROOT>/<id>/SKILL.md)\` — ROOT by Source:\n` +
+// `- custom: <abs path>\n` +
+// `- builtin: <abs path>\n` +
+// `Use these ROOT values verbatim; do NOT use training-prior layouts (e.g. \`/data/custom/skills/\`).\n\n` +
+// per-entry lines `- **<id>** (Source: custom|builtin) — desc`
+//
+// Why the inline ROOT header (added 2026-05): putting only `(Source: ...)` on
+// each entry and listing the path constants in a separate `## Resource locations`
+// section let the LLM ignore the resolved absolute paths and pattern-match its
+// training prior to fabricate `/data/custom/skills/<id>/SKILL.md` (a Claude Code
+// layout that doesn't exist here), which then trips E_PATH_OUT_OF_SCOPE on
+// `read_file`. The roots-in-block form puts the actual values right next to the
+// entry list so the LLM can't miss them.
+async function renderSkillLines(
+ specs: SkillSpec[],
+ customRoot: string,
+ builtinRoot: string,
+): Promise<string> {
if (!specs.length) return '';
const lang = getCurrentLang();
const pick = await getPickDescription();
- const lines = ['## Available skills (skills)', ''];
+ const lines: string[] = [
+ '## Available skills (skills)',
+ '',
+ '`read_file(<ROOT>/<id>/SKILL.md)` — ROOT by Source:',
+ `- custom: ${customRoot}`,
+ `- builtin: ${builtinRoot}`,
+ 'Use these ROOT values verbatim; do NOT use training-prior layouts (e.g. `/data/custom/skills/`).',
+ '',
+ ];
for (const s of specs) {
const source = skillSourceLabel(s.source);
const description = pick(s, lang);
@@ -114,14 +143,20 @@ export async function getSystemPromptBlock(opts: SystemPromptBlockOptions = {}):
const disabled = opts.disabledIds ? new Set(opts.disabledIds) : null;
const filterDisabled = (list: typeof specs) =>
disabled && disabled.size ? list.filter((s) => !disabled.has(s.id)) : list;
+ // Resolve roots once per call — `getActiveUserId` may have rotated since
+ // `getLoader` (cached) was first instantiated; users.ts switches uid via
+ // `activateUser` which calls `invalidateSkills` to drop the loader cache,
+ // but the ROOT values must reflect the CURRENT uid regardless of cache age.
+ const customRoot = path.resolve(userSkillsDir(getActiveUserId()));
+ const builtinRoot = path.resolve(BUILTIN_SKILLS_DIR);
- if (opts.allowlist === undefined) return renderSkillLines(filterDisabled(specs));
+ if (opts.allowlist === undefined) return renderSkillLines(filterDisabled(specs), customRoot, builtinRoot);
const rawAllow = opts.allowlist.filter((id) => typeof id === 'string' && id.length > 0);
if (rawAllow.length === 0) return '';
const allow = new Set(rawAllow);
- return renderSkillLines(filterDisabled(specs.filter((s) => allow.has(s.id))));
+ return renderSkillLines(filterDisabled(specs.filter((s) => allow.has(s.id))), customRoot, builtinRoot);
}
/** Drop the internal mtime cache so the next `list()` rescans. */
diff --git a/src/main/prompts/chat_agent_in_group.md b/src/main/prompts/chat_agent_in_group.md
index 40737218..278745b5 100644
--- a/src/main/prompts/chat_agent_in_group.md
+++ b/src/main/prompts/chat_agent_in_group.md
@@ -119,7 +119,7 @@ The "Runtime injection" section at the end lists your `inputs_schema`. If it is
## Resource locations (path constants)
-- Skill definitions: `Source: builtin` → `$builtin_skills_dir/<id>/SKILL.md`; `Source: custom` → `$custom_skills_dir/<id>/SKILL.md`.
+- Skill paths: see the header of the `## Available skills (skills)` block below for the `read_file(<ROOT>/<id>/SKILL.md)` pattern and resolved ROOT values per Source.
- Tool default cwd = `$working_dir`; all relative paths land here. To go out of this scope, the dispatcher must **explicitly include** a path in the inbound message.
---
diff --git a/src/main/prompts/chat_commander.md b/src/main/prompts/chat_commander.md
index 99cfe49f..aa4df548 100644
--- a/src/main/prompts/chat_commander.md
+++ b/src/main/prompts/chat_commander.md
@@ -290,13 +290,12 @@ skill_id_b
When `<agent_id>` is the right move (the user is asking to change an agent that already exists), follow this loop **before** emitting the container — skipping any step risks silent data loss:
-1. **Find the agent's id**. The `agents_index` block above does NOT carry ids — **don't fabricate**. Use `search_files` for an `agent.json` whose `name` matches under `$custom_agents_dir/`, or an equivalent `bash` grep; the directory segment after `$custom_agents_dir/` IS the agent_id.
-2. **Read the current spec**: `read_file($custom_agents_dir/<agent_id>/agent.json)`. Never rewrite from memory — `agents_index` only carries a slim view of `inputs_schema`, with no workflow / description / skill_list. Skipping this step ⇒ silently wiping fields you didn't intend to touch.
-3. **Confirm the agent is editable here**:
- - `source !== 'custom'` (built-in agent, lives under `$builtin_agents_dir/`) → reply with one prose line in the user's UI language explaining that this is a built-in agent and can't be edited through the main conversation; the user can fork a custom copy from the detail panel. Then stop. **Do not emit `<agent>`**.
+1. **Read the current spec**: take the `id` field from the `agents_index` entry and `read_file` per the Read pattern shown in that block's header. Never rewrite from memory — `agents_index` only carries a slim view of `inputs_schema`, with no workflow / description / skill_list; skipping this step ⇒ silently wiping fields you didn't intend to touch.
+2. **Confirm the agent is editable here**:
+ - `Source: builtin` → reply with one prose line in the user's UI language explaining that this is a built-in agent and can't be edited through the main conversation; the user can fork a custom copy from the detail panel. Then stop. **Do not emit `<agent>`**.
- `runtime.kind === 'cli'` (external CLI agent: claude code / codex / openclaw / opencode / hermes — they bring their own prompt; the runtime / model / args are owned by the create-modal + edit-form, not the LLM) → reply with one prose line in the user's UI language explaining that this is an external CLI-backed agent and that its working directory / model / launch args / name / description are only editable from the detail panel. Then stop. **Do not emit `<agent>`**.
-4. **Emit `<agent>` with `<agent_id>` first**, and only the sub-tags you're changing. Absent sub-tags preserve the current value. Empty body (e.g. `<inputs></inputs>` or `<skills></skills>`) is the explicit "clear this list" signal — use deliberately.
-5. **`<inputs>` is full-list replace, NOT per-id merge**. If the user is "adding a new input field", you must emit the entire updated list (every existing input + the new one). Emitting only the new one wipes the rest. Same rule for `<skills>`.
+3. **Emit `<agent>` with `<agent_id>` first**, and only the sub-tags you're changing. Absent sub-tags preserve the current value. Empty body (e.g. `<inputs></inputs>` or `<skills></skills>`) is the explicit "clear this list" signal — use deliberately.
+4. **`<inputs>` is full-list replace, NOT per-id merge**. If the user is "adding a new input field", you must emit the entire updated list (every existing input + the new one). Emitting only the new one wipes the rest. Same rule for `<skills>`.
Example shape (only the workflow changes; the prose line above the container is in the user's UI language):
@@ -349,8 +348,7 @@ When a user message has an `<attachments>` prefix, each `<file name=... path=...
### Resource path constants
-- Agent definitions: builtin → `$builtin_agents_dir/<id>/`; custom → `$custom_agents_dir/<id>/`. **Don't** `cat` an agent's JSON and impersonate it — dispatch by id to the real agent.
-- Skill definitions: builtin → `$builtin_skills_dir/<id>/SKILL.md`; custom → `$custom_skills_dir/<id>/SKILL.md`. Locate by `Source`; don't try both roots.
+- Agent / skill ROOT paths: see the headers of the `## Available skills` and `### Agents list` blocks below for `read_file(<ROOT>/<id>/...)` patterns and resolved ROOT values per Source. **Don't `cat` an agent's JSON and impersonate it** — dispatch by id to the real agent.
---
@@ -372,6 +370,6 @@ $plan_state
### Agents list
-> The list contains only name / source / description; an entry with `inputs_schema: [...]` indicates that the agent has structured input parameters — when dispatching via `dispatch_to`, write the field values into `message` in natural language.
+> Each entry shows `name / source / id / description` plus optional `inputs_schema: [...]` (structured input params — when dispatching via `dispatch_to`, write the field values into `message` in natural language). The block header lists the `read_file(<ROOT>/<id>/agent.json)` pattern + resolved ROOT values per Source.
$agents_index
diff --git a/test/main/features/group_chat/agents-index.test.ts b/test/main/features/group_chat/agents-index.test.ts
new file mode 100644
index 00000000..00c4e9b1
--- /dev/null
+++ b/test/main/features/group_chat/agents-index.test.ts
@@ -0,0 +1,108 @@
+// Pin the `agents_index` block format used by `buildCommanderSystemPrompt`.
+//
+// Format (one entry per agent, ordered by insertion):
+// `\`read_file(<ROOT>/<id>/agent.json)\` — ROOT by Source:`
+// `- custom: <abs path>`
+// `- builtin: <abs path>`
+// `Use these ROOT values verbatim. \`id:\` is tool-call input only — prose mentions agents as @<name>.`
+// ``
+// `- @<name> (Source: custom|builtin, id: <agent_id>) — desc`
+// ` inputs_schema: <slim json>` ← optional, only when inputs[] non-empty
+//
+// Why these fixtures matter (added 2026-05): the prior format hid agent_id
+// (to discourage hex-id leak in user prose) and put paths in a separate
+// `## Resource locations` section, forcing commander to do a 2-step
+// search_files + read_file dance to load any existing agent's spec. The
+// new format inlines `id:` per entry + ROOT values right next to the
+// entries, so commander goes 1 round-trip. Shipping this regression once
+// would mean either (a) ROOT values gone → LLM falls back on training-prior
+// `/data/custom/agents/<id>/` paths and trips E_PATH_OUT_OF_SCOPE, or
+// (b) `id:` gone → commander can't find agent.json without the dance.
+// The "@<name> in prose" hint relies on the existing `@<id>→@<name>`
+// rewrite chain in router.ts; both layers together keep hex IDs out of
+// user-visible bubbles.
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+let tmpDir: string;
+let prevWs: string | undefined;
+const TEST_UID = 'u-agents-idx';
+
+function customAgentsDir(): string {
+ return path.join(tmpDir, TEST_UID, 'cloud', 'agents');
+}
+function builtinAgentsDir(): string {
+ return path.join(tmpDir, 'builtin', 'agents');
+}
+
+function writeAgent(root: string, agent_id: string, body: Record<string, unknown>) {
+ const dir = path.join(root, agent_id);
+ fs.mkdirSync(dir, { recursive: true });
+ fs.writeFileSync(
+ path.join(dir, 'agent.json'),
+ JSON.stringify({ agent_id, created_at: '2026-01-01', updated_at: '2026-01-01', ...body }),
+ );
+}
+
+beforeEach(async () => {
+ tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'orkas-agentsidx-'));
+ prevWs = process.env.ORKAS_WORKSPACE_ROOT;
+ process.env.ORKAS_WORKSPACE_ROOT = tmpDir;
+ // Force fresh module loads so `BUILTIN_AGENTS_DIR` (module-level const
+ // resolved at paths.ts import time) gets the test ORKAS_WORKSPACE_ROOT.
+ vi.resetModules();
+ const users = await import('../../../../src/main/features/users');
+ users.activateUser(TEST_UID);
+});
+
+afterEach(() => {
+ process.env.ORKAS_WORKSPACE_ROOT = prevWs;
+ fs.rmSync(tmpDir, { recursive: true, force: true });
+});
+
+async function buildBlock(uid: string): Promise<string> {
+ const bus = await import('../../../../src/main/features/group_chat/bus');
+ return bus._buildAgentsIndexBlockForTest(uid);
+}
+
+describe('agents_index block — header + per-entry shape', () => {
+ it('header carries Read pattern, resolved ROOT values, and anti-prior warning', async () => {
+ writeAgent(customAgentsDir(), 'a1b2c3d4', { name: 'Alpha', description_zh: 'A', description_en: 'A' });
+ writeAgent(builtinAgentsDir(), 'e5f6a7b8', { name: 'Beta', description_zh: 'B', description_en: 'B' });
+ const text = await buildBlock(TEST_UID);
+ expect(text).toContain('`read_file(<ROOT>/<id>/agent.json)`');
+ expect(text).toContain(`- custom: ${path.resolve(customAgentsDir())}`);
+ expect(text).toContain(`- builtin: ${path.resolve(builtinAgentsDir())}`);
+ expect(text).toContain('Use these ROOT values verbatim');
+ expect(text).toContain('@<name>');
+ });
+
+ it('entry includes id: <agent_id> next to Source — commander needs it for read_file + <agent_id> sub-tag', async () => {
+ writeAgent(customAgentsDir(), 'a1b2c3d4e5f6', { name: 'Reviewer', description_zh: 'R', description_en: 'R' });
+ const text = await buildBlock(TEST_UID);
+ expect(text).toContain('@Reviewer (Source: custom, id: a1b2c3d4e5f6)');
+ });
+
+ it('inputs_schema is inlined as slim json on a continuation line when non-empty', async () => {
+ writeAgent(customAgentsDir(), 'agent-with-inputs', {
+ name: 'WithInputs',
+ description_zh: 'I',
+ description_en: 'I',
+ inputs: [{ id: 'topic', type: 'text', required: true, default: '', label: 'Topic', description: 'should be stripped' }],
+ });
+ const text = await buildBlock(TEST_UID);
+ expect(text).toContain('inputs_schema:');
+ expect(text).toContain('"topic"');
+ // narrative `description` field stripped from slim view
+ expect(text).not.toContain('"should be stripped"');
+ });
+
+ it('returns header + (no agents) when no agents are present', async () => {
+ const text = await buildBlock(TEST_UID);
+ expect(text).toContain('`read_file(<ROOT>/<id>/agent.json)`');
+ expect(text).toContain('(no agents)');
+ });
+});
diff --git a/test/main/model/skill-registry.test.ts b/test/main/model/skill-registry.test.ts
index 5d270882..1956135b 100644
--- a/test/main/model/skill-registry.test.ts
+++ b/test/main/model/skill-registry.test.ts
@@ -107,4 +107,29 @@ describe('skill-registry › getSystemPromptBlock(allowlist)', () => {
expect(text).toContain('Source: custom');
expect(text).not.toContain('Source: skills');
});
+
+ // The block embeds a Read-pattern header with resolved ROOT values for
+ // both sources + an anti-prior warning. Without these, the LLM falls back
+ // on training-prior layouts (e.g. `/data/custom/skills/<id>/`) and trips
+ // E_PATH_OUT_OF_SCOPE on `read_file`. See bus.ts substitution map cleanup
+ // — `$builtin_skills_dir / $custom_skills_dir` no longer flow through the
+ // prompt template, so this header IS the only place the LLM learns the
+ // real root paths.
+ it('block header carries Read pattern + resolved ROOT values + anti-prior warning', async () => {
+ writeSkill(builtinDir(), 'shipped', 'Shipped', 'desc-b');
+ writeSkill(customDir(), 'mine', 'Mine', 'desc-c');
+ const { getSystemPromptBlock } = await loadRegistry();
+ const text = await getSystemPromptBlock();
+ expect(text).toContain('`read_file(<ROOT>/<id>/SKILL.md)`');
+ expect(text).toContain(`- custom: ${path.resolve(customDir())}`);
+ expect(text).toContain(`- builtin: ${path.resolve(builtinDir())}`);
+ expect(text).toContain('Use these ROOT values verbatim');
+ expect(text).toContain('training-prior');
+ });
+
+ it('block omits ROOT header when no skills are present (renderSkillLines short-circuits empty)', async () => {
+ const { getSystemPromptBlock } = await loadRegistry();
+ const text = await getSystemPromptBlock();
+ expect(text).toBe('');
+ });
});