fix(skills): realpath bare-name SKILL.md + docs polish

Bare-name resolution now contains symlinks to the winning base dir.
Docs: .corbits clause, homedir paths, skill-dir footer, spawn skills[].

Author: TheGreatAxios

docs/ARCHITECTURE.md

@@ -343,7 +343,7 @@ The primary director is **dispatch** (`buildChatRole` → `createDispatchSystemP
 
 **Provider-conditional residuals.** Per-family additions layer on top of the shared block via the same `ModelFamilyPolicy` mechanism the directors use (`src/subagent/provider-family.ts`, `src/agent/model-family-policy.ts`) — additive lines, never prompt forks. **Grok** leaves get `buildGrokLeafAntiThrashNote` (gated by `shouldApplyGrokAntiThrash` / `applyGrokFinishBias`, withheld from orchestrators): a compact finish-bias reinforcement plus a one-line reminder to route file/web work through the dedicated tools rather than `run_shell`, motivated by observed tool-routing thrash on the same harness. **Kimi** intentionally has no residual yet — `detectModelFamily` already resolves the family so callers can branch on it, but the prompt seam is left unfilled pending eval characterization of Kimi's behavior, mirroring the provisional (permissive-default) policy in `model-family-policy.ts`.
 
-`buildChatSystemPrompt` (TUI chat) assembles: base → core tool list → name-only skills listing → live `<env>` block → appended extensions. `buildSubAgentSystemPrompt` assembles the worker prompt without a catalog skills listing. Closed directors that declare `attachedSkills` (none of the shipped directors do today; never the primary) get those bodies injected once at spawn from **plugin skill dirs only** (`skillDirsFromEnabledPlugins`) — `resolveSkillBody` is called with `pluginDirsOnly`, so a project-local `.agents`/`.claude`/`.codex/skills` SKILL.md cannot become system-prompt constraints. A miss is noted in the attached section; the worker proceeds (no park). Optional skills stay names-only in the identity header; workers mount `skill_search` + `use_skill` on every family (including grok/kimi leaves), scoped to the union of `attachedSkills` and `optionalSkills`. A worker that declares neither field gets an empty allowlist (fail closed) — `skill_search` / `use_skill` match nothing until the package or plugin profile lists names. `coder` ships `optionalSkills: ["typescript"]`. Built-in catalog tools (including `skill_search`) are advertised on the primary wire and callable directly; MCP integrations are discovered via `tool_search` rather than being enumerated. Skills follow the same lazy principle on the primary: each discovered skill contributes only its name. The model calls `skill_search` for descriptions when choosing, then `use_skill` to load a body. The operator can also invoke the same skill as `/<skill-name>` (see Skills below). Skills are discovered (and deduped by name, first-wins) from enabled plugin dirs, then project `.corbits`/`.agents`/`.claude`/`.codex/skills`, then the same relative dirs under `homedir()`. A user-global path that equals the project path (cwd is home) is skipped. Corbits Code ships a bundled catalog via the first-party `corbits-skills` plugin (origin `repo`); project-local skills of the same name are shadowed by an enabled plugin skill. A trusted/enabled plugin (or local `.agents/agents/`) profile whose `id` matches a closed director replaces that director at `spawn_agent(agent=…)` (prompt, capabilities, inference, skill fields); `intent=` still resolves the closed package.
+`buildChatSystemPrompt` (TUI chat) assembles: base → core tool list → name-only skills listing → live `<env>` block → appended extensions. `buildSubAgentSystemPrompt` assembles the worker prompt without a catalog skills listing. Closed directors that declare `attachedSkills` (none of the shipped directors do today; never the primary) get those bodies injected once at spawn from **plugin skill dirs only** (`skillDirsFromEnabledPlugins`) — `resolveSkillBody` is called with `pluginDirsOnly`, so a project-local `.corbits`/`.agents`/`.claude`/`.codex/skills` SKILL.md cannot become system-prompt constraints. A miss is noted in the attached section; the worker proceeds (no park). Optional skills stay names-only in the identity header; workers mount `skill_search` + `use_skill` on every family (including grok/kimi leaves), scoped to the union of `attachedSkills` and `optionalSkills`. A worker that declares neither field gets an empty allowlist (fail closed) — `skill_search` / `use_skill` match nothing until the package or plugin profile lists names. `coder` ships `optionalSkills: ["typescript"]`. Built-in catalog tools (including `skill_search`) are advertised on the primary wire and callable directly; MCP integrations are discovered via `tool_search` rather than being enumerated. Skills follow the same lazy principle on the primary: each discovered skill contributes only its name. The model calls `skill_search` for descriptions when choosing, then `use_skill` to load a body. The operator can also invoke the same skill as `/<skill-name>` (see Skills below). Skills are discovered (and deduped by name, first-wins) from enabled plugin dirs, then project `.corbits`/`.agents`/`.claude`/`.codex/skills`, then the same relative dirs under `homedir()`. A user-global path that equals the project path (cwd is home) is skipped. Corbits Code ships a bundled catalog via the first-party `corbits-skills` plugin (origin `repo`); project-local skills of the same name are shadowed by an enabled plugin skill. A trusted/enabled plugin (or local `.agents/agents/`) profile whose `id` matches a closed director replaces that director at `spawn_agent(agent=…)` (prompt, capabilities, inference, skill fields); `intent=` still resolves the closed package.
 
 **Overrides.** `loadSystemPromptOverrides` (`src/agent/context-extensions.ts`) resolves a project `SYSTEM.md` (repo root, then `.corbits/`) that **replaces** the static base block, and an `APPEND_SYSTEM.md` that is **appended** as an extension. These compose with `config.systemPromptExtensions` (profile config) and the auto-discovered `AGENTS.md`, all of which attach as appended sections after the base.
 
@@ -486,7 +486,7 @@ There is no skill `type` field required for model invocation — a skill body is
 
 `buildSkillsSection` lists discovered skill names in the system prompt (no descriptions). Details come from `skill_search`; the full instructions enter context in two ways:
 
-1. **Model** — `skill_search` for descriptions, then `use_skill` (`src/agent/use-skill.ts`) with a skill name. The handler refuses names already attached at spawn or already loaded this session (short “already in context”; it does not dump the body again). Otherwise it calls `resolveSkillBody`, strips the frontmatter, and returns the body as the tool result.
+1. **Model** — `skill_search` for descriptions, then `use_skill` (`src/agent/use-skill.ts`) with a skill name. The handler refuses names already attached at spawn or already loaded this session (short “already in context”; it does not dump the body again). Otherwise it calls `resolveSkillBody`, strips the frontmatter, and returns the body as the tool result. The result appends a `Skill directory:` footer naming the winning skill dir plus a sibling-file hint (read sibling files with `read_file` relative to that dir).
 2. **Operator** — `/<skill-name>` from `loadSkillCommands` sends the same SKILL.md body (plus typed args) to the primary as a user turn. Skills with `user-invocable: false` are omitted from the slash registry and remain `use_skill` only. Dispatch then follows the recipe.
 
 Which plugin skill directories are in scope is decided in `runner.ts` / `skillDirsFromEnabledPlugins`, which passes the enabled plugins' dirs to both `discoverSkills` (for the listing) and the `use_skill` tool (for resolution). Project-local `.corbits`/`.agents`/`.claude`/`.codex/skills` and the same dirs under `homedir()` are always searched (user paths that equal project paths are skipped). Slash-command registration is first-wins (built-ins, then plugins in discovery order), so a first-party `/implement` stays first-party if a marketplace plugin of the same slash name is also enabled.

docs/IMPLEMENTATION.md

@@ -168,7 +168,7 @@ Twenty packages under `src/agent/directors/<id>/` register in `DIRECTOR_REGISTRY
    **One advertised posix set (CL-8400).** Registry engines stay posix-named (`read_file`, `write_file`, `edit_file`, `delete_file`, `run_shell`, `search_files`, `grep`). Advertise is a 1:1 projection onto wire names (`read`, `write`, `edit`, `delete`, `bash`, `glob`, `grep`) plus the unchanged control-plane. Incoming aliases (wire names, old posix ids, Codex `shell` → `run_shell`, `update_plan` → `manage_tasks`) canonicalize onto the engine id for dispatch and grants. `apply_patch` is neither advertised nor dispatched (not an alias of `edit`). `list_dir` stays mounted and unadvertised. Director `tools.allow` stays engine names. Codex does not dual-publish `shell`+`run_shell`. Hidden `shell` coerces Codex `command` (string or `["bash","-lc",script]` argv), `workdir`, and `timeout_ms` onto `run_shell`. Hidden `update_plan` maps `plan: [{step, status}]` onto `manage_tasks(action: "create")` (`pending`/`in_progress`/`completed` → `todo`/`doing`/`done`).
 
 6. There is no static write-path declaration on packages or profiles (CL-6952 removed it — no shipped director ever set one). Instead, `agent-fleet.ts` tracks each running dispatch by cwd; a new mutating dispatch that lands on the same cwd as a live mutating peer (`pending_init`/`running`, and not a declared read-only `modelRole` of `explore`/`plan`/`review`/`test`) records at most one `concurrent-lane-overlap` entry per cwd wave in `intervention-log.ts` (class `conflict`). The wave flag clears when no live mutating writer remains for that cwd. Terminal-but-unsettled lanes (for example cancelled with `finishedAt` set while the run promise has not reached `finally`) are pruned from the map and do not warn. This is advisory only — it never blocks the spawn, since cwd overlap does not prove the two lanes touch the same files.
-7. Spawn effort: pin > package `modelRole` default (`defaultEffortForDirector`; plan/review/orchestrator=high; implement/explore/docs/test=medium) > orchestrator/worker binary > parent inheritance. Attached skills (none on the shipped directors today; never the primary) are injected into the worker system prompt at spawn from plugin skill dirs only (no project-local `.corbits`/`.agents`/`.claude`/`.codex` or user-global fallback). Optional skills are listed in the identity header for awareness; workers mount `skill_search` + `use_skill` on every family, scoped to the union of `attachedSkills` and `optionalSkills`. A worker that declares neither field gets an empty allowlist (fail closed). `coder` lists `typescript`. `use_skill` refuses names already attached or already loaded this session and does not return the body again. Primary mounts `use_skill` for its own skill list (same in-session refuse; no attached set). Plugin skill discovery also searches `<cwd>/.corbits/skills` and `homedir()/.corbits`/`.agents`/`.claude`/`.codex/skills`.
+7. Spawn effort: pin > package `modelRole` default (`defaultEffortForDirector`; plan/review/orchestrator=high; implement/explore/docs/test=medium) > orchestrator/worker binary > parent inheritance. Attached skills (none on the shipped directors today; never the primary) are injected into the worker system prompt at spawn from plugin skill dirs only (no project-local `.corbits`/`.agents`/`.claude`/`.codex` or user-global fallback). Optional skills are listed in the identity header for awareness; workers mount `skill_search` + `use_skill` on every family, scoped to the union of `attachedSkills` and `optionalSkills`. A worker that declares neither field gets an empty allowlist (fail closed). `coder` lists `typescript`. `use_skill` refuses names already attached or already loaded this session and does not return the body again. Primary mounts `use_skill` for its own skill list (same in-session refuse; no attached set). `spawn_agent` accepts a `skills[]` param unioned with the package allowlist for the worker's `skill_search` / `use_skill` scope. Plugin skill discovery also searches `<cwd>/.corbits/skills`, `homedir()/.corbits/skills`, `homedir()/.agents/skills`, `homedir()/.claude/skills`, and `homedir()/.codex/skills`.
 
 Intent defaults: `intent=implement` → director `coder`; `explore` → `explorer`; `plan` → `planner`; `review` → `reviewer`; general → error. Spawn: dispatch full fleet; all other directors mount no fleet tools. Dispatch assigns one focused task per worker; fan-out width follows independent lanes (one lane per PR/path/ownership). Live `<env>` injects cwd, platform, arch, runtime, date, and git status on every chat and worker prompt.
 

docs/PLUGINS.md

@@ -280,6 +280,7 @@ shape.
     plugin root (`pluginRoot`), with lexical containment plus a realpath check so
     a symlink under the root cannot escape. Absolute paths, bare `.` / `..`, and
     escapes outside the root are rejected (skill miss, not a crash).
+- `spawn_agent` accepts a `skills[]` param unioned with the package allowlist, scoping the worker's `skill_search` / `use_skill`.
 - An agent plugin is wired in only when `settings.plugins[id].enabled` is true
   (same gating as command plugins — no consent needed, since profiles are
   configuration data, not in-process code).

src/agent/profiles.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test";
-import { mkdtemp, writeFile } from "node:fs/promises";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
@@ -9,38 +9,46 @@ import { defined } from "../../testkit/defined.js";
 describe("loadAgentProfiles director overlay", () => {
   test("plugin extraProfiles with a closed director id replace the default", async () => {
     const dir = await mkdtemp(join(tmpdir(), "cl9917-profiles-"));
-    const profiles = await loadAgentProfiles(dir, [
-      {
-        id: "designer",
-        source: "plugin:p1",
-        systemPromptRole: "Plugin designer prompt.",
-        optionalSkills: ["better-ui"],
-      },
-    ]);
-    const designer = defined(
-      profiles.find((p) => p.id === "designer"),
-      "designer profile",
-    );
-    expect(designer.systemPromptRole).toBe("Plugin designer prompt.");
-    expect(designer.source).toBe("plugin:p1");
-    expect(designer.optionalSkills).toEqual(["better-ui"]);
+    try {
+      const profiles = await loadAgentProfiles(dir, [
+        {
+          id: "designer",
+          source: "plugin:p1",
+          systemPromptRole: "Plugin designer prompt.",
+          optionalSkills: ["better-ui"],
+        },
+      ]);
+      const designer = defined(
+        profiles.find((p) => p.id === "designer"),
+        "designer profile",
+      );
+      expect(designer.systemPromptRole).toBe("Plugin designer prompt.");
+      expect(designer.source).toBe("plugin:p1");
+      expect(designer.optionalSkills).toEqual(["better-ui"]);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
   });
 
   test("local file with a closed director id replaces the default", async () => {
     const dir = await mkdtemp(join(tmpdir(), "cl9917-profiles-local-"));
-    await writeFile(
-      join(dir, "designer.json"),
-      JSON.stringify({
-        id: "designer",
-        systemPromptRole: "Local designer prompt.",
-      }),
-    );
-    const profiles = await loadAgentProfiles(dir);
-    const designer = defined(
-      profiles.find((p) => p.id === "designer"),
-      "designer profile",
-    );
-    expect(designer.systemPromptRole).toBe("Local designer prompt.");
-    expect(designer.source).toBe("local");
+    try {
+      await writeFile(
+        join(dir, "designer.json"),
+        JSON.stringify({
+          id: "designer",
+          systemPromptRole: "Local designer prompt.",
+        }),
+      );
+      const profiles = await loadAgentProfiles(dir);
+      const designer = defined(
+        profiles.find((p) => p.id === "designer"),
+        "designer profile",
+      );
+      expect(designer.systemPromptRole).toBe("Local designer prompt.");
+      expect(designer.source).toBe("local");
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
   });
 });

src/extensions/skills.test.ts

@@ -241,6 +241,57 @@ describe("skill resolution", () => {
   });
 });
 
+describe("bare-name symlink escape", () => {
+  test("file-symlink SKILL.md pointing outside fails closed", async () => {
+    const cwd = await mkdtemp(join(tmpdir(), "skill-bare-filelink-cwd-"));
+    const outside = await mkdtemp(join(tmpdir(), "skill-bare-filelink-out-"));
+    const home = await mkdtemp(join(tmpdir(), "skill-bare-filelink-home-"));
+    try {
+      await mkdir(join(cwd, ".agents", "skills", "evil"), { recursive: true });
+      await writeFile(
+        join(outside, "SKILL.md"),
+        "escaped outside body\n",
+        "utf8",
+      );
+      await symlink(
+        join(outside, "SKILL.md"),
+        join(cwd, ".agents", "skills", "evil", "SKILL.md"),
+      );
+      await withMockedHomedir(home, async () => {
+        expect(await resolveSkillBody(cwd, "evil", [])).toBeUndefined();
+        expect(await resolveSkillWithDir(cwd, "evil", [])).toBeUndefined();
+      });
+    } finally {
+      await rm(cwd, { recursive: true, force: true });
+      await rm(outside, { recursive: true, force: true });
+      await rm(home, { recursive: true, force: true });
+    }
+  });
+
+  test("dir-symlink skill dir pointing outside fails closed", async () => {
+    const cwd = await mkdtemp(join(tmpdir(), "skill-bare-dirlink-cwd-"));
+    const outside = await mkdtemp(join(tmpdir(), "skill-bare-dirlink-out-"));
+    const home = await mkdtemp(join(tmpdir(), "skill-bare-dirlink-home-"));
+    try {
+      await mkdir(join(cwd, ".agents", "skills"), { recursive: true });
+      await writeFile(
+        join(outside, "SKILL.md"),
+        "escaped outside body\n",
+        "utf8",
+      );
+      await symlink(outside, join(cwd, ".agents", "skills", "evildir"), "dir");
+      await withMockedHomedir(home, async () => {
+        expect(await resolveSkillBody(cwd, "evildir", [])).toBeUndefined();
+        expect(await resolveSkillWithDir(cwd, "evildir", [])).toBeUndefined();
+      });
+    } finally {
+      await rm(cwd, { recursive: true, force: true });
+      await rm(outside, { recursive: true, force: true });
+      await rm(home, { recursive: true, force: true });
+    }
+  });
+});
+
 describe("path-like skill refs", () => {
   let pluginRoot: string;
 

src/extensions/skills.ts

@@ -200,7 +200,25 @@ export async function resolveSkillWithDir(
     options?.pluginDirsOnly !== true,
   )) {
     const dir = join(base, name);
-    const body = await bodyFromSkillPath(join(dir, "SKILL.md"));
+    const skillMd = join(dir, "SKILL.md");
+    // Symlink escape bar (mirrors resolvePathLikeSkill): realpath both sides
+    // so a skill dir or SKILL.md symlinked outside the winning base fails
+    // closed instead of returning outside content.
+    let realSkill: string;
+    let realBase: string;
+    try {
+      [realSkill, realBase] = await Promise.all([
+        realpath(skillMd),
+        realpath(base),
+      ]);
+    } catch {
+      // Missing base or skill → not resolvable here.
+      continue;
+    }
+    if (!pathIsInsideOrEqual(realSkill, realBase)) continue;
+    const body = await bodyFromSkillPath(realSkill);
+    // Return the lexical dir (unchanged public semantics): containment of the
+    // realpath'd SKILL.md in the realpath'd base already failed closed above.
     if (body !== undefined) return { body, dir };
   }
   return undefined;