@crustjs/skills 0.2.1 → 0.3.1

package/README.md

@@ -5,7 +5,7 @@ Package and install agent skills for AI coding assistants.
 ## Install
 
 ```sh
-bun add @crustjs/skills
+npm install @crustjs/skills
 ```
 
 ## Documentation

package/dist/index.d.ts

@@ -1,29 +1,4 @@
 import { CommandDefinition, CommandSnapshot, ExtensionFactory } from "@crustjs/core";
-//#region src/build.d.ts
-/** Options for rendering a skill source. */
-interface WriteSkillsOptions {
-  /** Application whose command tree is rendered into a generated skill. Omit to write only `extras`. */
-  readonly app?: {
-    snapshot(): Promise<CommandSnapshot>;
-  };
-  /** `skills` directory that receives one subdirectory per skill. */
-  readonly outDir: string;
-  /** Version recorded in the generated skill's SKILL.md metadata. Omitted when absent. */
-  readonly version?: string;
-  /** Generated skill name. Defaults to the root command name. */
-  readonly name?: string;
-  /** Generated skill description. Defaults to the root command description. */
-  readonly description?: string;
-  /** Hand-authored skill directories included alongside the generated skill. */
-  readonly extras?: readonly (string | URL)[];
-}
-/**
- * Renders generated and authored skills into a package-ready skill source.
- */
-export declare function writeSkills({ app, ...options }: WriteSkillsOptions): Promise<readonly string[]>;
-/** Renders skills from a Command Snapshot prepared in this or another process. */
-export declare function writeSkillsFromSnapshot(snapshot: CommandSnapshot, options: Omit<WriteSkillsOptions, "app">): Promise<readonly string[]>;
-//#endregion
 //#region src/agents.d.ts
 type AgentClass = "universal" | "additional";
 type Scope = "global" | "project";
@@ -95,10 +70,11 @@ interface SkillStatusResult {
     status: SkillLinkStatus;
   }>;
 }
-/** Options for the skills extension. */
+/**
+ * Options for the skills extension. Packaged skills are read at runtime from
+ * `resolveArtifactDir("skills")` (`@crustjs/core`), the directory `crust build` stages.
+ */
 interface SkillOptions {
-  /** Packaged skills directory read at runtime for discovery and installation. */
-  distDir: string | URL;
   /** Hand-authored skill directories (URL, absolute, or package-root-relative path) built alongside the generated skill. */
   extras?: readonly (string | URL)[];
   /** Generated command skill name. Defaults to the root command name. */
@@ -116,10 +92,35 @@ interface SkillOptions {
   defaultScope?: Scope;
   /** Repair stale or dangling owned links before commands run. @default true */
   autoUpdate?: boolean;
-  /** Name of the interactive management command. @default "skill" */
+  /** Name of the interactive management command. The default includes a `skill` alias. @default "skills" */
   command?: string;
 }
 //#endregion
+//#region src/build.d.ts
+/** Options for rendering a skill source. */
+interface WriteSkillsOptions {
+  /** Application whose command tree is rendered into a generated skill. Omit to write only `extras`. */
+  readonly app?: {
+    snapshot(): Promise<CommandSnapshot>;
+  };
+  /** `skills` directory that receives one subdirectory per skill. */
+  readonly outDir: string;
+  /** Version recorded in the generated skill's SKILL.md metadata. Omitted when absent. */
+  readonly version?: string;
+  /** Generated skill name. Defaults to the root command name. */
+  readonly name?: string;
+  /** Generated skill description. Defaults to the root command description. */
+  readonly description?: string;
+  /** Hand-authored skill directories included alongside the generated skill. */
+  readonly extras?: readonly (string | URL)[];
+}
+/**
+ * Renders generated and authored skills into a package-ready skill source.
+ */
+export declare function writeSkills({ app, ...options }: WriteSkillsOptions): Promise<readonly string[]>;
+/** Renders skills from a Command Snapshot prepared in this or another process. */
+export declare function writeSkillsFromSnapshot(snapshot: CommandSnapshot, options: Omit<WriteSkillsOptions, "app">): Promise<readonly string[]>;
+//#endregion
 //#region src/errors.d.ts
 export declare class SkillSourceConflictError extends Error {
   override readonly name = "SkillSourceConflictError";
@@ -145,7 +146,7 @@ export declare const skill: ExtensionFactory<[options: SkillOptions], {}, [], []
 export declare function installSkill(options: InstallSkillOptions): Promise<InstallSkillResult>;
 /** Unlinks only agent-directory entries carrying the requested skill's ownership signature. */
 export declare function uninstallSkill(options: UninstallSkillOptions): Promise<UninstallSkillResult>;
-/** Reports the ownership and health of each requested agent-directory entry. */
+/** Reports ownership and health. Only ENOENT is missing; other filesystem errors reject. */
 export declare function getSkillStatus(options: SkillStatusOptions): Promise<SkillStatusResult>;
 //#endregion
 //#region src/skill-name.d.ts
@@ -158,21 +159,19 @@ export declare function getSkillStatus(options: SkillStatusOptions): Promise<Ski
 export declare function isValidSkillName(name: string): boolean;
 //#endregion
 //#region src/source.d.ts
+/** The packaged skills root is missing or holds no skills: the CLI has not been built yet. */
 export declare class SkillSourceUnavailableError extends Error {
   override readonly name = "SkillSourceUnavailableError";
 }
-/**
- * Resolves a logical packaged skill-source root. When the package path is
- * unavailable, falls back to the executable directory: absolute and URL
- * sources by their basename, relative sources by the same relative path.
- */
-export declare function resolveSkillSource(source: string | URL): string;
 interface PackagedSkill {
   readonly sourceDir: string;
   readonly name: string;
   readonly description: string;
 }
-/** Reads every self-describing skill directory in a packaged skill source. */
-export declare function loadPackagedSkills(source: string | URL): readonly PackagedSkill[];
+/**
+ * Reads every self-describing skill directory under `root`, the absolute
+ * packaged skills directory (normally `resolveArtifactDir("skills")`).
+ */
+export declare function loadPackagedSkills(root: string): readonly PackagedSkill[];
 //#endregion
 export type { AgentClass, AgentResult, AgentTarget, InstallSkillOptions, InstallSkillResult, InstallStatus, PackagedSkill, Scope, SkillLinkStatus, SkillOptions, SkillStatusOptions, SkillStatusResult, UninstallSkillOptions, UninstallSkillResult, UninstallStatus, WriteSkillsOptions };

package/dist/index.js

@@ -1,6 +1,6 @@
 import { lstat, mkdir, readFile, readdir, readlink, realpath, rm, stat, symlink, unlink, writeFile } from "node:fs/promises";
 import { basename, delimiter, dirname, extname, isAbsolute, join, posix, relative, resolve, sep } from "node:path";
-import { accessSync, constants, existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { accessSync, constants, existsSync, readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { buildCommandDocumentation, formatDefault, sectionsFor } from "@crustjs/core/tooling";
 import { defineCommand, defineExtension, defineExtensionId } from "@crustjs/core";
@@ -41,7 +41,7 @@ function isWithin(parent, child) {
 * @returns The absolute path of the nearest enclosing directory containing
 *   `package.json`, or `null` if the filesystem root is reached first.
 *
-* @internal Used only by {@link resolveSourceDir}.
+* @internal Shared by {@link resolveSourceDir} and `resolveArtifactDir`.
 */
 function findNearestPackageRoot(startPath) {
 	let current = resolve(startPath);
@@ -230,12 +230,13 @@ async function loadBundleFiles(sourceDir) {
 	const collected = await collectBundleEntries(canonicalRoot, canonicalRoot, "", /* @__PURE__ */ new Set([canonicalRoot]));
 	const skillMd = collected.find((f) => f.relPath === SKILL_MD);
 	if (!skillMd) throw new Error(`Extra skill directory is missing SKILL.md at its root "${canonicalRoot}". Every extra skill directory must contain a top-level SKILL.md file.`);
+	const files = await Promise.all(collected.map(async (entry) => ({
+		path: entry.relPath,
+		content: await readFile(entry.absPath)
+	})));
 	return {
-		files: await Promise.all(collected.map(async (entry) => ({
-			path: entry.relPath,
-			content: await readFile(entry.absPath)
-		}))),
-		frontmatter: requireSkillFrontmatter(probeFrontmatter(await readFile(skillMd.absPath, "utf-8")), `Extra skill SKILL.md at "${join(canonicalRoot, SKILL_MD)}"`)
+		files,
+		frontmatter: requireSkillFrontmatter(probeFrontmatter(files[collected.indexOf(skillMd)].content.toString("utf-8")), `Extra skill SKILL.md at "${join(canonicalRoot, SKILL_MD)}"`)
 	};
 }
 //#endregion
@@ -258,6 +259,56 @@ var SkillConflictError = class extends Error {
 	}
 };
 //#endregion
+//#region ../utils/src/artifacts.ts
+/**
+* Set by `crust build` while it prepares the Command Snapshot: the absolute
+* entry-isolated directory Extension build hooks write into. Core reads it
+* to run the hooks; `resolveArtifactDir` reads it so sections evaluated during
+* that run see the artifacts being built instead of the wiped `.crust/root`.
+*/
+const BUILD_OUT_DIR_ENV = "CRUST_INTERNAL_BUILD_OUT_DIR";
+/** True inside a `bun build --compile` or `deno compile` executable. */
+function isCompiledExecutable() {
+	const { Bun, Deno } = globalThis;
+	const bunMain = Bun?.main ?? "";
+	return bunMain.startsWith("/$bunfs/") || /^[A-Za-z]:[\\/]~BUN[\\/]/.test(bunMain) || Deno?.build?.standalone === true;
+}
+/**
+* Absolute path of a build artifact or `crust.include` directory shipped with
+* this CLI. `name` is a top-level directory name such as `"skills"`.
+*
+* The artifact path is computed from how the CLI is running — never probed:
+* - Compiled executable (Bun or Deno): `<dir of the executable>/<name>`, which
+*   is a platform package's `bin/` or wherever the binary was placed.
+* - Crust-built Node bundle: `<name>` next to the bundle's `bin/` directory,
+*   i.e. `.crust/root/<name>` in place and `<installed root>/<name>` after install.
+* - Snapshot preparation inside `crust build`: `<build output dir>/<name>`, the
+*   artifacts earlier Extension build hooks wrote in this same build.
+* - Source (`bun run`, `node`, `deno run`): `.crust/root/<name>` under the
+*   nearest package root of the real `process.argv[1]` entrypoint (following source
+*   links) — the output of the last `crust build`.
+*
+* @throws {Error} when `name` is not a single path segment, or in source mode
+*   when the entrypoint cannot be resolved or has no enclosing `package.json`.
+*/
+function resolveArtifactDir(name) {
+	if (name === "" || name === "." || name === ".." || /[\\/]/.test(name)) throw new Error(`Artifact name must be a single directory name, got ${JSON.stringify(name)}.`);
+	if (isCompiledExecutable()) return join(dirname(process.execPath), name);
+	if (process.env.CRUST_INTERNAL_BUILD === "1") return resolve(fileURLToPath(import.meta.url), "..", "..", name);
+	const buildOutDir = process.env[BUILD_OUT_DIR_ENV];
+	if (buildOutDir) return join(buildOutDir, name);
+	const entrypoint = process.argv[1];
+	let sourceEntrypoint = entrypoint;
+	if (entrypoint) try {
+		sourceEntrypoint = realpathSync(entrypoint);
+	} catch (cause) {
+		throw new Error(`Could not resolve artifact "${name}": could not resolve source entrypoint "${entrypoint}".`, { cause });
+	}
+	const packageRoot = sourceEntrypoint ? findNearestPackageRoot(sourceEntrypoint) : null;
+	if (!packageRoot) throw new Error(`Could not resolve artifact "${name}": no package.json was found above ${entrypoint ? `entrypoint "${entrypoint}"` : "process.argv[1] (unset)"}.`);
+	return join(packageRoot, ".crust", "root", name);
+}
+//#endregion
 //#region ../utils/src/process.ts
 /** Resolve a bare executable name from PATH (and PATHEXT on Windows). */
 function which(command) {
@@ -567,6 +618,12 @@ function resolveAgentPath(agent, scope, name) {
 	return join(cfg.globalSkillsDir(homedir()), name);
 }
 //#endregion
+//#region ../utils/src/error.ts
+/** Narrows a caught Node.js system error to its stable errno contract. */
+function isErrnoException(error) {
+	return error instanceof Error && "code" in error && typeof error.code === "string";
+}
+//#endregion
 //#region src/link.ts
 /** Returns whether a symlink target carries Crust's skill ownership signature. */
 function isOwnedSkillLink(target, name) {
@@ -593,47 +650,11 @@ function isValidSkillName(name) {
 	return name.length >= 1 && name.length <= 64 && SKILL_NAME_PATTERN.test(name);
 }
 //#endregion
-//#region ../utils/src/error.ts
-/** Narrows a caught Node.js system error to its stable errno contract. */
-function isErrnoException(error) {
-	return error instanceof Error && "code" in error && typeof error.code === "string";
-}
-//#endregion
 //#region src/source.ts
+/** The packaged skills root is missing or holds no skills: the CLI has not been built yet. */
 var SkillSourceUnavailableError = class extends Error {
 	name = "SkillSourceUnavailableError";
 };
-function directoryPath(path) {
-	try {
-		return statSync(path).isDirectory() ? path : null;
-	} catch {
-		return null;
-	}
-}
-function fallbackName(source) {
-	if (source instanceof URL) return basename(fileURLToPath(source));
-	return isAbsolute(source) ? basename(source) : source;
-}
-/**
-* Resolves a logical packaged skill-source root. When the package path is
-* unavailable, falls back to the executable directory: absolute and URL
-* sources by their basename, relative sources by the same relative path.
-*/
-function resolveSkillSource(source) {
-	if (source instanceof URL && source.protocol !== "file:") throw new Error(`Skill source URL must use file: protocol, got "${source.protocol}".`);
-	let primary;
-	try {
-		primary = resolveSourceDir(source);
-	} catch {}
-	if (primary) {
-		const resolved = directoryPath(primary);
-		if (resolved) return resolved;
-	}
-	const fallback = join(dirname(process.execPath), fallbackName(source));
-	const resolvedFallback = directoryPath(fallback);
-	if (resolvedFallback) return resolvedFallback;
-	throw new SkillSourceUnavailableError(`Could not resolve skill source${primary ? ` at "${primary}"` : ""} or executable-relative fallback "${fallback}".`);
-}
 function readSkillFrontmatter(sourceDir) {
 	let content;
 	try {
@@ -644,11 +665,20 @@ function readSkillFrontmatter(sourceDir) {
 	}
 	return requireSkillFrontmatter(probeFrontmatter(content), `Skill source directory "${sourceDir}"`);
 }
-/** Reads every self-describing skill directory in a packaged skill source. */
-function loadPackagedSkills(source) {
-	const root = resolveSkillSource(source);
+/**
+* Reads every self-describing skill directory under `root`, the absolute
+* packaged skills directory (normally `resolveArtifactDir("skills")`).
+*/
+function loadPackagedSkills(root) {
+	let entries;
+	try {
+		entries = readdirSync(root, { withFileTypes: true });
+	} catch (error) {
+		if (!isErrnoException(error) || error.code !== "ENOENT" && error.code !== "ENOTDIR") throw error;
+		throw new SkillSourceUnavailableError(`Packaged skills not found at "${root}". Run \`crust build\` first.`, { cause: error });
+	}
 	const skills = [];
-	for (const entry of readdirSync(root, { withFileTypes: true })) {
+	for (const entry of entries) {
 		if (!entry.isDirectory()) continue;
 		const sourceDir = join(root, entry.name);
 		if (!existsSync(join(sourceDir, "SKILL.md"))) continue;
@@ -660,7 +690,7 @@ function loadPackagedSkills(source) {
 			description: frontmatter.description
 		});
 	}
-	if (skills.length === 0) throw new SkillSourceUnavailableError(`Skill source "${root}" does not contain any skill directories.`);
+	if (skills.length === 0) throw new SkillSourceUnavailableError(`Packaged skills at "${root}" do not contain any skill directories. Run \`crust build\` first.`);
 	return skills.sort((a, b) => a.name.localeCompare(b.name));
 }
 //#endregion
@@ -680,7 +710,8 @@ async function pathExists(path) {
 	try {
 		await stat(path);
 		return true;
-	} catch {
+	} catch (error) {
+		if (!isErrnoException(error) || error.code !== "ENOENT") throw error;
 		return false;
 	}
 }
@@ -688,7 +719,8 @@ async function inspectLink(outputDir, name, expectedSourceDir) {
 	let entry;
 	try {
 		entry = await lstat(outputDir);
-	} catch {
+	} catch (error) {
+		if (!isErrnoException(error) || error.code !== "ENOENT") throw error;
 		return { status: "absent" };
 	}
 	if (!entry.isSymbolicLink()) return { status: "conflict" };
@@ -760,7 +792,7 @@ async function uninstallSkill(options) {
 	}
 	return { agents: results };
 }
-/** Reports the ownership and health of each requested agent-directory entry. */
+/** Reports ownership and health. Only ENOENT is missing; other filesystem errors reject. */
 async function getSkillStatus(options) {
 	const agents = options.agents ?? [...ALL_AGENTS];
 	const scope = resolveEffectiveScope(options.scope ?? "global");
@@ -803,9 +835,10 @@ function planReconcile(options) {
 //#endregion
 //#region src/extension.ts
 const SKILLS = defineExtensionId("crust:skills");
-const DEFAULT_SKILL_COMMAND_NAME = "skill";
+const DEFAULT_SKILL_COMMAND_NAME = "skills";
 const SKILLS_SECTION_TITLE = "Agent skills";
 const DEFAULT_SKILL_SCOPE = "global";
+const SKILLS_ARTIFACT = "skills";
 async function resolveScope(rawScope, options) {
 	if (rawScope) return rawScope;
 	if (options.defaultScope) return options.defaultScope;
@@ -855,7 +888,7 @@ async function repairInstalledSkill(packagedSkill, scope, io, report = false) {
 async function autoRepairSkills(options, io) {
 	let skills;
 	try {
-		skills = loadPackagedSkills(options.distDir);
+		skills = loadPackagedSkills(resolveArtifactDir(SKILLS_ARTIFACT));
 	} catch (error) {
 		if (!(error instanceof SkillSourceUnavailableError)) io.stderr(yellow(`Skipping skill link repair: ${error instanceof Error ? error.message : String(error)}`));
 		return;
@@ -868,27 +901,28 @@ async function autoRepairSkills(options, io) {
 		io.stderr(yellow(`Skipping skill link repair [${packagedSkill.name}]: ${error instanceof Error ? error.message : String(error)}`));
 	}
 }
-function formatSkillDocumentation(source, commandName, appName) {
+function formatSkillDocumentation(commandName, appName) {
 	try {
-		return loadPackagedSkills(source).map((packagedSkill) => {
+		return loadPackagedSkills(resolveArtifactDir(SKILLS_ARTIFACT)).map((packagedSkill) => {
 			const sourcePath = isWithin(process.cwd(), packagedSkill.sourceDir) ? relative(process.cwd(), packagedSkill.sourceDir) || "." : packagedSkill.sourceDir;
 			return `${packagedSkill.name} — ${packagedSkill.description}\n  Source: ${sourcePath}`;
 		}).join("\n\n");
 	} catch (error) {
-		if (error instanceof SkillSourceUnavailableError) return `The packaged skills directory is unavailable. Run \`${appName} ${commandName}\` to link packaged skills into an agent directory.`;
+		if (error instanceof SkillSourceUnavailableError) return `${error.message} Then run \`${appName} ${commandName}\` to link packaged skills into an agent directory.`;
 		return `Packaged skills could not be read. Run \`${appName} ${commandName}\` for details.`;
 	}
 }
 async function buildSkills(options, context) {
-	const { writeSkills, writeSkillsFromSnapshot } = await Promise.resolve().then(() => build_exports);
-	const writeOptions = {
-		outDir: join(context.outDir, "skills"),
+	const { renderSkills } = await Promise.resolve().then(() => build_exports);
+	return (await renderSkills(options.generated === false ? void 0 : context.snapshot, {
 		version: context.snapshot.meta.version,
 		name: options.name,
 		description: options.description,
 		extras: options.extras
-	};
-	return (options.generated === false ? await writeSkills(writeOptions) : await writeSkillsFromSnapshot(context.snapshot, writeOptions)).map((file) => join("skills", file));
+	})).map((file) => ({
+		path: join(SKILLS_ARTIFACT, file.path),
+		content: file.content
+	}));
 }
 const skill = defineExtension(SKILLS, (options) => {
 	const commandName = options.command ?? DEFAULT_SKILL_COMMAND_NAME;
@@ -897,7 +931,7 @@ const skill = defineExtension(SKILLS, (options) => {
 		sections: (snapshot) => [{
 			command: [],
 			title: SKILLS_SECTION_TITLE,
-			body: formatSkillDocumentation(options.distDir, commandName, snapshot.meta.name),
+			body: formatSkillDocumentation(commandName, snapshot.meta.name),
 			except: [SKILLS]
 		}],
 		build: (context) => buildSkills(options, context),
@@ -1002,7 +1036,10 @@ async function reconcileSkill(opts) {
 	if (toInstall.length === 0 && toUninstall.length === 0) io.stdout(dim(`No changes [${packagedSkill.name}].`));
 }
 function buildSkillCommand(commandName, options) {
-	return defineCommand(commandName, { description: "Manage agent skill installations" }, (command) => command.flags({
+	return defineCommand(commandName, {
+		description: "Manage agent skill installations",
+		aliases: commandName === DEFAULT_SKILL_COMMAND_NAME ? ["skill"] : []
+	}, (command) => command.flags({
 		name: "scope",
 		type: "string",
 		choices: ["project", "global"],
@@ -1018,11 +1055,11 @@ function buildSkillCommand(commandName, options) {
 		description: "Update scope (project or global)"
 	}).action(async (context) => {
 		const scope = await resolveScope(context.flags.scope, options);
-		for (const packagedSkill of loadPackagedSkills(options.distDir)) await repairInstalledSkill(packagedSkill, scope, context, true);
+		for (const packagedSkill of loadPackagedSkills(resolveArtifactDir(SKILLS_ARTIFACT))) await repairInstalledSkill(packagedSkill, scope, context, true);
 	}))).action(async (context) => {
 		const installAll = context.flags.all === true;
 		const scope = installAll ? context.flags.scope ?? options.defaultScope ?? DEFAULT_SKILL_SCOPE : await resolveScope(context.flags.scope, options);
-		for (const packagedSkill of loadPackagedSkills(options.distDir)) await reconcileSkill({
+		for (const packagedSkill of loadPackagedSkills(resolveArtifactDir(SKILLS_ARTIFACT))) await reconcileSkill({
 			packagedSkill,
 			scope,
 			installAll,
@@ -1065,7 +1102,7 @@ function normalizeArg(arg) {
 		variadic: arg.variadic
 	};
 	if (arg.description !== void 0) result.description = arg.description;
-	if (arg.default !== void 0) result.default = serializeDefault(arg.default);
+	if (arg.default !== void 0) result.default = formatDefault(arg.default);
 	return result;
 }
 function normalizeFlag(flag) {
@@ -1077,15 +1114,12 @@ function normalizeFlag(flag) {
 		multiple: flag.multiple
 	};
 	if (flag.description !== void 0) result.description = flag.description;
-	if (flag.default !== void 0) result.default = serializeDefault(flag.default);
+	if (flag.default !== void 0) result.default = formatDefault(flag.default);
 	return result;
 }
 function manifestType(type) {
 	return type === "number" || type === "boolean" ? type : "string";
 }
-function serializeDefault(value) {
-	return formatDefault(value);
-}
 //#endregion
 //#region src/render.ts
 /**
@@ -1295,21 +1329,12 @@ function renderArgsTable(args) {
 	for (const arg of args) {
 		const name = arg.variadic ? `${arg.name}...` : arg.name;
 		const required = arg.required ? "Yes" : "No";
-		const desc = escapeTableCell(formatArgDescription(arg));
+		const desc = escapeTableCell(formatFieldDescription(arg));
 		lines.push(`| \`${name}\` | ${arg.type} | ${required} | ${desc} |`);
 	}
 	return lines;
 }
 /**
-* Formats the description cell for an argument, including default value.
-*/
-function formatArgDescription(arg) {
-	const parts = [];
-	if (arg.description) parts.push(arg.description);
-	if (arg.default !== void 0) parts.push(`Default: \`${arg.default}\``);
-	return parts.join(". ") || "-";
-}
-/**
 * Renders a markdown table for named flags.
 */
 function renderFlagsTable(flags) {
@@ -1319,20 +1344,16 @@ function renderFlagsTable(flags) {
 	for (const flag of flags) {
 		const name = flag.spellings.map((spelling) => `\`${spelling}\``).join(", ");
 		const required = flag.required ? "Yes" : "No";
-		const desc = escapeTableCell(formatFlagDescription(flag));
+		const desc = escapeTableCell(formatFieldDescription(flag));
 		lines.push(`| ${name} | ${flag.type} | ${required} | ${desc} |`);
 	}
 	return lines;
 }
-/**
-* Formats the description cell for a flag, including default value
-* and multiplicity.
-*/
-function formatFlagDescription(flag) {
+function formatFieldDescription(field) {
 	const parts = [];
-	if (flag.description) parts.push(flag.description);
-	if (flag.multiple) parts.push("Can be specified multiple times");
-	if (flag.default !== void 0) parts.push(`Default: \`${flag.default}\``);
+	if (field.description) parts.push(field.description);
+	if ("multiple" in field && field.multiple) parts.push("Can be specified multiple times");
+	if (field.default !== void 0) parts.push(`Default: \`${field.default}\``);
 	return parts.join(". ") || "-";
 }
 /**
@@ -1370,6 +1391,7 @@ function findNode(root, path) {
 //#endregion
 //#region src/build.ts
 var build_exports = /* @__PURE__ */ __exportAll({
+	renderSkills: () => renderSkills,
 	writeSkills: () => writeSkills,
 	writeSkillsFromSnapshot: () => writeSkillsFromSnapshot
 });
@@ -1384,18 +1406,37 @@ async function writeSkillsFromSnapshot(snapshot, options) {
 	return await writeSkillSource(snapshot, options);
 }
 async function writeSkillSource(snapshot, options) {
-	if (snapshot === void 0 && (options.extras?.length ?? 0) === 0) throw new Error("Nothing to write: provide an app or at least one extra skill directory.");
 	const outDir = resolve(options.outDir);
 	if (basename(outDir) !== "skills") throw new Error(`Skill source outDir "${outDir}" must be named "skills".`);
-	const skills = /* @__PURE__ */ new Map();
-	const authoredNames = /* @__PURE__ */ new Set();
 	for (const sourceDir of options.extras ?? []) {
 		const resolved = resolveSourceDir(sourceDir);
 		if (isWithin(outDir, resolved)) throw new Error(`Extra skill directory "${resolved}" is inside outDir "${outDir}", which is replaced on every build. Move authored skills outside the build output.`);
+	}
+	const files = await renderSkills(snapshot, options);
+	const cwd = resolve(".");
+	if (outDir === dirname(outDir) || isWithin(outDir, cwd)) throw new Error(`Refusing to replace "${outDir}": outDir must be a dedicated directory, not the filesystem root, the working directory, or an ancestor of it.`);
+	await rm(outDir, {
+		recursive: true,
+		force: true
+	});
+	for (const file of files) {
+		const filePath = join(outDir, file.path);
+		await mkdir(dirname(filePath), { recursive: true });
+		await writeFile(filePath, file.content);
+	}
+	return files.map((file) => file.path);
+}
+/**
+* Renders generated and authored skills as `<skill>/<file>` paths relative to a
+* `skills` directory, without writing them.
+*/
+async function renderSkills(snapshot, options) {
+	if (snapshot === void 0 && (options.extras?.length ?? 0) === 0) throw new Error("Nothing to write: provide an app or at least one extra skill directory.");
+	const skills = /* @__PURE__ */ new Map();
+	for (const sourceDir of options.extras ?? []) {
 		const bundle = await loadBundleFiles(sourceDir);
 		validateSkillName(bundle.frontmatter.name);
-		if (authoredNames.has(bundle.frontmatter.name)) throw new SkillSourceConflictError(bundle.frontmatter.name);
-		authoredNames.add(bundle.frontmatter.name);
+		if (skills.has(bundle.frontmatter.name)) throw new SkillSourceConflictError(bundle.frontmatter.name);
 		skills.set(bundle.frontmatter.name, bundle.files);
 	}
 	if (snapshot) {
@@ -1404,32 +1445,19 @@ async function writeSkillSource(snapshot, options) {
 			description: options.description ?? snapshot.meta.description ?? "",
 			version: options.version
 		};
-		if (!authoredNames.has(generatedMeta.name)) {
+		if (!skills.has(generatedMeta.name)) {
 			validateSkillName(generatedMeta.name);
 			requireSkillFrontmatter(generatedMeta, `Skill "${generatedMeta.name}"`);
 			skills.set(generatedMeta.name, renderSkill(buildManifest(snapshot), generatedMeta));
 		}
 	}
-	const cwd = resolve(".");
-	if (outDir === dirname(outDir) || isWithin(outDir, cwd)) throw new Error(`Refusing to replace "${outDir}": outDir must be a dedicated directory, not the filesystem root, the working directory, or an ancestor of it.`);
-	await rm(outDir, {
-		recursive: true,
-		force: true
-	});
-	const written = [];
-	for (const [name, files] of skills) written.push(...(await writeFiles(join(outDir, name), files)).map((path) => join(name, path)));
-	return written;
+	return [...skills].flatMap(([name, files]) => files.map((file) => ({
+		path: join(name, file.path),
+		content: file.content
+	})));
 }
 function validateSkillName(name) {
 	if (!isValidSkillName(name)) throw new Error(`Invalid skill name "${name}": must be 1–64 lowercase alphanumeric characters and hyphens, no leading/trailing/consecutive hyphens.`);
 }
-async function writeFiles(baseDir, files) {
-	for (const file of files) {
-		const filePath = join(baseDir, file.path);
-		await mkdir(dirname(filePath), { recursive: true });
-		await writeFile(filePath, file.content);
-	}
-	return files.map((file) => file.path);
-}
 //#endregion
-export { SkillConflictError, SkillSourceConflictError, SkillSourceUnavailableError, detectInstalledAgents, getAdditionalAgents, getSkillStatus, getUniversalAgents, installSkill, isUniversalAgent, isValidSkillName, loadPackagedSkills, resolveSkillSource, skill, uninstallSkill, writeSkills, writeSkillsFromSnapshot };
+export { SkillConflictError, SkillSourceConflictError, SkillSourceUnavailableError, detectInstalledAgents, getAdditionalAgents, getSkillStatus, getUniversalAgents, installSkill, isUniversalAgent, isValidSkillName, loadPackagedSkills, skill, uninstallSkill, writeSkills, writeSkillsFromSnapshot };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@crustjs/skills",
-	"version": "0.2.1",
+	"version": "0.3.1",
 	"description": "Package and install agent skills for AI coding assistants.",
 	"type": "module",
 	"sideEffects": false,
@@ -46,19 +46,19 @@
 	},
 	"dependencies": {
 		"@crustjs/progress": "^0.1.1",
-		"@crustjs/prompts": "^0.2.1",
-		"@crustjs/style": "^0.3.1"
+		"@crustjs/prompts": "^0.2.2",
+		"@crustjs/style": "^0.3.3"
 	},
 	"devDependencies": {
 		"@crustjs/config": "0.0.0",
-		"@crustjs/core": "0.2.1",
-		"@crustjs/extensions": "0.2.1",
-		"@crustjs/testing": "0.1.1",
+		"@crustjs/core": "0.3.1",
+		"@crustjs/extensions": "0.3.1",
+		"@crustjs/testing": "0.1.2",
 		"@crustjs/utils": "0.0.0",
 		"tsdown": "^0.23.0"
 	},
 	"peerDependencies": {
-		"@crustjs/core": "^0.2.1",
+		"@crustjs/core": "^0.3.1",
 		"typescript": "^7.0.0"
 	},
 	"peerDependenciesMeta": {