feat(harness): discover agent skills in the sandbox

Add the codework.prompt.skill builtin. Skills are SKILL.md directories
(and standalone .md files in .codework/skills) found through the
session's sandbox filesystem, never the host or <home>:
.codework/skills at the cwd, then .agents/skills from the cwd up to the
git root, or the sandbox root outside a repository. Only name,
description and location go into the <skills> prompt section; the model
reads the file when a task matches. Invalid frontmatter, unreadable
files and name collisions warn instead of failing.

Share the ancestor walk, the batched existence probe and BOM stripping
between the instruction and skill plugins.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: sanchitrk

CHANGELOG.md

@@ -6,6 +6,12 @@ This file is the canonical source for unreleased changes and published release n
 
 - Add in-progress work under `## [Unreleased]
 
+## [Unreleased]
+
+### Added
+
+- Added Agent Skills (`codework.prompt.skill`). A skill is a directory with a `SKILL.md` whose frontmatter has a `name` and a `description`; `.codework/skills` may also hold standalone `.md` skills. Skills are found in the session's sandbox, local or remote, and never on the host or in `<home>`: `.codework/skills` in the working directory, then `.agents/skills` in the working directory and each parent up to the git root (or up to the sandbox root outside a repository). `.gitignore`, `.ignore` and `.fdignore` are honoured. The system prompt lists only each skill's name, description and location under `<skills>`; the model reads the full file when a task matches. A skill with `disable-model-invocation: true` is not listed. Invalid fields, unreadable files and name collisions log a warning instead of failing; the first skill found keeps the name. The hint names the `read` tool, or `bash` when `read` is off, and names no tool when the reader is hidden from the prompt. Turn it off with `{ "plugin": "codework.prompt.skill", "enabled": false }` in `plugins`.
+
 ## [@codeworksh/cli@0.3.0] - 2026-10-13
 
 ### Added

packages/harness/package.json

@@ -74,7 +74,7 @@
 		"test": "vp test",
 		"test:sandbox:package": "node test/scripts/codework-sandbox-vercel-smoke.mjs",
 		"test:sandbox:package:e2e": "node test/scripts/codework-sandbox-vercel-smoke.mjs --e2e",
-		"test:sandbox:e2e": "CODEWORK_SANDBOX_E2E_REQUIRED=1 vp test --no-file-parallelism test/sandbox.vercel.e2e.test.ts test/sandbox.daytona.e2e.test.ts test/sandbox.remote.driver.e2e.test.ts test/tools.registry.remote.e2e.test.ts test/session.relink.e2e.test.ts test/plugin.instruction.e2e.test.ts"
+		"test:sandbox:e2e": "CODEWORK_SANDBOX_E2E_REQUIRED=1 vp test --no-file-parallelism test/sandbox.vercel.e2e.test.ts test/sandbox.daytona.e2e.test.ts test/sandbox.remote.driver.e2e.test.ts test/tools.registry.remote.e2e.test.ts test/session.relink.e2e.test.ts test/plugin.instruction.e2e.test.ts test/plugin.skill.e2e.test.ts"
 	},
 	"dependencies": {
 		"@codeworksh/aikit": "workspace:^",
@@ -86,11 +86,13 @@
 		"@platformatic/vfs": "^0.4.0",
 		"@silvia-odwyer/photon-node": "0.3.4",
 		"diff": "9.0.0",
+		"ignore": "7.0.8",
 		"jsonc-parser": "3.3.1",
 		"just-bash": "^3.4.2",
 		"npm-package-arg": "^14.0.0",
 		"pacote": "^22.0.0",
-		"uuidv7": "^1.2.1"
+		"uuidv7": "^1.2.1",
+		"yaml": "2.9.1"
 	},
 	"devDependencies": {
 		"@daytona/sdk": "^0.211.2",

packages/harness/src/plugin/builtin.ts

@@ -1,5 +1,6 @@
 import { defaultPromptPlugin } from "./builtin/prompt/default.ts";
 import { instructionPlugin } from "./builtin/prompt/instruction.ts";
+import { skillPlugin } from "./builtin/prompt/skill.ts";
 import { bashPlugin } from "./builtin/tool/bash.ts";
 import { editPlugin } from "./builtin/tool/edit.ts";
 import { findPlugin } from "./builtin/tool/find.ts";
@@ -24,4 +25,5 @@ export const builtins = Object.freeze([
 	lsPlugin,
 	defaultPromptPlugin,
 	instructionPlugin,
+	skillPlugin,
 ]);

packages/harness/src/plugin/builtin/prompt/instruction.ts

@@ -7,11 +7,12 @@
 
 import * as Section from "@codeworksh/plugin/plugin/section";
 import { Effect, Option } from "effect";
-import { SandboxFileSystem } from "../../../sandbox/fs/filesystem.ts";
+import type { SandboxFileSystem } from "../../../sandbox/fs/filesystem.ts";
 import { SandboxIO } from "../../../sandbox/io.ts";
 import { posix } from "../../../util/posix.ts";
 import type { SharedPluginContext } from "../../context.ts";
 import { define } from "../../plugin.ts";
+import { ancestors, present, stripBom } from "./walk.ts";
 
 /** First readable match per directory wins. */
 const names: ReadonlyArray<string> = [
@@ -31,40 +32,10 @@ export interface Found {
 }
 
 const content = (raw: string): string | undefined => {
-	const text = raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw;
+	const text = stripBom(raw);
 	return text.trim().length === 0 ? undefined : text;
 };
 
-/** `directory` and every ancestor up to the sandbox root, closest first. */
-const ancestors = (directory: string): string[] => {
-	const chain: string[] = [];
-	for (let current = directory; ; current = posix.dirname(current)) {
-		chain.push(current);
-		if (posix.dirname(current) === current) return chain;
-	}
-};
-
-/**
- * Which of `paths` are files. Absence is the expected answer and stays silent; any other failure
- * (permissions, a remote blip) is logged so a dropped file is not a mystery, then counts as absent.
- */
-const present = (fs: SandboxFileSystem.Interface, paths: ReadonlyArray<string>) =>
-	Effect.forEach(
-		paths,
-		(path) =>
-			fs.exists(path).pipe(
-				Effect.flatMap((exists) =>
-					exists ? fs.stat(path).pipe(Effect.map((stat) => stat.isFile)) : Effect.succeed(false),
-				),
-				Effect.catch((error) =>
-					SandboxFileSystem.isNotFoundError(error.cause)
-						? Effect.succeed(false)
-						: Effect.logWarning(`could not stat instruction file ${path}`, error.cause).pipe(Effect.as(false)),
-				),
-			),
-		{ concurrency: "unbounded" },
-	).pipe(Effect.map((hits) => new Set(paths.filter((_, index) => hits[index]))));
-
 /** A file that stats but does not read falls through to the next candidate. */
 const first = Effect.fnUntraced(function* (
 	fs: SandboxFileSystem.Interface,
@@ -110,6 +81,8 @@ export const discover = Effect.fnUntraced(function* (
 	const files = yield* present(
 		fs,
 		chain.flatMap((directory) => names.map((name) => posix.join(directory, name))),
+		"file",
+		"instruction file",
 	);
 	const found = yield* Effect.forEach(chain, (directory) => first(fs, directory, files), {
 		concurrency: "unbounded",