feat(skills): nested sibling files + spawn_agent skills handoff

use_skill returns skill dir so workers can read brand-guidelines.md next to SKILL.md; user-global skill dirs become read-only trusted roots; spawn_agent accepts skills[] unioned with package allowlist.

Author: TheGreatAxios

src/agent/use-skill.test.ts

@@ -57,11 +57,11 @@ describe("createUseSkillTool already-in-context", () => {
       import.meta.resolve("../extensions/skills.js"),
       (real: typeof import("../extensions/skills.js")) => ({
         ...real,
-        resolveSkillBody: async (
-          ...args: Parameters<typeof real.resolveSkillBody>
+        resolveSkillWithDir: async (
+          ...args: Parameters<typeof real.resolveSkillWithDir>
         ) => {
           resolveCalls += 1;
-          return real.resolveSkillBody(...args);
+          return real.resolveSkillWithDir(...args);
         },
       }),
       async () => {
@@ -102,12 +102,12 @@ describe("createUseSkillTool already-in-context", () => {
       import.meta.resolve("../extensions/skills.js"),
       (real: typeof import("../extensions/skills.js")) => ({
         ...real,
-        resolveSkillBody: async (
-          ...args: Parameters<typeof real.resolveSkillBody>
+        resolveSkillWithDir: async (
+          ...args: Parameters<typeof real.resolveSkillWithDir>
         ) => {
           resolveCalls += 1;
           await Promise.resolve();
-          return real.resolveSkillBody(...args);
+          return real.resolveSkillWithDir(...args);
         },
       }),
       async () => {
@@ -144,3 +144,25 @@ describe("createUseSkillTool already-in-context", () => {
     expect(out).toContain('Skill "git-worktrees"');
   });
 });
+
+describe("createUseSkillTool skill directory footer", () => {
+  test("loaded body appends the skill dir plus a sibling-file hint", async () => {
+    const cwd = await fixtureWithHiddenSkill();
+    const tool = createUseSkillTool(cwd);
+    const out = await call(tool, { name: "git-worktrees" });
+    expect(out).toContain("Create worktree recipe.");
+    expect(out).toContain(
+      `Skill directory: ${join(cwd, ".agents", "skills", "git-worktrees")}.`,
+    );
+    expect(out).toContain("brand-guidelines.md");
+    expect(out).toContain("read_file");
+  });
+
+  test("unknown skill has no footer", async () => {
+    const cwd = await fixtureWithHiddenSkill();
+    const tool = createUseSkillTool(cwd);
+    const out = await call(tool, { name: "nope-missing" });
+    expect(out).toBe('No skill named "nope-missing" is available.');
+    expect(out).not.toContain("Skill directory:");
+  });
+});

src/agent/use-skill.ts

@@ -3,7 +3,7 @@ import type { AgentTool } from "@intx/agent";
 import type { ToolDefinition } from "@intx/types/runtime";
 import { type } from "arktype";
 
-import { resolveSkillBody } from "../extensions/skills.js";
+import { resolveSkillWithDir } from "../extensions/skills.js";
 import { NOOP_TELEMETRY, type Telemetry } from "../telemetry/index.js";
 import { captureSkillUsed } from "../telemetry/product-events.js";
 
@@ -72,8 +72,11 @@ export function createUseSkillTool(
       if (loaded.has(name)) return alreadyInContextMessage(name);
       loaded.add(name);
       let body: string | undefined;
+      let dir: string | undefined;
       try {
-        body = await resolveSkillBody(cwd, name, skillDirs);
+        const resolved = await resolveSkillWithDir(cwd, name, skillDirs);
+        body = resolved?.body;
+        dir = resolved?.dir;
       } catch (err) {
         loaded.delete(name);
         throw err;
@@ -86,7 +89,11 @@ export function createUseSkillTool(
       // name never leaves the process: first-party `corbits-skills` names
       // are reported by name, everything else as `custom`.
       captureSkillUsed(telemetry, name);
-      return `Skill "${name}" — follow these instructions for this task:\n\n${body}`;
+      const footer =
+        dir !== undefined
+          ? `\n\nSkill directory: ${dir}. Sibling files (e.g. brand-guidelines.md) can be read with read_file relative to that dir.`
+          : "";
+      return `Skill "${name}" — follow these instructions for this task:\n\n${body}${footer}`;
     },
   });
 }

src/extensions/skills.test.ts

@@ -3,7 +3,11 @@ import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { test, expect, describe, beforeEach, afterEach } from "bun:test";
 
-import { discoverSkills, resolveSkillBody } from "./skills.js";
+import {
+  discoverSkills,
+  resolveSkillBody,
+  resolveSkillWithDir,
+} from "./skills.js";
 import { defined } from "../../testkit/defined.js";
 import { withMockedHomedir } from "../../testkit/mock-module.js";
 
@@ -189,6 +193,25 @@ describe("skill resolution", () => {
     ).toBeUndefined();
   });
 
+  test("resolveSkillWithDir returns the body plus the winning skill directory", async () => {
+    const resolved = await resolveSkillWithDir(
+      fixtureCwd,
+      "scribe",
+      pluginDirs,
+    );
+    expect(resolved).toBeDefined();
+    expect(defined(resolved, "resolved skill").body).toContain("Scribe");
+    expect(defined(resolved, "resolved skill").dir).toBe(
+      join(exampleAgentPlugin, "skills", "scribe"),
+    );
+  });
+
+  test("resolveSkillWithDir returns undefined for an unknown skill", async () => {
+    expect(
+      await resolveSkillWithDir(fixtureCwd, "does-not-exist-xyz", pluginDirs),
+    ).toBeUndefined();
+  });
+
   test("resolveSkillBody still loads disable-model-invocation skills by name", async () => {
     const plugin = await mkdtemp(join(tmpdir(), "skill-dmi-resolve-"));
     try {

src/extensions/skills.ts

@@ -1,7 +1,7 @@
 import { homedir } from "node:os";
 import { realpath } from "node:fs/promises";
 import { readdir, readFile } from "node:fs/promises";
-import { basename, isAbsolute, join, resolve } from "node:path";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import { pathIsInsideOrEqual } from "../util/path-contain.js";
 
 const SKILL_RELATIVE_DIRS = [
@@ -52,6 +52,14 @@ function skillBaseDirs(
   return [...pluginBases, ...projectBases, ...userBases];
 }
 
+// User-global skill base dirs (`~/.corbits/skills`, …). Project-local skill
+// dirs resolve under the session cwd (already inside the workspace); these
+// home-based dirs live outside it, so read-only file tools need them as
+// trusted roots to open sibling files (see assembleSessionGate).
+export function userSkillBaseDirs(home: string = homedir()): string[] {
+  return SKILL_RELATIVE_DIRS.map((rel) => join(home, rel));
+}
+
 function parseSkillRef(ref: string): string {
   const idx = ref.indexOf(":");
   return idx === -1 ? ref : ref.slice(idx + 1);
@@ -119,16 +127,26 @@ async function bodyFromSkillPath(path: string): Promise<string | undefined> {
   return body.length > 0 ? body : undefined;
 }
 
+/**
+ * A resolved skill: the SKILL.md body (frontmatter stripped) plus the skill
+ * directory that won, so callers can point the model at sibling files
+ * (e.g. brand-guidelines.md) living next to SKILL.md.
+ */
+export interface ResolvedSkill {
+  body: string;
+  dir: string;
+}
+
 /**
  * Resolve a path-like skill ref against `pluginRoot`. Absolute refs and
  * escapes outside the root are rejected. Accepts a SKILL.md file path or a
  * directory that contains SKILL.md. When the candidate exists, both sides are
  * realpath'd so a symlink under the root cannot escape to outside content.
  */
-async function resolvePathLikeSkillBody(
+async function resolvePathLikeSkill(
   pluginRoot: string,
   ref: string,
-): Promise<string | undefined> {
+): Promise<ResolvedSkill | undefined> {
   if (isAbsolute(ref)) return undefined;
   const root = resolve(pluginRoot);
   const resolved = resolve(root, ref);
@@ -146,7 +164,9 @@ async function resolvePathLikeSkillBody(
       realpath(root),
     ]);
     if (!pathIsInsideOrEqual(realSkill, realRoot)) return undefined;
-    return bodyFromSkillPath(realSkill);
+    const body = await bodyFromSkillPath(realSkill);
+    if (body === undefined) return undefined;
+    return { body, dir: dirname(realSkill) };
   } catch {
     // Missing path (or unreadable root) → not a resolvable skill.
     return undefined;
@@ -160,31 +180,42 @@ async function resolvePathLikeSkillBody(
 // project-local then user-global fallbacks). Path-like refs (`./skills/style`,
 // `skills/foo`) resolve only under `options.pluginRoot` with containment
 // checks; absolute and escape paths fail.
-export async function resolveSkillBody(
+export async function resolveSkillWithDir(
   cwd: string,
   ref: string,
   pluginDirs: string[] = [],
   options?: ResolveSkillBodyOptions,
-): Promise<string | undefined> {
+): Promise<ResolvedSkill | undefined> {
   const name = parseSkillRef(ref);
   // Bare `.` / `..` are not skill names and must not fall through to directory search.
   if (name === "." || name === "..") return undefined;
   if (isPathLikeSkillRef(name)) {
     const pluginRoot = options?.pluginRoot;
     if (pluginRoot === undefined) return undefined;
-    return resolvePathLikeSkillBody(pluginRoot, name);
+    return resolvePathLikeSkill(pluginRoot, name);
   }
   for (const base of skillBaseDirs(
     cwd,
     pluginDirs,
     options?.pluginDirsOnly !== true,
   )) {
-    const body = await bodyFromSkillPath(join(base, name, "SKILL.md"));
-    if (body !== undefined) return body;
+    const dir = join(base, name);
+    const body = await bodyFromSkillPath(join(dir, "SKILL.md"));
+    if (body !== undefined) return { body, dir };
   }
   return undefined;
 }
 
+export async function resolveSkillBody(
+  cwd: string,
+  ref: string,
+  pluginDirs: string[] = [],
+  options?: ResolveSkillBodyOptions,
+): Promise<string | undefined> {
+  const resolved = await resolveSkillWithDir(cwd, ref, pluginDirs, options);
+  return resolved?.body;
+}
+
 // Discover every available skill (name + one-line description). Deduped by name:
 // the first base dir that provides a skill wins, so a higher-precedence dir
 // shadows a lower one. Descriptions feed skill_search and the slash picker; the

src/session/assemble-runtime.ts

@@ -107,6 +107,7 @@ import {
 } from "../permission/gate.js";
 import type { Approval, RequestApproval } from "../permission/types.js";
 import { createWorktreeRootsProvider } from "../permission/worktree-roots.js";
+import { userSkillBaseDirs } from "../extensions/skills.js";
 import { userPluginsRoot } from "../plugins/uninstall.js";
 import { createApprovalLog } from "../permission/approval-log.js";
 import { sessionDir } from "./index.js";
@@ -312,7 +313,11 @@ export async function assembleSessionGate(
     telemetry: args.telemetry,
     cwd: args.cwd,
     rootsProvider: createWorktreeRootsProvider(args.cwd),
-    trustedPluginRoots: () => [userPluginsRoot()],
+    // User-global skill dirs live outside the workspace, so sibling reads
+    // (read_file/grep/search_files/list_dir of files next to a loaded
+    // SKILL.md) need them as trusted roots. Trusted roots are read-only by
+    // construction — writes/deletes under them stay hard escape denies.
+    trustedPluginRoots: () => [userPluginsRoot(), ...userSkillBaseDirs()],
     providerName: args.providerName,
     model: args.model,
     requestApproval: args.requestApproval,

src/subagent/agent-fleet.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test";
-import { mkdtemp, readFile } from "node:fs/promises";
+import { mkdir, mkdtemp, readFile, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
@@ -453,6 +453,103 @@ describe("spawn_agent", () => {
     expect(captured?.systemPromptRole).toBe("You are the plugin designer.");
     expect(captured?.allowedSkillNames).toEqual(["better-ui"]);
   });
+
+  test("spawn skills[] unions with the package allowlist; omitted stays fail-closed", async () => {
+    const fixture = await mkdtemp(join(tmpdir(), "corbits-spawn-skills-"));
+    const skillDir = join(fixture, ".agents", "skills", "custom");
+    await mkdir(skillDir, { recursive: true });
+    await writeFile(
+      join(skillDir, "SKILL.md"),
+      "---\nname: custom\ndescription: Custom lane.\n---\nCustom body.\n",
+    );
+
+    const captured: RunSubAgentParams[] = [];
+    const deps = createFleetDeps(
+      async (params) => {
+        captured.push(params);
+        return { report: "done" };
+      },
+      {
+        profiles: [
+          {
+            id: "bare-worker",
+            systemPromptRole: "You are a bare worker with no package skills.",
+          },
+        ],
+      },
+    );
+    const spawn = createSpawnAgentTool(deps);
+
+    // Package has no skill fields: spawn skills alone open the allowlist,
+    // and blank entries are ignored, never an error.
+    const withSkills = await callFleetTool(spawn, {
+      description: "skilled job",
+      prompt: "do it",
+      agent: "bare-worker",
+      skills: ["custom", "  ", ""],
+    });
+    expect(withSkills.status).toBe("running");
+    expect(captured[0]?.allowedSkillNames).toEqual(["custom"]);
+
+    // The dispatched allowlist is what gates use_skill: the spawned worker
+    // loads the custom skill through it.
+    const { createUseSkillTool } = await import("../agent/use-skill.js");
+    const callUseSkill = (
+      tool: ReturnType<typeof createUseSkillTool>,
+      args: Record<string, unknown>,
+    ): Promise<string> => {
+      if (tool.kind !== "string") throw new Error("expected string tool");
+      return tool.handler(args, new AbortController().signal);
+    };
+    const skilled = createUseSkillTool(
+      fixture,
+      [],
+      undefined,
+      captured[0]?.allowedSkillNames,
+    );
+    expect(await callUseSkill(skilled, { name: "custom" })).toContain(
+      "Custom body.",
+    );
+
+    // Without the spawn handoff the same package stays fail-closed.
+    const withoutSkills = await callFleetTool(spawn, {
+      description: "bare job",
+      prompt: "do it",
+      agent: "bare-worker",
+    });
+    expect(withoutSkills.status).toBe("running");
+    expect(captured[1]?.allowedSkillNames).toEqual([]);
+    const bare = createUseSkillTool(
+      fixture,
+      [],
+      undefined,
+      captured[1]?.allowedSkillNames,
+    );
+    expect(await callUseSkill(bare, { name: "custom" })).toBe(
+      'No skill named "custom" is available.',
+    );
+  });
+
+  test("spawn skills[] unions with a closed package allowlist", async () => {
+    const captured: RunSubAgentParams[] = [];
+    const deps = createFleetDeps(async (params) => {
+      captured.push(params);
+      return { report: "done" };
+    });
+    const spawn = createSpawnAgentTool(deps);
+
+    // coder declares optionalSkills ["typescript"]: the spawn list unions,
+    // it does not replace.
+    const result = await callFleetTool(spawn, {
+      description: "coded job",
+      prompt: "implement it",
+      agent: "coder",
+      success_criteria: ["it ships"],
+      skills: ["custom"],
+    });
+    expect(result.status).toBe("running");
+    expect(captured[0]?.allowedSkillNames).toEqual(["typescript", "custom"]);
+  });
 });
 
 describe("spawn_agent + wait_agents", () => {