@cat-factory/executor-harness 1.45.0 → 1.47.0

package/dist/agent-runner.js

@@ -1,7 +1,7 @@
 import { spawn } from 'node:child_process';
-import { mkdtemp, rm, writeFile } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { homedir, tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
 import { killChildProcess, spawnDetached } from './process.js';
 import { redact, secretsToRedact } from './redact.js';
 function isObject(value) {
@@ -130,6 +130,31 @@ function streamCli(command, args, prompt, opts, env, secrets, onEvent) {
  * `TodoWrite` tool calls onto subtask progress and the terminal `result` event
  * onto the summary + usage.
  */
+/**
+ * Write a repo-sourced skill as a NATIVE Claude Code skill under `<skillsRoot>/<name>/`: a
+ * `SKILL.md` (YAML frontmatter `name`/`description` + the instructions body, the format the CLI
+ * expects) plus every resource file at its path within the skill directory. Resource sub-paths
+ * were sanitized at the job boundary (no traversal), so nested dirs are created as needed.
+ *
+ * The frontmatter `name`/`description` values are emitted as JSON-encoded (double-quoted) YAML
+ * scalars, not bare plain scalars: an author's description routinely contains `: ` (colon-space)
+ * or a leading YAML indicator (`#`, `-`, `[`, `{`, `"`, …), which is invalid as a plain scalar and
+ * would make the CLI fail to parse the frontmatter and silently skip the skill. A JSON string is a
+ * valid YAML double-quoted scalar, so quoting makes the manifest robust to arbitrary text.
+ */
+async function writeNativeSkill(skillsRoot, skill) {
+    const dir = join(skillsRoot, skill.name);
+    await mkdir(dir, { recursive: true });
+    const name = JSON.stringify(skill.name);
+    const description = JSON.stringify(skill.description.replace(/\r?\n/g, ' '));
+    const frontmatter = `---\nname: ${name}\ndescription: ${description}\n---\n`;
+    await writeFile(join(dir, 'SKILL.md'), `${frontmatter}\n${skill.instructions}\n`, 'utf8');
+    for (const resource of skill.resources) {
+        const dest = join(dir, resource.relPath);
+        await mkdir(dirname(dest), { recursive: true });
+        await writeFile(dest, resource.content, 'utf8');
+    }
+}
 export async function runClaudeCode(opts) {
     const stats = { toolCalls: 0, assistantChars: 0 };
     let summary = '';
@@ -219,6 +244,16 @@ export async function runClaudeCode(opts) {
             hasTrustDialogAccepted: true,
         }), { mode: 0o600 }).catch(() => { });
     }
+    // Repo-sourced Claude Skill (slice 2): install it as a native skill under the config dir's
+    // `skills/<name>/` so the CLI discovers and can invoke it. Written to the isolated per-run
+    // config home when present, else the developer's `~/.claude` (ambient/native mode). Best-effort:
+    // a write failure must not wedge the run — the prompt still names the skill.
+    if (opts.skill) {
+        const skillsRoot = configHome
+            ? join(configHome, 'skills')
+            : join(homedir(), '.claude', 'skills');
+        await writeNativeSkill(skillsRoot, opts.skill).catch(() => { });
+    }
     // Anthropic itself authenticates with the subscription OAuth token; a
     // non-Anthropic Claude-Code vendor (GLM via Z.ai, Kimi via Moonshot, DeepSeek)
     // points Claude Code at its Anthropic-compatible endpoint with an auth-token key.

package/dist/agent.js

@@ -746,6 +746,8 @@ async function runSingleRepoCoding(job, opts) {
         ...(job.persistentCheckout ? { persistentCheckout: true } : {}),
         ...(job.streamFollowUps ? { streamFollowUps: true } : {}),
         ...(job.referenceBranches?.length ? { referenceBranches: job.referenceBranches } : {}),
+        // Repo-sourced skill (slice 2): installed harness-aware by runAgentInWorkspace.
+        ...(job.skill ? { skill: job.skill } : {}),
         // Ralph loop: run the completion command after the agent commits and report its verdict.
         ...(job.validation
             ? {

package/dist/coding-agent.js

@@ -230,6 +230,7 @@ export async function runCodingAgent(spec, opts = {}) {
                 webToolsGuidance: spec.webToolsGuidance,
                 webSearchProxy: spec.webSearchProxy,
                 guardLimits: spec.guardLimits,
+                ...(spec.skill ? { skill: spec.skill } : {}),
             }, opts);
             // Stop tailing the follow-up sentinel and flush any items written after the last
             // tick, so a fast final burst still reaches the job view before the run is recorded.

package/dist/job.js

@@ -409,6 +409,78 @@ function parseContextFiles(value) {
     }
     return files;
 }
+/**
+ * Sanitize a skill resource's relative path: keep the subdirectory structure (so
+ * `templates/report.md` materialises nested) but reject anything that could escape the skill
+ * directory — absolute paths, `..` traversal, backslashes, empty/dot segments. Returns undefined
+ * for an unsafe path (the resource is then dropped).
+ */
+function sanitizeSkillRelPath(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const segments = value.replace(/\\/g, '/').split('/');
+    const clean = [];
+    for (const seg of segments) {
+        if (seg === '' || seg === '.')
+            continue;
+        if (seg === '..')
+            return undefined;
+        // Same character class as a context-file name, per segment.
+        const c = seg.replace(/[^A-Za-z0-9._-]/g, '');
+        if (!c || c === '.' || c === '..' || c.startsWith('.'))
+            return undefined;
+        clean.push(c);
+    }
+    return clean.length ? clean.join('/') : undefined;
+}
+/**
+ * Fallback native-skill directory name when the authored name has no id-safe characters (e.g. a
+ * purely non-ASCII skill name). The name is only a path segment / manifest label, so a safe
+ * default keeps the skill installable rather than dropping it — which, on the claude-code path,
+ * would leave the prompt pointing at a skill that was never installed (a blind run).
+ */
+const FALLBACK_SKILL_NAME = 'skill';
+/** A skill's own directory name, sanitized to a safe single path segment (undefined if empty). */
+function sanitizeSkillName(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const base = value.replace(/\\/g, '/').split('/').pop() ?? '';
+    const cleaned = base.replace(/[^A-Za-z0-9._-]/g, '');
+    if (!cleaned || cleaned === '.' || cleaned === '..' || cleaned.startsWith('.'))
+        return undefined;
+    return cleaned;
+}
+/** Validate the optional `skill` field, or undefined when absent/malformed. */
+function parseSkillSpec(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const o = value;
+    const instructions = typeof o.instructions === 'string' ? o.instructions : undefined;
+    // No instructions ⇒ there is nothing to run — drop the skill (the prompt still carries the
+    // folded-in directive on the Pi/codex path). An unsafe/empty NAME only affects the install
+    // directory, so fall back to a safe default rather than dropping the whole skill.
+    if (!instructions)
+        return undefined;
+    const name = sanitizeSkillName(o.name) ?? FALLBACK_SKILL_NAME;
+    const description = typeof o.description === 'string' ? o.description : '';
+    const resources = [];
+    if (Array.isArray(o.resources)) {
+        const used = new Set();
+        for (const entry of o.resources) {
+            if (typeof entry !== 'object' || entry === null)
+                continue;
+            const e = entry;
+            const relPath = sanitizeSkillRelPath(e.relPath);
+            if (!relPath || used.has(relPath))
+                continue;
+            if (typeof e.content !== 'string')
+                continue;
+            used.add(relPath);
+            resources.push({ relPath, content: e.content });
+        }
+    }
+    return { name, description, instructions, resources };
+}
 /** Parse the explore-mode infra stand-up spec, or undefined when absent/unrecognised. */
 function parseAgentInfraSpec(value) {
     if (typeof value !== 'object' || value === null)
@@ -608,6 +680,7 @@ export function parseAgentJob(input) {
     const bootstrap = parseAgentBootstrapSpec(o.bootstrap);
     const contextFiles = parseContextFiles(o.contextFiles);
     const packageRegistries = parsePackageRegistries(o.packageRegistries);
+    const skill = parseSkillSpec(o.skill);
     const testSecrets = parseTestSecrets(o.testSecrets);
     const guardLimits = parseGuardLimits(o.guardLimits);
     const validation = parseValidationSpec(o.validation);
@@ -630,6 +703,7 @@ export function parseAgentJob(input) {
         ...(output ? { output } : {}),
         ...(contextFiles.length ? { contextFiles } : {}),
         ...(packageRegistries.length ? { packageRegistries } : {}),
+        ...(skill ? { skill } : {}),
         ...(testSecrets.length ? { testSecrets } : {}),
         ...(infra ? { infra } : {}),
         ...(typeof o.newBranch === 'string' && o.newBranch ? { newBranch: o.newBranch } : {}),

package/dist/pi-workspace.js

@@ -2,7 +2,7 @@ import { mkdir, mkdtemp, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { log } from './logger.js';
-import { CONTEXT_DIR, materializeContextFiles, mergeGuardLimits, progressGuardLimitsFromEnv, runPi, webSearchConfigFromEnv, webSearchProxyEnv, writeAgentsContext, writePiModelsConfig, writeWebToolsConfig, } from './pi.js';
+import { CONTEXT_DIR, materializeContextFiles, materializeSkillResources, mergeGuardLimits, progressGuardLimitsFromEnv, runPi, webSearchConfigFromEnv, webSearchProxyEnv, writeAgentsContext, writePiModelsConfig, writeWebToolsConfig, } from './pi.js';
 import { runSubscriptionHarness } from './agent-runner.js';
 // The thin base every container agent shares: an ephemeral working directory, and
 // one Pi run inside it driven by the harness-written context. The agents differ in
@@ -117,6 +117,13 @@ export async function runAgentInWorkspace(spec, opts = {}) {
     // harness paths; kept out of the agent's commits via a local git exclude entry.
     const contextFiles = spec.contextFiles ?? [];
     await materializeContextFiles(spec.dir, contextFiles);
+    // Repo-sourced skill (slice 2): claude-code installs it natively (written by the runner into the
+    // config dir), so it reads from there. Every other harness (Pi/codex) reads the checkout, so
+    // materialise the skill's resources under `.cat-context/skill/` (its instructions are folded
+    // into the prompt by the backend). A resource-free skill is a no-op here.
+    if (spec.skill && spec.harness !== 'claude-code') {
+        await materializeSkillResources(spec.dir, spec.skill);
+    }
     // Subscription harnesses (Claude Code / Codex) authenticate with the leased
     // token and talk direct to the vendor — no proxy config, no AGENTS.md. The
     // system prompt is passed straight to the CLI; everything around this (clone,
@@ -135,6 +142,7 @@ export async function runAgentInWorkspace(spec, opts = {}) {
             ...(spec.subscriptionToken ? { subscriptionToken: spec.subscriptionToken } : {}),
             subscriptionBaseUrl: spec.subscriptionBaseUrl,
             ...(spec.ambientAuth ? { ambientAuth: true } : {}),
+            ...(spec.skill ? { skill: spec.skill } : {}),
             signal: opts.signal,
             onActivity: opts.onActivity,
             onProgress: opts.onProgress,

package/dist/pi.js

@@ -206,6 +206,36 @@ export async function materializeContextFiles(cwd, files) {
         // No writable .git/info; the files simply stay untracked (still not auto-added on most flows).
     }
 }
+/** Subdirectory of {@link CONTEXT_DIR} where a repo-sourced skill's resources are materialised. */
+export const SKILL_CONTEXT_SUBDIR = 'skill';
+/**
+ * Materialise a repo-sourced skill's RESOURCE files under `.cat-context/skill/` in the checkout
+ * (repo-sourced Claude Skills, slice 2) — the Pi/codex path, whose agents read the checkout rather
+ * than a native `~/.claude/skills` dir (the skill's instructions are folded into their prompt by
+ * the backend). Resource sub-paths were sanitized at the job boundary (no traversal), so nested
+ * dirs are created as needed. Kept out of the agent's commits via the same `.cat-context/` git
+ * exclude entry. A skill with no resource bodies is a no-op.
+ */
+export async function materializeSkillResources(cwd, skill) {
+    if (!skill.resources.length)
+        return;
+    const dir = join(cwd, CONTEXT_DIR, SKILL_CONTEXT_SUBDIR);
+    await mkdir(dir, { recursive: true });
+    for (const r of skill.resources) {
+        const dest = join(dir, r.relPath);
+        await mkdir(dirname(dest), { recursive: true });
+        await writeFile(dest, r.content, 'utf8');
+    }
+    const gitRoot = await findGitRoot(cwd);
+    if (!gitRoot)
+        return;
+    try {
+        await appendFile(join(gitRoot, '.git', 'info', 'exclude'), `\n${CONTEXT_DIR}/\n`, 'utf8');
+    }
+    catch {
+        // No writable .git/info; the files simply stay untracked.
+    }
+}
 /** Walk up from `dir` (bounded) to the directory containing a `.git` folder, or null. */
 async function findGitRoot(dir) {
     let current = dir;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/executor-harness",
-  "version": "1.45.0",
+  "version": "1.47.0",
   "description": "Container payload: a thin TypeScript wrapper that runs the Pi coding agent against a cloned repo and opens a PR. Runs in the Cloudflare Container (and, in local native mode, as a host process); carries no secrets.",
   "repository": {
     "type": "git",
@@ -26,8 +26,8 @@
     "hono": "^4.12.29",
     "typescript": "7.0.2",
     "vitest": "^4.1.10",
-    "@cat-factory/server": "0.126.0",
-    "@cat-factory/spend": "0.12.37"
+    "@cat-factory/server": "0.129.0",
+    "@cat-factory/spend": "0.12.41"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/agent-runner.ts

@@ -1,7 +1,7 @@
 import { spawn } from 'node:child_process'
-import { mkdtemp, rm, writeFile } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { homedir, tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
 import type { HarnessCallMetric, PiRunOutcome, PiRunStats, TodoProgress } from './pi.js'
 import { killChildProcess, spawnDetached } from './process.js'
 import { redact, secretsToRedact } from './redact.js'
@@ -52,6 +52,18 @@ export interface SubscriptionRunOptions {
    * container.
    */
   ambientAuth?: boolean
+  /**
+   * A repo-sourced Claude Skill to install natively before launch (repo-sourced Claude Skills,
+   * slice 2). The claude-code runner writes it to `CLAUDE_CONFIG_DIR/skills/<name>/SKILL.md`
+   * (+ resource files) so the CLI loads it; the codex runner ignores it (codex reads the
+   * checkout's `.cat-context/skill/`, materialised by the caller). Absent ⇒ no skill installed.
+   */
+  skill?: {
+    name: string
+    description: string
+    instructions: string
+    resources: { relPath: string; content: string }[]
+  }
   /** Aborting this kills the CLI (the job's inactivity/max-duration watchdog). */
   signal?: AbortSignal
   /** Called on every chunk of CLI output, so the watchdog sees the agent is alive. */
@@ -202,6 +214,35 @@ function streamCli(
  * `TodoWrite` tool calls onto subtask progress and the terminal `result` event
  * onto the summary + usage.
  */
+/**
+ * Write a repo-sourced skill as a NATIVE Claude Code skill under `<skillsRoot>/<name>/`: a
+ * `SKILL.md` (YAML frontmatter `name`/`description` + the instructions body, the format the CLI
+ * expects) plus every resource file at its path within the skill directory. Resource sub-paths
+ * were sanitized at the job boundary (no traversal), so nested dirs are created as needed.
+ *
+ * The frontmatter `name`/`description` values are emitted as JSON-encoded (double-quoted) YAML
+ * scalars, not bare plain scalars: an author's description routinely contains `: ` (colon-space)
+ * or a leading YAML indicator (`#`, `-`, `[`, `{`, `"`, …), which is invalid as a plain scalar and
+ * would make the CLI fail to parse the frontmatter and silently skip the skill. A JSON string is a
+ * valid YAML double-quoted scalar, so quoting makes the manifest robust to arbitrary text.
+ */
+async function writeNativeSkill(
+  skillsRoot: string,
+  skill: NonNullable<SubscriptionRunOptions['skill']>,
+): Promise<void> {
+  const dir = join(skillsRoot, skill.name)
+  await mkdir(dir, { recursive: true })
+  const name = JSON.stringify(skill.name)
+  const description = JSON.stringify(skill.description.replace(/\r?\n/g, ' '))
+  const frontmatter = `---\nname: ${name}\ndescription: ${description}\n---\n`
+  await writeFile(join(dir, 'SKILL.md'), `${frontmatter}\n${skill.instructions}\n`, 'utf8')
+  for (const resource of skill.resources) {
+    const dest = join(dir, resource.relPath)
+    await mkdir(dirname(dest), { recursive: true })
+    await writeFile(dest, resource.content, 'utf8')
+  }
+}
+
 export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRunOutcome> {
   const stats: PiRunStats = { toolCalls: 0, assistantChars: 0 }
   let summary = ''
@@ -297,6 +338,17 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
     ).catch(() => {})
   }
 
+  // Repo-sourced Claude Skill (slice 2): install it as a native skill under the config dir's
+  // `skills/<name>/` so the CLI discovers and can invoke it. Written to the isolated per-run
+  // config home when present, else the developer's `~/.claude` (ambient/native mode). Best-effort:
+  // a write failure must not wedge the run — the prompt still names the skill.
+  if (opts.skill) {
+    const skillsRoot = configHome
+      ? join(configHome, 'skills')
+      : join(homedir(), '.claude', 'skills')
+    await writeNativeSkill(skillsRoot, opts.skill).catch(() => {})
+  }
+
   // Anthropic itself authenticates with the subscription OAuth token; a
   // non-Anthropic Claude-Code vendor (GLM via Z.ai, Kimi via Moonshot, DeepSeek)
   // points Claude Code at its Anthropic-compatible endpoint with an auth-token key.

package/src/agent.ts

@@ -894,6 +894,8 @@ async function runSingleRepoCoding(job: AgentJob, opts: RunOptions): Promise<Age
         ...(job.persistentCheckout ? { persistentCheckout: true } : {}),
         ...(job.streamFollowUps ? { streamFollowUps: true } : {}),
         ...(job.referenceBranches?.length ? { referenceBranches: job.referenceBranches } : {}),
+        // Repo-sourced skill (slice 2): installed harness-aware by runAgentInWorkspace.
+        ...(job.skill ? { skill: job.skill } : {}),
         // Ralph loop: run the completion command after the agent commits and report its verdict.
         ...(job.validation
           ? {

package/src/coding-agent.ts

@@ -10,6 +10,7 @@ import type {
   PeerRepoSpec,
   ReferenceRepoSpec,
   RepoSpec,
+  SkillSpec,
 } from './job.js'
 import {
   branchAheadOfBase,
@@ -101,6 +102,12 @@ export interface CodingAgentSpec extends HarnessAuthFields {
    * condition — computed by the harness, never the model). Absent for every non-`ralph` run.
    */
   validation?: { command: string; iteration?: number }
+  /**
+   * A repo-sourced Claude Skill to make available for this run (a `skill` step, slice 2). Threaded
+   * into {@link runAgentInWorkspace}, which installs it harness-aware (native `~/.claude/skills`
+   * for claude-code, `.cat-context/skill/` for Pi/codex). Absent ⇒ no skill.
+   */
+  skill?: SkillSpec
 }
 
 /** The outcome of a coding agent run, before each caller maps it to its own result shape. */
@@ -370,6 +377,7 @@ export async function runCodingAgent(
             webToolsGuidance: spec.webToolsGuidance,
             webSearchProxy: spec.webSearchProxy,
             guardLimits: spec.guardLimits,
+            ...(spec.skill ? { skill: spec.skill } : {}),
           },
           opts,
         )

package/src/job.ts

@@ -621,6 +621,26 @@ export interface ContextFileSpec {
   content: string
 }
 
+/** One materialisable resource file of a skill (repo-sourced Claude Skills). */
+export interface SkillResourceSpec {
+  /** Path within the skill directory, e.g. `templates/report.md` (subdirs preserved, no traversal). */
+  relPath: string
+  content: string
+}
+
+/**
+ * A repo-sourced Claude Skill to make available for a `skill` step. Materialised HARNESS-AWARE:
+ * `CLAUDE_CONFIG_DIR/skills/<name>/SKILL.md` (+ resources) for the claude-code CLI to load
+ * natively, or `.cat-context/skill/<relPath>` for the Pi/codex checkout (their prompt carries the
+ * instructions). A dedicated top-level body field (like `packageRegistries`), never a context file.
+ */
+export interface SkillSpec {
+  name: string
+  description: string
+  instructions: string
+  resources: SkillResourceSpec[]
+}
+
 /** How an explore agent's reply is consumed. */
 export interface AgentOutputSpec {
   /** `prose` keeps the reply text; `structured` parses (and optionally repairs) it to JSON. */
@@ -707,6 +727,12 @@ export interface AgentJob extends HarnessAuthFields {
    * job on a reused container is removed.
    */
   packageRegistries?: PackageRegistrySpec[]
+  /**
+   * A repo-sourced Claude Skill to make available for a `skill` step (see {@link SkillSpec}).
+   * Materialised harness-aware before the run: natively into `CLAUDE_CONFIG_DIR/skills/<name>/`
+   * for claude-code, or `.cat-context/skill/<relPath>` for Pi/codex. Absent ⇒ no skill installed.
+   */
+  skill?: SkillSpec
   /**
    * Tester kinds only: sensitive test credentials injected into the run's ENVIRONMENT (out of
    * band) as `{ key, value }` env pairs, so the tester's shell can read `$KEY` without the value
@@ -943,6 +969,71 @@ function parseContextFiles(value: unknown): ContextFileSpec[] {
   return files
 }
 
+/**
+ * Sanitize a skill resource's relative path: keep the subdirectory structure (so
+ * `templates/report.md` materialises nested) but reject anything that could escape the skill
+ * directory — absolute paths, `..` traversal, backslashes, empty/dot segments. Returns undefined
+ * for an unsafe path (the resource is then dropped).
+ */
+function sanitizeSkillRelPath(value: unknown): string | undefined {
+  if (typeof value !== 'string') return undefined
+  const segments = value.replace(/\\/g, '/').split('/')
+  const clean: string[] = []
+  for (const seg of segments) {
+    if (seg === '' || seg === '.') continue
+    if (seg === '..') return undefined
+    // Same character class as a context-file name, per segment.
+    const c = seg.replace(/[^A-Za-z0-9._-]/g, '')
+    if (!c || c === '.' || c === '..' || c.startsWith('.')) return undefined
+    clean.push(c)
+  }
+  return clean.length ? clean.join('/') : undefined
+}
+
+/**
+ * Fallback native-skill directory name when the authored name has no id-safe characters (e.g. a
+ * purely non-ASCII skill name). The name is only a path segment / manifest label, so a safe
+ * default keeps the skill installable rather than dropping it — which, on the claude-code path,
+ * would leave the prompt pointing at a skill that was never installed (a blind run).
+ */
+const FALLBACK_SKILL_NAME = 'skill'
+
+/** A skill's own directory name, sanitized to a safe single path segment (undefined if empty). */
+function sanitizeSkillName(value: unknown): string | undefined {
+  if (typeof value !== 'string') return undefined
+  const base = value.replace(/\\/g, '/').split('/').pop() ?? ''
+  const cleaned = base.replace(/[^A-Za-z0-9._-]/g, '')
+  if (!cleaned || cleaned === '.' || cleaned === '..' || cleaned.startsWith('.')) return undefined
+  return cleaned
+}
+
+/** Validate the optional `skill` field, or undefined when absent/malformed. */
+function parseSkillSpec(value: unknown): SkillSpec | undefined {
+  if (typeof value !== 'object' || value === null) return undefined
+  const o = value as Record<string, unknown>
+  const instructions = typeof o.instructions === 'string' ? o.instructions : undefined
+  // No instructions ⇒ there is nothing to run — drop the skill (the prompt still carries the
+  // folded-in directive on the Pi/codex path). An unsafe/empty NAME only affects the install
+  // directory, so fall back to a safe default rather than dropping the whole skill.
+  if (!instructions) return undefined
+  const name = sanitizeSkillName(o.name) ?? FALLBACK_SKILL_NAME
+  const description = typeof o.description === 'string' ? o.description : ''
+  const resources: SkillResourceSpec[] = []
+  if (Array.isArray(o.resources)) {
+    const used = new Set<string>()
+    for (const entry of o.resources) {
+      if (typeof entry !== 'object' || entry === null) continue
+      const e = entry as Record<string, unknown>
+      const relPath = sanitizeSkillRelPath(e.relPath)
+      if (!relPath || used.has(relPath)) continue
+      if (typeof e.content !== 'string') continue
+      used.add(relPath)
+      resources.push({ relPath, content: e.content })
+    }
+  }
+  return { name, description, instructions, resources }
+}
+
 /** Parse the explore-mode infra stand-up spec, or undefined when absent/unrecognised. */
 function parseAgentInfraSpec(value: unknown): AgentInfraSpec | undefined {
   if (typeof value !== 'object' || value === null) return undefined
@@ -1182,6 +1273,7 @@ export function parseAgentJob(input: unknown): AgentJob {
   const bootstrap = parseAgentBootstrapSpec(o.bootstrap)
   const contextFiles = parseContextFiles(o.contextFiles)
   const packageRegistries = parsePackageRegistries(o.packageRegistries)
+  const skill = parseSkillSpec(o.skill)
   const testSecrets = parseTestSecrets(o.testSecrets)
   const guardLimits = parseGuardLimits(o.guardLimits)
   const validation = parseValidationSpec(o.validation)
@@ -1204,6 +1296,7 @@ export function parseAgentJob(input: unknown): AgentJob {
     ...(output ? { output } : {}),
     ...(contextFiles.length ? { contextFiles } : {}),
     ...(packageRegistries.length ? { packageRegistries } : {}),
+    ...(skill ? { skill } : {}),
     ...(testSecrets.length ? { testSecrets } : {}),
     ...(infra ? { infra } : {}),
     ...(typeof o.newBranch === 'string' && o.newBranch ? { newBranch: o.newBranch } : {}),

package/src/pi-workspace.ts

@@ -1,7 +1,7 @@
 import { mkdir, mkdtemp, rm } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
-import type { RepoSpec } from './job.js'
+import type { RepoSpec, SkillSpec } from './job.js'
 import { log } from './logger.js'
 import {
   type ContextFileInfo,
@@ -11,6 +11,7 @@ import {
   type RunDiagnostics,
   CONTEXT_DIR,
   materializeContextFiles,
+  materializeSkillResources,
   mergeGuardLimits,
   progressGuardLimitsFromEnv,
   runPi,
@@ -201,6 +202,13 @@ export interface AgentRunSpec {
    * from AGENTS.md, so the agent reads them on demand. Absent ⇒ none.
    */
   contextFiles?: ContextFileInfo[]
+  /**
+   * A repo-sourced Claude Skill to make available for this run (slice 2). Installed HARNESS-AWARE:
+   * the claude-code runner writes it natively into the config dir's `skills/`; for Pi/codex the
+   * resource files are materialised under `.cat-context/skill/` (their prompt already carries the
+   * folded-in instructions). Absent ⇒ no skill.
+   */
+  skill?: SkillSpec
   /**
    * Enable proxy-backed web search: point the rpiv-web-tools SearXNG provider at the
    * backend's search proxy (`${proxyBaseUrl}/web-search`) with the session token as
@@ -232,6 +240,13 @@ export async function runAgentInWorkspace(
   // harness paths; kept out of the agent's commits via a local git exclude entry.
   const contextFiles = spec.contextFiles ?? []
   await materializeContextFiles(spec.dir, contextFiles)
+  // Repo-sourced skill (slice 2): claude-code installs it natively (written by the runner into the
+  // config dir), so it reads from there. Every other harness (Pi/codex) reads the checkout, so
+  // materialise the skill's resources under `.cat-context/skill/` (its instructions are folded
+  // into the prompt by the backend). A resource-free skill is a no-op here.
+  if (spec.skill && spec.harness !== 'claude-code') {
+    await materializeSkillResources(spec.dir, spec.skill)
+  }
 
   // Subscription harnesses (Claude Code / Codex) authenticate with the leased
   // token and talk direct to the vendor — no proxy config, no AGENTS.md. The
@@ -251,6 +266,7 @@ export async function runAgentInWorkspace(
       ...(spec.subscriptionToken ? { subscriptionToken: spec.subscriptionToken } : {}),
       subscriptionBaseUrl: spec.subscriptionBaseUrl,
       ...(spec.ambientAuth ? { ambientAuth: true } : {}),
+      ...(spec.skill ? { skill: spec.skill } : {}),
       signal: opts.signal,
       onActivity: opts.onActivity,
       onProgress: opts.onProgress,

package/src/pi.ts

@@ -244,6 +244,38 @@ export async function materializeContextFiles(
   }
 }
 
+/** Subdirectory of {@link CONTEXT_DIR} where a repo-sourced skill's resources are materialised. */
+export const SKILL_CONTEXT_SUBDIR = 'skill'
+
+/**
+ * Materialise a repo-sourced skill's RESOURCE files under `.cat-context/skill/` in the checkout
+ * (repo-sourced Claude Skills, slice 2) — the Pi/codex path, whose agents read the checkout rather
+ * than a native `~/.claude/skills` dir (the skill's instructions are folded into their prompt by
+ * the backend). Resource sub-paths were sanitized at the job boundary (no traversal), so nested
+ * dirs are created as needed. Kept out of the agent's commits via the same `.cat-context/` git
+ * exclude entry. A skill with no resource bodies is a no-op.
+ */
+export async function materializeSkillResources(
+  cwd: string,
+  skill: { resources: { relPath: string; content: string }[] },
+): Promise<void> {
+  if (!skill.resources.length) return
+  const dir = join(cwd, CONTEXT_DIR, SKILL_CONTEXT_SUBDIR)
+  await mkdir(dir, { recursive: true })
+  for (const r of skill.resources) {
+    const dest = join(dir, r.relPath)
+    await mkdir(dirname(dest), { recursive: true })
+    await writeFile(dest, r.content, 'utf8')
+  }
+  const gitRoot = await findGitRoot(cwd)
+  if (!gitRoot) return
+  try {
+    await appendFile(join(gitRoot, '.git', 'info', 'exclude'), `\n${CONTEXT_DIR}/\n`, 'utf8')
+  } catch {
+    // No writable .git/info; the files simply stay untracked.
+  }
+}
+
 /** Walk up from `dir` (bounded) to the directory containing a `.git` folder, or null. */
 async function findGitRoot(dir: string): Promise<string | null> {
   let current = dir