feat: mirror opencode built-in skills from the live inventory

opencode registers skills in code (currently `customize-opencode`,
location `<built-in>`) that have no on-disk SKILL.md, so neither the
filesystem scan nor the live merge reached them — the live entry was
dropped because its location isn't resolvable.

Materialise content-only live skills (name + description + content from
`app.skills`) into a per-process scratch dir with generated frontmatter,
so the mirror stamps and copies them like disk-backed skills. The copy
is only rewritten when the content or description changes, keeping
per-turn mtimes (and the skill-set hash) stable.

Verified against a live `opencode debug skill --pure` dump: 23 skills
parsed, `customize-opencode` lands in `.cursor/skills/` with the
sentinel and appears in the `<available_skills>` catalogue.

Author: justin-carper

README.md

@@ -318,14 +318,19 @@ The mirror includes:
 - **opencode's live skill inventory** — on every turn the mirror also consults
   opencode's `app.skills` endpoint (when reachable) and merges any skill it
   knows about that the filesystem scan missed, at the same lowest priority.
+- **opencode's built-in skills** — skills opencode registers in code rather
+  than on disk (currently `customize-opencode`, its own config-authoring
+  guide). They only exist in the live inventory, so the mirror materialises
+  them from the endpoint's content into `.cursor/skills/` like any other
+  skill; the materialised copy updates whenever opencode's version changes.
 - **Supporting files** alongside each `SKILL.md` (preserving relative paths).
 - An `<available_skills>` catalogue appended to the generated system rule,
   listing each skill's id and description so the Cursor agent can load them on
   demand.
 
-> **Note:** `config.skills.urls` (HTTP skill catalogs) are not yet supported by
-> the mirror. If you rely on URL-sourced skills, they will not appear in
-> `.cursor/skills/`.
+> **Note:** URL-sourced skills (`config.skills.urls`) that are also present in
+> opencode's live inventory reach the mirror through that route; the mirror
+> does not fetch `skills.urls` catalogs on its own.
 
 ### Permission filtering
 
@@ -359,10 +364,12 @@ user explicitly asked for them). `exclude` always drops the listed skills.
 
 ### Limitations
 
-- Plugin-bundled skills are resolved from the plugin package cache by
-  filesystem scan (`@opencode-ai/sdk` exposes no skills API), so they update
-  only when the cache is refreshed — run `opencode-plugins-refresh` after
-  installing/updating a plugin that ships skills, then restart opencode.
+- Skills served via `skills.urls` that opencode itself hasn't loaded (the
+  endpoint is reachable but the catalog wasn't pulled this session) won't
+  appear until opencode sees them.
+- Built-in skills require the live `app.skills` endpoint (i.e. a running
+  opencode server reachable by this plugin); the filesystem scan can't see
+  them on its own.
 - A user-owned `.cursor/skills/<id>/SKILL.md` (without the `generated:
   opencode-cursor` sentinel) is never overwritten or deleted.
 - Individual files larger than 1 MB are skipped (the rest of the skill is still

src/plugin/skill-discovery.ts

@@ -4,6 +4,10 @@ import {
 	statSync,
 	existsSync,
 	realpathSync,
+	mkdtempSync,
+	mkdirSync,
+	rmSync,
+	writeFileSync,
 } from "node:fs";
 import type { Dirent } from "node:fs";
 import {
@@ -13,7 +17,7 @@ import {
 	resolve as resolvePath,
 	isAbsolute,
 } from "node:path";
-import { homedir } from "node:os";
+import { homedir, tmpdir } from "node:os";
 import { execSync } from "node:child_process";
 import type { Config } from "@opencode-ai/plugin";
 
@@ -740,28 +744,112 @@ export interface LiveSkill {
 	name: string;
 	description?: string;
 	location: string;
+	/**
+	 * The skill's full body. Present for content-only skills (e.g. opencode's
+	 * `<built-in>` skills, which have no on-disk SKILL.md).
+	 */
+	content?: string;
 }
 
 /**
- * Convert live `app.skills` entries into {@link DiscoveredSkill}s, pointing
- * at each skill's on-disk directory (derived from `location`). Entries whose
- * location can't be resolved are skipped — the filesystem scan already
- * covers anything reachable.
+ * Scratch root holding materialised copies of skills that only exist in
+ * opencode's live inventory (no on-disk SKILL.md — e.g. opencode's own
+ * `<built-in>` skills, whose content is registered in code). Stable across
+ * calls so `skillSetHash` mtime checks don't churn per turn; wiped on exit.
+ */
+let liveScratchRoot: string | undefined;
+let liveScratchCleanupRegistered = false;
+
+/** Test hook: drop the scratch root so tests don't share state. */
+export function resetLiveSkillScratch(): void {
+	const root = liveScratchRoot;
+	if (root) {
+		try {
+			rmSync(root, { recursive: true, force: true });
+		} catch {
+			// best effort
+		}
+	}
+	liveScratchRoot = undefined;
+}
+
+function liveScratchDir(): string {
+	if (!liveScratchRoot) {
+		liveScratchRoot = mkdtempSync(join(tmpdir(), "opencode-cursor-skills-"));
+		if (!liveScratchCleanupRegistered) {
+			liveScratchCleanupRegistered = true;
+			const rootAtExit = liveScratchRoot;
+			process.once("exit", () => {
+				rmSync(rootAtExit, { recursive: true, force: true });
+			});
+		}
+	}
+	return liveScratchRoot;
+}
+
+/**
+ * Convert live `app.skills` entries into {@link DiscoveredSkill}s.
+ *
+ * Disk-backed entries point at the skill's on-disk directory (derived from
+ * `location`); entries whose location isn't resolvable are skipped — the
+ * filesystem scan already covers anything reachable.
+ *
+ * Content-only entries (no on-disk SKILL.md — opencode's `<built-in>` skills
+ * and anything else opencode serves from memory) are materialised into a
+ * scratch dir so the mirror can stamp and copy them like any other skill.
+ * The rewritten file carries frontmatter (the live `description`) + the
+ * live `content` body, keeping the mirror in sync with opencode's version.
  */
 export function liveSkillsToDiscovered(live: LiveSkill[]): DiscoveredSkill[] {
 	const out: DiscoveredSkill[] = [];
 	for (const skill of live) {
-		if (!skill.location) continue;
+		if (!skill.location || !skill.name) continue;
 		const sourceDir = skill.location.endsWith("SKILL.md")
 			? dirname(skill.location)
 			: skill.location;
-		if (!existsSync(join(sourceDir, "SKILL.md"))) continue;
-		const loaded = loadSkill(skill.name, sourceDir);
+		if (existsSync(join(sourceDir, "SKILL.md"))) {
+			const loaded = loadSkill(skill.name, sourceDir);
+			if (loaded) out.push(loaded);
+			continue;
+		}
+		// Not on disk: materialise if opencode gave us content.
+		if (!skill.content) continue;
+		const scratchDir = join(liveScratchDir(), skill.name);
+		const scratchMd = join(scratchDir, "SKILL.md");
+		// Rewrite only when the content or description actually changed, so
+		// per-turn calls don't touch mtimes and invalidate the skill hash.
+		let needsWrite = true;
+		if (existsSync(scratchMd)) {
+			try {
+				const existing = readFileSync(scratchMd, "utf8");
+				if (existing === renderLiveSkillMd(skill)) needsWrite = false;
+			} catch {
+				// unreadable → rewrite
+			}
+		}
+		if (needsWrite) {
+			try {
+				mkdirSync(scratchDir, { recursive: true });
+				writeFileSync(scratchMd, renderLiveSkillMd(skill), "utf8");
+			} catch {
+				continue; // scratch fs unavailable — skip this skill
+			}
+		}
+		const loaded = loadSkill(skill.name, scratchDir);
 		if (loaded) out.push(loaded);
 	}
 	return out;
 }
 
+/** Render a live (content-only) skill as a stamped SKILL.md. */
+function renderLiveSkillMd(skill: LiveSkill): string {
+	// YAML: quote the description to survive colons/quotes inside it.
+	const escaped = (skill.description ?? "").replace(/"/g, '\\"');
+	const body = skill.content ?? "";
+	const separator = body.startsWith("\n") ? "" : "\n";
+	return `---\nname: ${skill.name}\ndescription: "${escaped}"\n---\n${separator}${body}`;
+}
+
 /**
  * Discover and filter skills in one call. This is the main entry point for the
  * plugin's config and chat.params hooks. Never throws — fs errors degrade to

test/skill-discovery.test.ts

@@ -6,6 +6,8 @@ import {
 	rmSync,
 	existsSync,
 	symlinkSync,
+	readFileSync,
+	statSync,
 } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -34,8 +36,13 @@ afterAll(() => {
 	else process.env["XDG_CACHE_HOME"] = realXdgCache;
 });
 
-const { discoverSkills, filterSkills, resolveSkills, skillSetHash } =
-	await import("../src/plugin/skill-discovery.js");
+const {
+	discoverSkills,
+	filterSkills,
+	resolveSkills,
+	skillSetHash,
+	resetLiveSkillScratch,
+} = await import("../src/plugin/skill-discovery.js");
 import type { DiscoveredSkill } from "../src/plugin/skill-discovery.js";
 import type { Config } from "@opencode-ai/plugin";
 
@@ -46,6 +53,8 @@ function tmp(): string {
 	return d;
 }
 afterEach(() => {
+	// Drop the content-only live-skill scratch root between tests.
+	resetLiveSkillScratch();
 	for (const d of dirs.splice(0)) {
 		rmSync(d, { recursive: true, force: true });
 	}
@@ -883,3 +892,84 @@ describe("live skills merge (app.skills)", () => {
 		expect(result.withheld.find((w) => w.id === "live-denied")).toBeDefined();
 	});
 });
+
+describe("live built-in (content-only) skills", () => {
+	it("materialises a <built-in> skill so the mirror can copy it", () => {
+		const cwd = tmp();
+		const cacheRoot = tmp();
+		const result = resolveSkills(cwd, undefined, undefined, {
+			cacheRoot,
+			liveSkills: [
+				{
+					name: "customize-opencode",
+					description: "Use ONLY when editing opencode config.",
+					location: "<built-in>",
+					content: "# Customizing opencode\n\nBody here.",
+				},
+			],
+		});
+		const skill = result.skills.find((s) => s.id === "customize-opencode");
+		expect(skill).toBeDefined();
+		expect(skill!.description).toBe("Use ONLY when editing opencode config.");
+		// The materialised dir holds a real SKILL.md with frontmatter + body.
+		const md = readFileSync(join(skill!.sourceDir, "SKILL.md"), "utf8");
+		expect(md).toContain("name: customize-opencode");
+		expect(md).toContain("# Customizing opencode");
+		// Second resolve with identical input must not rewrite the file
+		// (mtimes stable → skillSetHash stable → no per-turn mirror churn).
+		const mtimeBefore = statSync(join(skill!.sourceDir, "SKILL.md")).mtimeMs;
+		resolveSkills(cwd, undefined, undefined, {
+			cacheRoot,
+			liveSkills: [
+				{
+					name: "customize-opencode",
+					description: "Use ONLY when editing opencode config.",
+					location: "<built-in>",
+					content: "# Customizing opencode\n\nBody here.",
+				},
+			],
+		});
+		const mtimeAfter = statSync(join(skill!.sourceDir, "SKILL.md")).mtimeMs;
+		expect(mtimeAfter).toBe(mtimeBefore);
+	});
+
+	it("rewrites the materialised copy when opencode's content changes", () => {
+		const cwd = tmp();
+		const cacheRoot = tmp();
+		const mk = (content: string) =>
+			resolveSkills(cwd, undefined, undefined, {
+				cacheRoot,
+				liveSkills: [
+					{
+						name: "builtin-v2",
+						description: "Built-in.",
+						location: "<built-in>",
+						content,
+					},
+				],
+			});
+		const first = mk("# v1");
+		expect(first.skills.find((s) => s.id === "builtin-v2")).toBeDefined();
+		const dir = first.skills.find((s) => s.id === "builtin-v2")!.sourceDir;
+		const second = mk("# v2 updated");
+		const md = readFileSync(join(dir, "SKILL.md"), "utf8");
+		expect(md).toContain("# v2 updated");
+		expect(second.skills).toHaveLength(1);
+	});
+
+	it("skips content-only entries without content or description", () => {
+		const cwd = tmp();
+		const result = resolveSkills(cwd, undefined, undefined, {
+			cacheRoot: tmp(),
+			liveSkills: [
+				{ name: "no-content", description: "d", location: "<built-in>" },
+				{
+					name: "no-description",
+					location: "<built-in>",
+					content: "# body",
+				},
+			],
+		});
+		expect(result.skills).toHaveLength(0);
+	});
+});