opencode-agent-skills-md 1.0.1 → 1.1.0

package/dist/plugin.mjs

@@ -0,0 +1,1138 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import YAML from "yaml";
+import { homedir } from "node:os";
+import { tool } from "@opencode-ai/plugin";
+//#region ../core/src/debug.ts
+/**
+* Debug-gated logging for bare `catch {}` blocks.
+*
+* Bare catches stay silent by default so malformed payloads and parse
+* errors never surface as user-visible noise. Setting
+* `OPENCODE_AGENT_SKILLS_DEBUG=1` makes the diagnostic context appear on
+* stderr so developers can trace why a fallback fired.
+*
+* The env var is checked on every call (not cached at module load) so
+* tests can toggle it without re-importing the module.
+*/
+const debugLog = (...args) => {
+	if (!process.env.OPENCODE_AGENT_SKILLS_DEBUG) return;
+	console.error("[opencode-agent-skills-md]", ...args);
+};
+//#endregion
+//#region ../core/src/walk.ts
+/**
+* Internal shared directory walker.
+*
+* Walks `baseDir` recursively up to `maxDepth` and invokes `visitor` for each
+* non-skipped entry. The walker owns the traversal rules shared by skill
+* discovery (`findSkillsRecursive`) and script enumeration (`findScripts`):
+*
+*   - hidden directories (names starting with `.`) are skipped
+*   - `node_modules` and `.git` are skipped unconditionally
+*   - per-entry errors (read, stat, or visitor throw) are isolated so a
+*     single broken symlink or throwing visitor does not abort the walk
+*
+* Callers that need extra skip sets (e.g. `__pycache__`, `.venv` for the
+* scripts layer) pass them via {@link WalkOptions.skipDirs}. The walker does
+* NOT re-export its skip rules — each caller decides what extra paths are
+* not its business to enter.
+*
+* The walker is internal to the core package: it is intentionally NOT
+* re-exported from `packages/core/src/index.ts`. Callers import it
+* directly from `./walk`.
+*/
+/** Directories the walker skips on every invocation, regardless of caller. */
+const ALWAYS_SKIP = new Set(["node_modules", ".git"]);
+/**
+* Walk `baseDir` recursively, invoking `visitor` for each non-skipped entry.
+*
+* The visitor is called depth-first with the entry's `parentPath` already
+* populated (Node 20.12+), so callers can build absolute paths via
+* `path.join(entry.parentPath, entry.name)` without restating the parent.
+*
+* `currentDepth` is the depth of the directory containing the entry:
+* `0` for entries inside `baseDir`, `1` for entries inside its subdirs,
+* and so on. Entries beyond `maxDepth` are never visited.
+*
+* The visitor may be sync or async; the walker awaits it so any state
+* the visitor records (e.g. "skip this subtree") is visible to the
+* subsequent recursive step.
+*
+* A missing or unreadable `baseDir` is not an error: the walker simply
+* yields nothing. Per-entry failures (read, stat, or a throwing visitor)
+* are likewise isolated to the offending entry.
+*/
+const walkDir = async (baseDir, maxDepth, visitor, options = {}) => {
+	const skipDirs = options.skipDirs;
+	await walk(baseDir, 0, maxDepth, visitor, skipDirs);
+};
+const walk = async (dir, depth, maxDepth, visitor, skipDirs) => {
+	if (depth > maxDepth) return;
+	let entries;
+	try {
+		entries = await fs.readdir(dir, { withFileTypes: true });
+	} catch {
+		return;
+	}
+	for (const entry of entries) {
+		if (entry.name.startsWith(".")) continue;
+		if (ALWAYS_SKIP.has(entry.name)) continue;
+		if (skipDirs?.has(entry.name)) continue;
+		try {
+			await visitor(entry, depth);
+		} catch {
+			continue;
+		}
+		if (entry.isDirectory()) await walk(path.join(dir, entry.name), depth + 1, maxDepth, visitor, skipDirs);
+	}
+};
+//#endregion
+//#region ../core/src/scripts.ts
+/**
+* Script discovery and path-safety helpers.
+*
+* Pure functions: filesystem reads only, no host dependencies.
+*/
+/**
+* Directory names the script walker skips on top of the unconditional
+* `node_modules` / `.git` / hidden-dir rules owned by {@link walkDir}.
+* These are common dependency / cache directories that never host skill
+* scripts and would otherwise inflate the file scan.
+*/
+const SCRIPT_SKIP_DIRS = new Set([
+	"__pycache__",
+	".venv",
+	"venv",
+	".tox",
+	".nox"
+]);
+/**
+* Recursively find executable scripts in a skill's directory.
+*
+* Traversal is delegated to the shared {@link walkDir} utility, which owns
+* hidden-dir / `node_modules` / `.git` skip rules and per-entry error
+* isolation. The visitor checks each file entry's executable bit (the
+* `0o111` mode mask) and pushes a `Script` record only for files that
+* qualify.
+*
+* Output is sorted by `relativePath` so callers see a stable order
+* regardless of the underlying `readdir` enumeration order.
+*/
+const findScripts = async (skillPath, maxDepth = 10) => {
+	const scripts = [];
+	await walkDir(skillPath, maxDepth, async (entry) => {
+		if (!entry.isFile()) return;
+		const fullPath = path.join(entry.parentPath, entry.name);
+		const relPath = path.relative(skillPath, fullPath);
+		let stats;
+		try {
+			stats = await fs.stat(fullPath);
+		} catch {
+			return;
+		}
+		if (stats.mode & 73) scripts.push({
+			relativePath: relPath,
+			absolutePath: fullPath
+		});
+	}, { skipDirs: SCRIPT_SKIP_DIRS });
+	return scripts.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+};
+/**
+* Check if a path is safely within a base directory (no escape via .. or symlink).
+*
+* Uses fs.realpath to canonicalize both paths before comparing, which closes
+* the symlink-escape attack: a symlink inside the skill directory that points
+* outside will have its real path resolved and fail the prefix check.
+*
+* @returns Promise<boolean> — true if the resolved real path is within basePath
+*/
+const isPathSafe = async (basePath, requestedPath) => {
+	const resolved = path.resolve(basePath, requestedPath);
+	try {
+		const resolvedReal = await fs.realpath(resolved);
+		const baseReal = await fs.realpath(basePath);
+		return resolvedReal.startsWith(baseReal + path.sep) || resolvedReal === baseReal;
+	} catch {
+		return false;
+	}
+};
+//#endregion
+//#region ../core/src/parse.ts
+/**
+* YAML frontmatter parsing and skill frontmatter validation.
+*
+* Pure functions: no I/O, no host dependencies. The script-discovery step
+* that follows parsing is delegated to `core/scripts.ts`.
+*/
+/**
+* Parse YAML frontmatter using the yaml library with safe options.
+* Uses strict schema to prevent code execution from malicious YAML.
+* Handles all YAML 1.2 features including multi-line strings (| and >).
+*
+* Two distinct failure modes:
+*   - Empty frontmatter (blank / whitespace-only input) returns `{}`
+*     without touching the parser. This is a valid zero-field case.
+*   - Malformed YAML (real syntax error) is caught and logged via the
+*     `debugLog` helper; the function still returns `{}` so callers see
+*     the same graceful fallback as before.
+*/
+const parseYamlFrontmatter = (text) => {
+	if (text.trim().length === 0) return {};
+	try {
+		const result = YAML.parse(text, {
+			schema: "core",
+			maxAliasCount: 100
+		});
+		return typeof result === "object" && result !== null ? result : {};
+	} catch (error) {
+		debugLog("parseYamlFrontmatter: malformed YAML", error);
+		return {};
+	}
+};
+const NAME_REGEX = /^[\p{Ll}\p{N}-]+$/u;
+const validateFrontmatter = (obj) => {
+	if (typeof obj !== "object" || obj === null) return null;
+	const o = obj;
+	if (typeof o.name !== "string" || !NAME_REGEX.test(o.name) || o.name.length === 0) return null;
+	if (typeof o.description !== "string" || o.description.length === 0) return null;
+	if (o.trigger !== void 0 && typeof o.trigger !== "string") return null;
+	if (o.license !== void 0 && typeof o.license !== "string") return null;
+	if (o["allowed-tools"] !== void 0 && !Array.isArray(o["allowed-tools"])) return null;
+	if (o.metadata !== void 0 && typeof o.metadata !== "object") return null;
+	const frontmatter = {
+		name: o.name,
+		description: o.description
+	};
+	if (o.trigger !== void 0) frontmatter.trigger = o.trigger;
+	if (o.license !== void 0) frontmatter.license = o.license;
+	if (o["allowed-tools"] !== void 0) frontmatter["allowed-tools"] = o["allowed-tools"];
+	if (o.metadata !== void 0) frontmatter.metadata = o.metadata;
+	return frontmatter;
+};
+/**
+* Parse a SKILL.md file and validate its frontmatter.
+* Returns null if parsing fails (with error logging).
+*/
+const parseSkillFile = async (skillPath, relativePath, label) => {
+	const content = await fs.readFile(skillPath, "utf-8").catch((error) => {
+		debugLog("parseSkillFile: cannot read", skillPath, error);
+		return null;
+	});
+	if (!content) return null;
+	const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+	if (!frontmatterMatch?.[1] || !frontmatterMatch[2]) return null;
+	const frontmatterText = frontmatterMatch[1];
+	const skillContent = frontmatterMatch[2].trim();
+	let frontmatterObj;
+	try {
+		frontmatterObj = parseYamlFrontmatter(frontmatterText);
+	} catch {
+		return null;
+	}
+	const frontmatter = validateFrontmatter(frontmatterObj);
+	if (!frontmatter) return null;
+	const skillDirPath = path.dirname(skillPath);
+	const scripts = await findScripts(skillDirPath);
+	const rawNamespace = frontmatter.metadata?.namespace;
+	const namespace = typeof rawNamespace === "string" ? rawNamespace : void 0;
+	const rawTags = frontmatter.metadata?.tags;
+	const tags = Array.isArray(rawTags) ? rawTags.filter((t) => typeof t === "string") : [];
+	return {
+		name: frontmatter.name,
+		description: frontmatter.description,
+		trigger: frontmatter.trigger,
+		path: skillDirPath,
+		relativePath,
+		namespace,
+		tags,
+		label,
+		scripts,
+		template: skillContent
+	};
+};
+//#endregion
+//#region ../core/src/discovery.ts
+/**
+* Skill discovery across filesystem roots.
+*
+* The core never hard-codes a host's directory layout. Callers pass the list
+* of discovery roots; the default `getDefaultOpencodeRoots` reproduces the
+* legacy OpenCode priority order. PR2 will call `discoverAllSkills` from the
+* OpenCode host adapter with the same default.
+*/
+/**
+* Check if a file exists in a directory and return path info.
+*
+* @param directory - Directory to check
+* @param relativePath - Relative path to use in result (caller-specific)
+* @param filename - Name of file to look for (e.g., 'SKILL.md')
+* @returns Path info if file exists, null otherwise
+*/
+const findFile = async (directory, relativePath, filename) => {
+	const filePath = path.join(directory, filename);
+	try {
+		await fs.stat(filePath);
+		return {
+			filePath,
+			relativePath
+		};
+	} catch {
+		return null;
+	}
+};
+/**
+* Recursively find SKILL.md files in a directory.
+*
+* The base directory itself is checked first: a SKILL.md placed at the root
+* of a discovery root is returned with `relativePath = ""` and wins the
+* shadowing tie-break over same-name skills in subdirectories (first found
+* wins in `discoverAllSkills`).
+*
+* The traversal is delegated to the shared {@link walkDir} utility, which
+* owns hidden-dir / `node_modules` / `.git` skip rules and per-entry error
+* isolation. The visitor only checks each directory entry for SKILL.md and
+* records the labeled result; recursion and skip semantics are the walker's
+* job, not this function's.
+*
+* Output is sorted by `relativePath` so callers see a stable order across
+* runs regardless of the underlying `readdir` enumeration order.
+*/
+const findSkillsRecursive = async (baseDir, label, maxDepth = 3) => {
+	const results = [];
+	try {
+		await fs.access(baseDir);
+		const rootFile = await findFile(baseDir, "", "SKILL.md");
+		if (rootFile) results.push({
+			...rootFile,
+			label
+		});
+		await walkDir(baseDir, maxDepth, async (entry) => {
+			if (!entry.isDirectory()) return;
+			const fullPath = path.join(entry.parentPath, entry.name);
+			const found = await findFile(fullPath, path.relative(baseDir, fullPath), "SKILL.md");
+			if (found) results.push({
+				...found,
+				label
+			});
+		});
+	} catch (error) {
+		debugLog("findSkillsRecursive: cannot access baseDir", baseDir, error);
+	}
+	return results.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+};
+/**
+* Default recursion depth for the four priority discovery roots.
+*
+* Pre-refactor commit `c2d8e74` used `maxDepth: 1` for the Claude-side
+* roots; commit `12de52a` ("fix(core): unify maxDepth to 3 across all
+* discovery roots") widened them deliberately so deeply-nested Claude
+* skills surface. The regression net in
+* `tests/integration/skill-discovery.test.ts` pins this value so a
+* future narrowing breaks loudly.
+*/
+const DEFAULT_DISCOVERY_MAX_DEPTH = 3;
+/**
+* Default discovery roots matching the pre-refactor OpenCode priority order
+* (see commit `c2d8e74`, `src/skills.ts#discoverAllSkills`):
+*   1. .opencode/skills/         (project - OpenCode)
+*   2. .claude/skills/           (project - Claude)
+*   3. ~/.config/opencode/skills/ (user - OpenCode)
+*   4. ~/.claude/skills/         (user - Claude)
+*
+* No shadowing - unique names only. First match wins, duplicates are warned.
+*/
+const getDefaultOpencodeRoots = (directory) => {
+	return [
+		{
+			path: path.join(directory, ".opencode", "skills"),
+			label: "project",
+			maxDepth: DEFAULT_DISCOVERY_MAX_DEPTH
+		},
+		{
+			path: path.join(directory, ".claude", "skills"),
+			label: "claude-project",
+			maxDepth: DEFAULT_DISCOVERY_MAX_DEPTH
+		},
+		{
+			path: path.join(homedir(), ".config", "opencode", "skills"),
+			label: "user",
+			maxDepth: DEFAULT_DISCOVERY_MAX_DEPTH
+		},
+		{
+			path: path.join(homedir(), ".claude", "skills"),
+			label: "claude-user",
+			maxDepth: DEFAULT_DISCOVERY_MAX_DEPTH
+		}
+	];
+};
+/**
+* Default callback for shadowed skill names. Emits a `console.warn` that
+* identifies the surviving (existing) skill and the duplicate that was
+* skipped. Hosts can override by passing `onDuplicate` to `discoverAllSkills`.
+*
+* @internal - exported for testing
+*/
+const defaultOnDuplicate = (existing, duplicate) => {
+	console.warn(`Skill name conflict: '${existing.name}' at ${existing.path} shadows duplicate at ${duplicate.path}`);
+};
+/**
+* Discover all skills from the provided roots.
+*
+* @param directory - Project directory (used to build the default roots).
+* @param roots - Discovery roots. Defaults to the OpenCode priority order
+*   via `getDefaultOpencodeRoots(directory)`. Hosts pass an explicit list to
+*   override the layout.
+* @param onDuplicate - Optional callback invoked when two roots produce a
+*   skill with the same `name`. Defaults to `console.warn` via
+*   `defaultOnDuplicate`. The first-discovered skill wins; the duplicate
+*   (second one encountered) is passed to the callback but never stored.
+*/
+const discoverAllSkills = async (directory, roots = getDefaultOpencodeRoots(directory), onDuplicate = defaultOnDuplicate) => {
+	const allResults = [];
+	for (const { path: baseDir, label, maxDepth } of roots) allResults.push(...await findSkillsRecursive(baseDir, label, maxDepth));
+	const skillsByName = /* @__PURE__ */ new Map();
+	for (const { filePath, relativePath, label } of allResults) {
+		const skill = await parseSkillFile(filePath, relativePath, label);
+		if (!skill) continue;
+		if (skillsByName.has(skill.name)) {
+			onDuplicate(skillsByName.get(skill.name), skill);
+			continue;
+		}
+		skillsByName.set(skill.name, skill);
+	}
+	return skillsByName;
+};
+/**
+* Resolve a skill by name, handling namespace prefixes.
+* Supports: "skill-name", "project:skill-name", "user:skill-name", etc.
+*/
+const resolveSkill = (skillName, skillsByName) => {
+	if (skillName.includes(":")) {
+		const [namespace, name] = skillName.split(":");
+		for (const skill of skillsByName.values()) if (skill.name === name && (skill.label === namespace || skill.namespace === namespace)) return skill;
+		return null;
+	}
+	return skillsByName.get(skillName) || null;
+};
+/**
+* Recursively list all files in a directory, returning relative paths.
+* Excludes SKILL.md since it's already loaded as the main content.
+* Applies the same skip rules as walkDir (hidden dirs, node_modules, .git).
+*/
+const listSkillFiles = async (skillPath, maxDepth = 3) => {
+	const files = [];
+	const walk = async (dir, depth) => {
+		let entries;
+		try {
+			entries = await fs.readdir(dir, { withFileTypes: true });
+		} catch {
+			return;
+		}
+		for (const entry of entries) {
+			if (entry.name.startsWith(".")) continue;
+			if (entry.name === "node_modules" || entry.name === ".git") continue;
+			const fullPath = path.join(dir, entry.name);
+			const relPath = path.relative(skillPath, fullPath);
+			if (entry.name === "SKILL.md") continue;
+			if (entry.isDirectory()) {
+				if (depth < maxDepth) await walk(fullPath, depth + 1);
+			} else files.push(relPath);
+		}
+	};
+	await walk(skillPath, 0);
+	return files.sort();
+};
+//#endregion
+//#region ../core/src/match.ts
+/**
+* Fuzzy string matching helpers used to suggest the closest skill or script
+* name when a user request does not match exactly.
+*
+* Pure functions: no I/O, no host dependencies.
+*/
+/**
+* Calculate Levenshtein edit distance between two strings.
+* Used for fuzzy matching suggestions when skill/script names are not found.
+* @internal - exported for testing
+*/
+const levenshtein = (a, b) => {
+	const m = a.length;
+	const n = b.length;
+	const dp = Array.from({ length: m + 1 }, (_, i) => Array.from({ length: n + 1 }, (_, j) => i || j));
+	for (let i = 1; i <= m; i++) for (let j = 1; j <= n; j++) dp[i][j] = Math.min(dp[i - 1][j] + 1, dp[i][j - 1] + 1, dp[i - 1][j - 1] + (a[i - 1] !== b[j - 1] ? 1 : 0));
+	return dp[m][n];
+};
+/**
+* Find the closest matching string from a list of candidates.
+* Uses combined scoring: prefix match (strongest), substring match, then Levenshtein distance.
+* Returns the best match if similarity is above 0.4 threshold, otherwise null.
+* @internal - exported for testing
+*/
+const findClosestMatch = (input, candidates) => {
+	if (candidates.length === 0) return null;
+	const inputLower = input.toLowerCase();
+	let bestMatch = null;
+	let bestScore = 0;
+	for (const candidate of candidates) {
+		const candidateLower = candidate.toLowerCase();
+		let score = 0;
+		if (candidateLower.startsWith(inputLower)) {
+			score = .9 + inputLower.length / candidateLower.length * .1;
+			const nextChar = candidateLower[inputLower.length];
+			if (nextChar && /[-_/.]/.test(nextChar)) score += .05;
+		} else if (inputLower.startsWith(candidateLower)) score = .8;
+		else if (candidateLower.includes(inputLower) || inputLower.includes(candidateLower)) score = .7;
+		else score = 1 - levenshtein(inputLower, candidateLower) / Math.max(inputLower.length, candidateLower.length);
+		if (score > bestScore) {
+			bestScore = score;
+			bestMatch = candidate;
+		}
+	}
+	return bestScore >= .4 ? bestMatch : null;
+};
+//#endregion
+//#region ../core/src/content.ts
+/**
+* Format a list of skills as the inner bullet block used inside the
+* `<available-skills>` synthetic injection.
+*/
+const formatSkillListing = (skills) => {
+	return skills.map((s) => `- ${s.name}: ${s.description}`).join("\n");
+};
+/**
+* Render the full `<available-skills>...</available-skills>` block that the
+* host injects into a session on startup and after compaction.
+*/
+const renderAvailableSkillsBlock = (skills) => {
+	return `<available-skills>
+Use the use_skill, read_skill_file, run_skill_script, and get_available_skills tools to work with skills.
+
+${formatSkillListing(skills)}
+</available-skills>`;
+};
+//#endregion
+//#region ../core/src/search.ts
+/**
+* Tokenize a free-text query into lowercase, non-empty tokens.
+*
+* Whitespace is the only separator. Empty tokens (from leading or
+* trailing whitespace) are dropped so the caller never has to filter
+* them out before scoring.
+*/
+const tokenize = (query) => {
+	return query.toLowerCase().split(/\s+/).filter((t) => t.length > 0);
+};
+/**
+* Check whether a skill matches at least one of the supplied keywords
+* against its `metadata.tags`. OR semantics: a single tag hit is enough
+* to keep the skill in the result set. An empty keyword list is a no-op
+* (every skill passes).
+*/
+const keywordMatch = (skill, keywords) => {
+	if (keywords.length === 0) return true;
+	const tags = skill.tags ?? [];
+	return keywords.some((kw) => tags.includes(kw));
+};
+/** Compute a Levenshtein-derived similarity in the 0..1 range. */
+const similarity = (a, b) => {
+	if (a.length === 0 && b.length === 0) return 1;
+	return 1 - levenshtein(a, b) / Math.max(a.length, b.length);
+};
+/** Best description-token fuzzy similarity for a single query token. */
+const bestDescriptionTokenSim = (descLower, token) => {
+	let best = 0;
+	for (const dt of descLower.split(/\s+/)) {
+		if (dt.length === 0) continue;
+		const sim = similarity(dt, token);
+		if (sim > best) best = sim;
+	}
+	return best;
+};
+/**
+* Score a skill against a list of pre-tokenized, lowercase query
+* tokens. Returns 0 when the skill has no chance of matching (used to
+* drop it from the result). Positive scores compare higher = more
+* relevant.
+*
+* The "description contains ALL tokens" tier (50) is applied as a
+* per-token lift, not a flat bonus, so the ordering
+*   name exact > name prefix > name fuzzy > trigger > desc-all > desc-any
+* is preserved even after the `max + 0.1 * sum` multi-token formula.
+*
+* The `trigger` tier (60) is a flat per-token contribution: any token
+* that appears as a case-insensitive substring of `skill.trigger` adds
+* 60 to that token's contribution. Trigger is sandwiched between the
+* name tiers (≥70) and the description tiers (≤50) so the invariant
+*   name > trigger > description
+* holds for single-token queries.
+*/
+const scoreSkill = (skill, tokens) => {
+	if (tokens.length === 0) return 0;
+	const name = skill.name.toLowerCase();
+	const desc = skill.description.toLowerCase();
+	const trigger = skill.trigger?.toLowerCase() ?? "";
+	const descTier = tokens.every((t) => desc.includes(t)) ? 50 : 30;
+	const perToken = [];
+	for (const token of tokens) {
+		let s = 0;
+		if (name === token) s = Math.max(s, 100);
+		else if (name.startsWith(token)) s = Math.max(s, 90);
+		else {
+			const nameSim = similarity(name, token);
+			if (nameSim > .4) s = Math.max(s, 70 * nameSim);
+		}
+		if (trigger.length > 0 && trigger.includes(token)) s = Math.max(s, 60);
+		if (desc.includes(token)) s = Math.max(s, descTier);
+		else {
+			const descSim = bestDescriptionTokenSim(desc, token);
+			if (descSim > .4) s = Math.max(s, Math.min(60, 60 * descSim));
+		}
+		if (s === 0) return 0;
+		perToken.push(s);
+	}
+	return Math.max(...perToken) + .1 * perToken.reduce((a, b) => a + b, 0);
+};
+/**
+* Filter, score, and rank skills against a free-text query and an
+* optional tag-keyword filter. The keyword filter applies first
+* (it is the cheaper predicate and can only narrow the candidate
+* set), then the query is tokenized and scored.
+*
+* Returns a new array sorted by score descending. Skills with a score
+* of 0 are dropped. When the query is empty AND no keywords are
+* supplied, the input list is returned unchanged (the caller can use
+* the unranked discovery for browsing).
+*/
+const searchSkills = (skills, query, keywords) => {
+	let candidates = skills;
+	if (keywords && keywords.length > 0) candidates = candidates.filter((s) => keywordMatch(s, keywords));
+	if (!query || query.trim() === "") return candidates;
+	const tokens = tokenize(query);
+	if (tokens.length === 0) return candidates;
+	return candidates.map((skill) => ({
+		skill,
+		score: scoreSkill(skill, tokens)
+	})).filter(({ score }) => score > 0).sort((a, b) => b.score - a.score).map(({ skill }) => skill);
+};
+//#endregion
+//#region src/host.ts
+/**
+* OpenCode host adapter.
+*
+* Wraps the OpenCode SDK client (`PluginInput["client"]`) and provides
+* a bounded surface for content injection, session context, and filesystem
+* access consumed by the plugin and skill tools.
+*
+* The boundary contracts (`SkillHostClient`, `SkillHostSession`,
+* `SkillHostContext`) are declared in the `opencode-agent-skills-md-core`
+* package per spec R2; this module IMPLEMENTS them over the OpenCode SDK
+* client plus `node:fs/promises`. No other package may declare a concrete
+* implementation — the plugin package owns exactly one.
+*/
+/**
+* Build an `OpencodeSkillHost` over the supplied OpenCode SDK client.
+*
+* The host is the only place in the codebase that touches the SDK's
+* `client.session.prompt` and `client.session.messages` methods.
+*/
+const createOpencodeSkillHost = (client) => {
+	const skillClient = {
+		async injectContent(sessionID, text, context) {
+			await client.session.prompt({
+				path: { id: sessionID },
+				body: {
+					noReply: true,
+					model: context?.model,
+					agent: context?.agent,
+					parts: [{
+						type: "text",
+						text,
+						synthetic: true
+					}]
+				}
+			});
+		},
+		async getSessionContext(sessionID) {
+			try {
+				const response = await client.session.messages({
+					path: { id: sessionID },
+					query: { limit: 50 }
+				});
+				if (response.data) {
+					for (const msg of response.data) if (msg.info.role === "user" && "model" in msg.info && msg.info.model) return {
+						model: msg.info.model,
+						agent: msg.info.agent
+					};
+				}
+			} catch (error) {
+				debugLog("getSessionContext: session lookup failed", sessionID, error?.name);
+			}
+		},
+		async readFile(filePath) {
+			return fs.readFile(filePath, "utf-8");
+		},
+		async readdir(dirPath) {
+			return fs.readdir(dirPath);
+		}
+	};
+	const session = (id) => ({ id });
+	return {
+		client: skillClient,
+		session
+	};
+};
+//#endregion
+//#region src/tools.ts
+/** Escape XML special characters to prevent wrapper breakout. */
+const escapeXml = (s) => {
+	return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+};
+/** Wrap a shell argument in single quotes and escape embedded single quotes (Bourne-shell pattern). */
+const escapeShellArg = (arg) => {
+	return "'" + arg.replace(/'/g, "'\\''") + "'";
+};
+/**
+* Tool translation guide for skills written for Claude Code.
+* Injected into skill content to help the AI use OpenCode equivalents.
+*/
+const toolTranslation = `<tool-translation>
+This skill may reference Claude Code tools. Use OpenCode equivalents:
+- TodoWrite/TodoRead -> todowrite/todoread
+- Task (subagents) -> task tool with subagent_type parameter
+- Skill tool -> use_skill tool
+- Read/Write/Edit/Bash/Glob/Grep/WebFetch -> lowercase (read/write/edit/bash/glob/grep/webfetch)
+</tool-translation>`;
+/**
+* Build the four skill tool factories bound to the host, shell, and
+* project directory. The returned object is what the plugin registers
+* under its `tool` hook.
+*
+* The optional `onSkillLoaded` callback is threaded through to `UseSkill`
+* so a successful load can update host session state (e.g., the loaded-
+* skill set used to suppress duplicate match injection in `chat.message`).
+*/
+const createSkillTools = (host, $, directory, onSkillLoaded) => {
+	return {
+		GetAvailableSkills: GetAvailableSkills(directory),
+		ReadSkillFile: ReadSkillFile(directory, host),
+		RunSkillScript: RunSkillScript(directory, $),
+		UseSkill: UseSkill(directory, host, onSkillLoaded)
+	};
+};
+/**
+* Resolve a skill by name, or return a "not found" message with a
+* close-match suggestion.
+*
+* Centralizes the duplicated resolve-then-suggest pattern that
+* `use_skill`, `read_skill_file`, and `run_skill_script` all need.
+* Returning a single `string` keeps the call site trivial:
+*
+*   - skill found              → returns `skill.name`
+*   - skill missing, suggestion → `Skill "<name>" not found. Did you mean "<suggestion>"?`
+*   - skill missing, no hint    → `Skill "<name>" not found. Use get_available_skills to list available skills.`
+*
+* Not-found messages always start with the literal `Skill "` so callers
+* can detect them with `result.startsWith('Skill "')`. The skill-name
+* regex (`/^[\p{Ll}\p{N}-]+$/u`) forbids uppercase initial characters,
+* so a legitimate skill name can never collide with that prefix.
+*
+* The helper does its own discovery; callers that need the `Skill` object
+* (rather than just its name) re-resolve via a second `discoverAllSkills`
+* call. Discovery is cheap (file-listing only) and the OS-level metadata
+* cache absorbs most of the cost.
+*/
+const resolveSkillOrSuggest = async (directory, skillName) => {
+	const skillsByName = await discoverAllSkills(directory);
+	const skill = resolveSkill(skillName, skillsByName);
+	if (skill) return skill.name;
+	const suggestion = findClosestMatch(skillName, Array.from(skillsByName.values()).map((s) => s.name));
+	if (suggestion) return `Skill "${skillName}" not found. Did you mean "${suggestion}"?`;
+	return `Skill "${skillName}" not found. Use get_available_skills to list available skills.`;
+};
+const GetAvailableSkills = (directory) => {
+	return tool({
+		description: "Get available skills with their descriptions. Optionally filter by free-text query and/or tag keywords.",
+		args: {
+			query: tool.schema.string().optional().describe("Free-text search query. Matched against skill name and description; relevance-ranked."),
+			keywords: tool.schema.array(tool.schema.string()).optional().describe("Optional list of tag keywords. Only skills whose metadata.tags include at least one entry are returned.")
+		},
+		async execute(args) {
+			const skillsByName = await discoverAllSkills(directory);
+			const allSkills = Array.from(skillsByName.values());
+			const matched = searchSkills(allSkills, args.query ?? "", args.keywords);
+			if (matched.length === 0) {
+				if (args.query) {
+					const allSkillNames = allSkills.map((s) => s.name);
+					const suggestion = findClosestMatch(args.query, allSkillNames);
+					if (suggestion) return `No skills found matching "${args.query}". Did you mean "${suggestion}"?`;
+				}
+				return "No skills found matching your query.";
+			}
+			return matched.map((s) => {
+				const scripts = s.scripts.length > 0 ? ` [scripts: ${s.scripts.map((sc) => sc.relativePath).join(", ")}]` : "";
+				const trigger = s.trigger && s.trigger.length > 0 ? `\n  trigger: ${s.trigger}` : "";
+				return `${s.name} (${s.label})\n  ${s.description}${trigger}${scripts}`;
+			}).join("\n\n");
+		}
+	});
+};
+const ReadSkillFile = (directory, host) => {
+	return tool({
+		description: "Read a supporting file from a skill's directory (docs, examples, configs).",
+		args: {
+			skill: tool.schema.string().describe("Name of the skill"),
+			filename: tool.schema.string().describe("File to read, relative to skill directory (e.g., 'anthropic-best-practices.md', 'scripts/helper.sh')")
+		},
+		async execute(args, ctx) {
+			const resolved = await resolveSkillOrSuggest(directory, args.skill);
+			if (resolved.startsWith("Skill \"")) return resolved;
+			const skill = (await discoverAllSkills(directory)).get(resolved);
+			if (!skill) return `Skill "${args.skill}" not found. Use get_available_skills to list available skills.`;
+			if (!await isPathSafe(skill.path, args.filename)) return `Invalid path: cannot access files outside skill directory.`;
+			const filePath = path.join(skill.path, args.filename);
+			try {
+				const content = await host.client.readFile(filePath);
+				const wrappedContent = `<skill-file skill="${escapeXml(skill.name)}" file="${escapeXml(args.filename)}">
+  <metadata>
+    <directory>${escapeXml(skill.path)}</directory>
+  </metadata>
+
+  <content>
+${content}
+  </content>
+</skill-file>`;
+				const context = await host.client.getSessionContext(ctx.sessionID);
+				await host.client.injectContent(ctx.sessionID, wrappedContent, context);
+				return `File "${args.filename}" from skill "${skill.name}" loaded.`;
+			} catch {
+				try {
+					const files = await host.client.readdir(skill.path);
+					return `File "${args.filename}" not found. Available files: ${files.join(", ")}`;
+				} catch {
+					return `File "${args.filename}" not found in skill "${skill.name}".`;
+				}
+			}
+		}
+	});
+};
+const RunSkillScript = (directory, $) => {
+	return tool({
+		description: "Execute a script from a skill's directory. Scripts are run with the skill directory as CWD.",
+		args: {
+			skill: tool.schema.string().describe("Name of the skill"),
+			script: tool.schema.string().describe("Relative path to the script (e.g., 'build.sh', 'tools/deploy.sh')"),
+			arguments: tool.schema.array(tool.schema.string()).optional().describe("Arguments to pass to the script")
+		},
+		async execute(args) {
+			const resolved = await resolveSkillOrSuggest(directory, args.skill);
+			if (resolved.startsWith("Skill \"")) return resolved;
+			const skill = (await discoverAllSkills(directory)).get(resolved);
+			if (!skill) return `Skill "${args.skill}" not found. Use get_available_skills to list available skills.`;
+			const script = skill.scripts.find((s) => s.relativePath === args.script);
+			if (!script) {
+				const scriptPaths = skill.scripts.map((s) => s.relativePath);
+				const suggestion = findClosestMatch(args.script, scriptPaths);
+				if (suggestion) return `Script "${args.script}" not found in skill "${skill.name}". Did you mean "${suggestion}"?`;
+				const available = scriptPaths.join(", ") || "none";
+				return `Script "${args.script}" not found in skill "${skill.name}". Available scripts: ${available}`;
+			}
+			try {
+				$.cwd(skill.path);
+				const scriptArgs = (args.arguments || []).map(escapeShellArg).join(" ");
+				return await $`${script.absolutePath} ${scriptArgs}`.text();
+			} catch (error) {
+				if (error instanceof Error && "exitCode" in error) {
+					const shellError = error;
+					const stderr = shellError.stderr?.toString() || "";
+					const stdout = shellError.stdout?.toString() || "";
+					return `Script failed (exit ${shellError.exitCode}): ${stderr || stdout || shellError.message}`;
+				}
+				if (error instanceof Error) return `Script failed: ${error.message}`;
+				return `Script failed: ${String(error)}`;
+			}
+		}
+	});
+};
+const UseSkill = (directory, host, onSkillLoaded) => {
+	return tool({
+		description: "Load a skill's SKILL.md content into context. Skills contain proven workflows, techniques, and patterns.",
+		args: { skill: tool.schema.string().describe("Name of the skill (e.g., 'brainstorming', 'project:my-skill', 'user:my-skill')") },
+		async execute(args, ctx) {
+			const resolved = await resolveSkillOrSuggest(directory, args.skill);
+			if (resolved.startsWith("Skill \"")) return resolved;
+			const skill = (await discoverAllSkills(directory)).get(resolved);
+			if (!skill) return `Skill "${args.skill}" not found. Use get_available_skills to list available skills.`;
+			const skillFiles = await listSkillFiles(skill.path);
+			const scriptsXml = skill.scripts.length > 0 ? `\n    <scripts>\n${skill.scripts.map((s) => `      <script>${escapeXml(s.relativePath)}<\/script>`).join("\n")}\n    <\/scripts>` : "";
+			const filesXml = skillFiles.length > 0 ? `\n    <files>\n${skillFiles.map((f) => `      <file>${escapeXml(f)}</file>`).join("\n")}\n    </files>` : "";
+			const skillContent = `<skill name="${escapeXml(skill.name)}">
+  <metadata>
+    <source>${escapeXml(skill.label)}</source>
+    <directory>${escapeXml(skill.path)}</directory>${scriptsXml}${filesXml}
+  </metadata>
+
+  ${toolTranslation}
+
+  <content>
+${skill.template}
+  </content>
+</skill>`;
+			const context = await host.client.getSessionContext(ctx.sessionID);
+			await host.client.injectContent(ctx.sessionID, skillContent, context);
+			onSkillLoaded?.(ctx.sessionID, skill.name);
+			const scriptInfo = skill.scripts.length > 0 ? `\nAvailable scripts: ${skill.scripts.map((s) => s.relativePath).join(", ")}` : "";
+			const filesInfo = skillFiles.length > 0 ? `\nAvailable files: ${skillFiles.join(", ")}` : "";
+			return `Skill "${skill.name}" loaded.${scriptInfo}${filesInfo}`;
+		}
+	});
+};
+//#endregion
+//#region src/sdk.ts
+/** Type guard: narrows `unknown` to `ChatTextPart` when `part.type === "text"`. */
+const isChatTextPart = (part) => {
+	return typeof part === "object" && part !== null && part.type === "text";
+};
+/** Type guard: narrows `unknown` to `SessionCompactedEvent`. */
+const isSessionCompactedEvent = (event) => {
+	return typeof event === "object" && event !== null && event.type === "session.compacted";
+};
+/** Type guard: narrows `unknown` to `SessionDeletedEvent`. */
+const isSessionDeletedEvent = (event) => {
+	return typeof event === "object" && event !== null && event.type === "session.deleted";
+};
+//#endregion
+//#region src/plugin.ts
+const injectSkillsList = async (directory, host, sessionID, context, precomputed) => {
+	const skillsByName = precomputed ?? await discoverAllSkills(directory);
+	const skills = Array.from(skillsByName.values());
+	if (skills.length === 0) return;
+	await host.client.injectContent(sessionID, renderAvailableSkillsBlock(skills), context);
+};
+const maybeInjectSuperpowersBootstrap = async (directory, host, sessionID, context, precomputed) => {
+	if (process.env.OPENCODE_AGENT_SKILLS_SUPERPOWERS_MODE !== "true") return;
+	const usingSuperpowersSkill = (precomputed ?? await discoverAllSkills(directory)).get("using-superpowers");
+	if (!usingSuperpowersSkill) return;
+	const ctx = context ?? await host.client.getSessionContext(sessionID);
+	const content = `<EXTREMELY_IMPORTANT>
+You have superpowers.
+
+**IMPORTANT: The using-superpowers skill content is included below. It is ALREADY LOADED - do not call use_skill for it again. Use use_skill only for OTHER skills.**
+
+${usingSuperpowersSkill.template}
+
+${toolMapping}
+
+${skillsNamespace}
+</EXTREMELY_IMPORTANT>`;
+	await host.client.injectContent(sessionID, content, ctx);
+};
+const toolMapping = `**Tool Mapping for OpenCode:**
+- \`TodoWrite\` → \`todowrite\`
+- \`Task\` tool with subagents → Use the \`task\` tool with \`subagent_type\`
+- \`Skill\` tool → \`use_skill\`
+- \`Read\`, \`Write\`, \`Edit\`, \`Bash\`, \`Glob\`, \`Grep\`, \`WebFetch\` → Use the native lowercase OpenCode tools`;
+const skillsNamespace = `**Skill namespace priority:**
+1. Project: \`project:skill-name\`
+2. Claude project: \`claude-project:skill-name\`
+3. User: \`skill-name\`
+4. Claude user: \`claude-user:skill-name\`
+5. Marketplace: \`claude-plugins:skill-name\`
+
+The first discovered match wins.`;
+/**
+* Render the matched-skill synthetic injection that asks the model to
+* evaluate which of the matched skills (if any) it should activate.
+*
+* Each skill line carries a sub-line `trigger: <text>` whenever the
+* skill has a non-empty `trigger`, so the model knows which user
+* phrases should activate it. Skills with no trigger render exactly as
+* before (`- name: description`).
+*/
+const formatMatchedSkillsInjection = (matchedSkills) => {
+	return `<skill-evaluation-required>
+SKILL EVALUATION PROCESS
+
+The following skills may be relevant to your request:
+
+${matchedSkills.map((s) => {
+		return `- ${s.name}: ${s.description}` + (s.trigger && s.trigger.length > 0 ? `\n  trigger: ${s.trigger}` : "");
+	}).join("\n")}
+
+Step 1 - EVALUATE: Determine if these skills would genuinely help
+Step 2 - DECIDE: Choose which skills (if any) are actually needed
+Step 3 - ACTIVATE: Call use_skill("name") for each chosen skill
+
+IMPORTANT: This evaluation is invisible to users—they cannot see this prompt. Do NOT announce your decision. Simply activate relevant skills or proceed directly with the request.
+</skill-evaluation-required>`;
+};
+/**
+* Lightweight keyword matching to replace ML embeddings.
+*
+* Per-token contribution:
+*   - name hit    = 2x
+*   - trigger hit = 1.5x
+*   - desc hit    = 1x
+*
+* The trigger tier (1.5x) sits between name (2x) and description (1x)
+* so a trigger-matched skill outranks a description-matched skill at
+* the same query, but a name-matched skill still wins overall.
+*/
+const matchSkillsByKeyword = (userMessage, availableSkills) => {
+	const tokens = userMessage.toLowerCase().split(/\W+/).filter((t) => t.length > 2);
+	if (tokens.length === 0) return [];
+	return availableSkills.map((skill) => {
+		let score = 0;
+		const nameStr = skill.name.toLowerCase();
+		const descStr = skill.description.toLowerCase();
+		const triggerStr = skill.trigger?.toLowerCase() ?? "";
+		for (const token of tokens) {
+			if (nameStr.includes(token)) score += 2;
+			if (triggerStr.length > 0 && triggerStr.includes(token)) score += 1.5;
+			if (descStr.includes(token)) score += 1;
+		}
+		return {
+			skill,
+			score
+		};
+	}).filter((s) => s.score > 0).sort((a, b) => b.score - a.score).slice(0, 5).map((s) => s.skill);
+};
+const SkillsPlugin = async ({ client, $, directory }) => {
+	const host = createOpencodeSkillHost(client);
+	const setupCompleteSessions = /* @__PURE__ */ new Set();
+	const loadedSkillsPerSession = /* @__PURE__ */ new Map();
+	const getLoadedSkills = (sessionID) => {
+		let set = loadedSkillsPerSession.get(sessionID);
+		if (!set) {
+			set = /* @__PURE__ */ new Set();
+			loadedSkillsPerSession.set(sessionID, set);
+		}
+		return set;
+	};
+	/**
+	* Returns true when this chat.message is the first one for the session
+	* AND no prior message in this session already injected the available-
+	* skills block (which would mean the session was bootstrapped before
+	* this plugin instance attached).
+	*/
+	const isFirstMessageSetup = async (sessionID) => {
+		if (setupCompleteSessions.has(sessionID)) return false;
+		try {
+			const existing = await client.session.messages({ path: { id: sessionID } });
+			if (existing.data) {
+				if (existing.data.some((msg) => {
+					const m = msg;
+					const parts = Array.isArray(m.parts) ? m.parts : Array.isArray(m.info?.parts) ? m.info.parts : null;
+					if (!parts) return false;
+					return parts.some((part) => {
+						if (!isChatTextPart(part)) return false;
+						return typeof part.text === "string" && part.text.includes("<available-skills>");
+					});
+				})) setupCompleteSessions.add(sessionID);
+			}
+		} catch (error) {
+			debugLog("isFirstMessageSetup: failed to read existing messages", error);
+		}
+		return !setupCompleteSessions.has(sessionID);
+	};
+	/** Mark the session as bootstrapped and inject the available-skills block. */
+	const injectBootstrapSkills = async (sessionID, skillsByName, context) => {
+		setupCompleteSessions.add(sessionID);
+		await maybeInjectSuperpowersBootstrap(directory, host, sessionID, context, skillsByName);
+		await injectSkillsList(directory, host, sessionID, context, skillsByName);
+	};
+	/** Run keyword matching on the user message and inject the matched-skill prompt. */
+	const handleKeywordMatch = async (userText, sessionID, summaries, context) => {
+		if (!userText) return;
+		if (summaries.length === 0) return;
+		const matchedSkills = matchSkillsByKeyword(userText, summaries);
+		const loadedSkills = getLoadedSkills(sessionID);
+		const newSkills = matchedSkills.filter((s) => !loadedSkills.has(s.name));
+		if (newSkills.length === 0) return;
+		const injectionText = formatMatchedSkillsInjection(newSkills);
+		await host.client.injectContent(sessionID, injectionText, context);
+	};
+	const tools = createSkillTools(host, $, directory, (sessionID, skillName) => {
+		getLoadedSkills(sessionID).add(skillName);
+	});
+	return {
+		"chat.message": async (input, output) => {
+			const rawOutput = output;
+			if (!rawOutput || typeof rawOutput !== "object") {
+				debugLog("chat.message: missing or non-object output", output);
+				return;
+			}
+			const safeOutput = rawOutput;
+			if (typeof safeOutput.message?.sessionID !== "string") {
+				debugLog("chat.message: missing sessionID on output", safeOutput);
+				return;
+			}
+			const sessionID = safeOutput.message.sessionID;
+			const skillsByName = await discoverAllSkills(directory);
+			const summaries = Array.from(skillsByName.values()).map((skill) => ({
+				name: skill.name,
+				description: skill.description,
+				trigger: skill.trigger
+			}));
+			const context = {
+				model: safeOutput.message.model,
+				agent: safeOutput.message.agent
+			};
+			if (await isFirstMessageSetup(sessionID)) {
+				await injectBootstrapSkills(sessionID, skillsByName, context);
+				return;
+			}
+			await handleKeywordMatch((Array.isArray(safeOutput.parts) ? safeOutput.parts : []).flatMap((part) => {
+				if (!isChatTextPart(part)) return [];
+				if (part.synthetic === true) return [];
+				return typeof part.text === "string" ? [part.text] : [];
+			}).join("\n").trim(), sessionID, summaries, context);
+		},
+		event: async ({ event }) => {
+			if (isSessionCompactedEvent(event)) {
+				const sessionID = event.properties.sessionID;
+				if (typeof sessionID !== "string") {
+					debugLog("event: session.compacted missing sessionID", event);
+					return;
+				}
+				const context = await host.client.getSessionContext(sessionID);
+				await maybeInjectSuperpowersBootstrap(directory, host, sessionID, context);
+				await injectSkillsList(directory, host, sessionID, context);
+				loadedSkillsPerSession.delete(sessionID);
+				return;
+			}
+			if (isSessionDeletedEvent(event)) {
+				const sessionID = event.properties.info?.id;
+				if (typeof sessionID !== "string") {
+					debugLog("event: session.deleted missing info.id", event);
+					return;
+				}
+				setupCompleteSessions.delete(sessionID);
+				loadedSkillsPerSession.delete(sessionID);
+			}
+		},
+		tool: {
+			get_available_skills: tools.GetAvailableSkills,
+			read_skill_file: tools.ReadSkillFile,
+			run_skill_script: tools.RunSkillScript,
+			use_skill: tools.UseSkill
+		}
+	};
+};
+//#endregion
+//#region src/index.ts
+/**
+* OpenCode host adapter — root entrypoint.
+*
+* Re-exports the plugin factory as the package's default export so the
+* `rolldown` build can target this file directly. The root `src/plugin.ts`
+* shim forwards to this module to preserve the legacy import path while
+* `package.json` still resolves `dist/plugin.mjs` to the package main.
+*
+* Public surface:
+*   - default export: SkillsPlugin (the @opencode-ai/plugin Plugin factory)
+*   - named exports: SkillsPlugin, createOpencodeSkillHost
+*/
+var src_default = SkillsPlugin;
+//#endregion
+export { SkillsPlugin, createOpencodeSkillHost, src_default as default };