@crustjs/skills 0.1.2 → 0.2.1

package/README.md

@@ -1,8 +1,6 @@
 # @crustjs/skills
 
-Generate distributable AI agent skills from [Crust](https://crustjs.com) command definitions.
-
-Instead of hand-maintaining skill files for AI coding agents, generate them from your Crust command metadata. The output is a portable skill bundle that developers can download and install into their own agent environments (OpenCode, Claude Code, etc.).
+Package and install agent skills for AI coding assistants.
 
 ## Install
 
@@ -10,678 +8,6 @@ Instead of hand-maintaining skill files for AI coding agents, generate them from
 bun add @crustjs/skills
 ```
 
-## Quick Start
-
-### CLI (via `@crustjs/crust`)
-
-```sh
-crust skills generate ./src/cli.ts --name my-cli --description "My CLI tool"
-```
-
-### Programmatic API
-
-```ts
-import { generateSkill } from "@crustjs/skills";
-import { rootCommand } from "./commands.ts";
-
-const result = await generateSkill({
-	command: rootCommand,
-	meta: {
-		name: "my-cli",
-		description: "CLI tool for managing widgets",
-		version: "1.0.0",
-	},
-	agents: ["opencode", "claude-code"],
-});
-
-for (const agent of result.agents) {
-	console.log(`${agent.agent}: ${agent.status} -> ${agent.outputDir}`);
-}
-```
-
-### Runtime Plugin (`autoUpdate`)
-
-Register `skillPlugin()` on your `Crust` builder with `.use()`:
-
-```ts
-import { Crust } from "@crustjs/core";
-import { skillPlugin } from "@crustjs/skills";
-
-const app = new Crust("my-cli")
-	.meta({ description: "My CLI" })
-	.use(
-		skillPlugin({
-			version: "1.0.0",
-			instructions: `
-Prefer readonly commands before mutating project state.
-
-## Response Policy
-
-- Read the relevant command doc before suggesting flags.
-`,
-			// autoUpdate: true (default) — silently updates installed skills
-			// command: "skill" (default) — registers "my-cli skill" subcommand
-			// defaultScope: "global" | "project" — skip scope prompt when set
-			// installMode: "auto" | "symlink" | "copy" (default: "auto")
-		}),
-	)
-	.run(() => {
-		console.log("hello");
-	});
-
-await app.execute();
-```
-
-The plugin automatically updates already-installed skills when the version changes, checking both project and global paths for the current working directory. If the current working directory is the home directory, `project` scope is normalized to `global` so installs, updates, and status checks use the global skill locations. First-time installation is done via the interactive `skill` subcommand (or `skill update` for update-only flows), or programmatically using the exported primitives.
-
-Generated bundles are written once to a canonical store (`.crust/skills` for project scope, `~/.crust/skills` for global scope) and then installed into agent paths via symlink or copy depending on `installMode`.
-
-#### Hand-authored bundles via `customSkills`
-
-The plugin can also manage **hand-authored** skill bundles alongside the
-auto-generated command-reference skill. Pass an array of
-`CustomSkillConfig` entries via `customSkills`; each entry is reconciled
-through the same lifecycle as the main skill.
-
-```ts
-import { Crust } from "@crustjs/core";
-import { skillPlugin } from "@crustjs/skills";
-import pkg from "./package.json" with { type: "json" };
-
-const app = new Crust("my-cli")
-	.meta({ description: "My CLI" })
-	.use(
-		skillPlugin({
-			version: pkg.version,
-			customSkills: [
-				// Inherits `version: pkg.version` from the plugin — the typical
-				// case when the bundle ships in the same package as the CLI.
-				{
-					name: "funnel-builder",
-					// Resolved against the nearest package.json walking up from
-					// process.argv[1] — same rules as installSkillBundle().
-					sourceDir: "skills/funnel-builder",
-				},
-				// Explicit override for an independently-versioned bundle.
-				{
-					name: "vendored-toolkit",
-					sourceDir: "skills/vendored-toolkit",
-					version: "0.3.0",
-				},
-			],
-		}),
-	)
-	.run(() => {});
-
-await app.execute();
-```
-
-- **`name`** must satisfy `isValidSkillName` (1–64 lowercase alphanumeric
-  characters and hyphens, no leading/trailing/consecutive hyphens), must
-  be unique within the array, and must not collide with the main skill's
-  name. The bundle's `SKILL.md` frontmatter must declare a matching
-  `name:` field — mismatches are rejected at install time.
-- **`sourceDir`** accepts a `URL` (`file:` protocol), an absolute path, or
-  a relative string resolved from the nearest `package.json`. Resolution
-  errors surface at install time, not at plugin setup.
-- **`version`** is optional. When omitted, the bundle inherits the
-  plugin's top-level `version` — the typical case when the bundle ships
-  alongside the CLI. Pass an explicit value when the bundle's release
-  cadence is independent of the consuming CLI (for example, vendored
-  from another package). Identical-version reinstalls are skipped, so
-  bump the effective version whenever bundle contents change. The
-  bundle's `SKILL.md` frontmatter `version:` / `metadata.version`, if
-  any, is intentionally ignored — see the [`installSkillBundle()` note](#installing-hand-authored-bundles).
-- **`scope`** and **`installMode`** are optional per-entry overrides;
-  unset values inherit from the plugin's `defaultScope` / `installMode`.
-
-The interactive `skill` command shows one multiselect prompt per skill in
-order: the main auto-generated skill first, then each `customSkills`
-entry with its name in the prompt header (e.g. `"Select agents to install
-skills for [funnel-builder]"`). Each prompt is independent — selecting
-or deselecting agents reconciles only that skill's installs. `skill
---all` skips every prompt and installs every skill for the full agent
-set; `skill update` updates outdated installs across main + every bundle.
-
-Auto-update on plugin startup is per-skill: only outdated installs are
-rewritten, and a single bundle's failure (e.g. missing `sourceDir`) does
-not abort the others. Pass `autoUpdate: false` to disable startup auto-
-update for both the main skill and all bundles.
-
-### Programmatic Auto-Install
-
-For full control over first-time installation, call `generateSkill()`
-directly from your handler. With `agents` omitted, it installs into every
-universal agent plus every additional agent whose CLI is on `PATH`, and
-returns `up-to-date` for targets that already match the current version —
-so the same call is safe to run on every invocation. Pass `agents: []` to
-opt out, or an explicit array to scope the install.
-
-```ts
-import { Crust } from "@crustjs/core";
-import { generateSkill } from "@crustjs/skills";
-
-export const app = new Crust("my-cli").meta({ description: "My CLI" }).run(async (ctx) => {
-	// Defaults to universal + agents detected on PATH. Idempotent: targets
-	// that already match the current version are returned as `up-to-date`.
-	const result = await generateSkill({
-		command: ctx.command,
-		meta: {
-			name: ctx.command.meta.name,
-			description: ctx.command.meta.description ?? "",
-			version: "1.0.0",
-		},
-		scope: "global",
-	});
-
-	const changed = result.agents.filter((a) => a.status !== "up-to-date");
-	if (changed.length > 0) {
-		console.log(`Installed or updated skills for ${changed.length} target(s).`);
-	}
-});
-
-if (import.meta.main) {
-	await app.execute();
-}
-```
-
-`getUniversalAgents()`, `getAdditionalAgents()`, and
-`detectInstalledAgents()` remain exported for callers that want to compose
-their own agent list.
-
-#### Troubleshooting
-
-If auto-update does not appear to work:
-
-- Ensure `skillPlugin(...)` is registered on the `Crust` builder via `.use()`.
-- Ensure at least one supported agent is detected. Auto-update checks both project and global install paths, with home-directory `project` scope treated as `global`.
-- Check for existing conflicting skill directories without `crust.json`.
-
-## Recommended Export Pattern
-
-To avoid side effects when your command module is imported for generation, guard runtime code with `import.meta.main`:
-
-```ts
-import { Crust } from "@crustjs/core";
-
-// Export the command — used by skill generation.
-export const rootCommand = new Crust("my-cli")
-	.meta({ description: "My CLI tool" })
-	.run(({ args }) => {
-		console.log("Hello from my-cli!");
-	});
-
-// Only execute when run directly — not when imported for generation.
-if (import.meta.main) {
-	await rootCommand.execute();
-}
-```
-
-### Custom Instructions
-
-Use plugin-level `instructions` to add top-level guidance to the generated
-`SKILL.md`, and `annotate()` to add prompt guidance to specific
-command docs under `commands/`.
-
-- `instructions: string` renders as a raw markdown block.
-- `instructions: string[]` renders as bullet list items.
-- Empty or whitespace-only instruction input is ignored.
-- `annotate()` always renders command guidance as bullets.
-
-```ts
-import { Crust } from "@crustjs/core";
-import { annotate, skillPlugin } from "@crustjs/skills";
-
-const deploy = annotate(
-	new Crust("deploy")
-		.meta({ description: "Deploy the application" })
-		.flags({
-			"dry-run": { type: "boolean", description: "Preview changes only" },
-		})
-		.run(() => {
-			// ...
-		}),
-	[
-		"Prefer `--dry-run` before executing deployment changes.",
-		"Ask for confirmation before production deployments.",
-	],
-);
-
-const app = new Crust("my-cli")
-	.meta({ description: "My CLI" })
-	.use(
-		skillPlugin({
-			version: "1.0.0",
-			instructions: `
-Read command docs before suggesting exact flags.
-
-## Answer Style
-
-- Prefer exact syntax copied from the relevant command file.
-`,
-		}),
-	)
-	.command(deploy);
-```
-
-This pattern lets `crust skills generate` import the command definition without triggering `app.execute()`.
-
-## CLI Usage
-
-The `crust skills generate` command is provided by `@crustjs/crust`:
-
-```sh
-crust skills generate <module> [options]
-```
-
-### Arguments
-
-| Argument | Description                                      |
-| -------- | ------------------------------------------------ |
-| `module` | Path to the command module (e.g. `./src/cli.ts`) |
-
-### Flags
-
-| Flag            | Alias | Required | Default   | Description                                    |
-| --------------- | ----- | -------- | --------- | ---------------------------------------------- |
-| `--name`        | `-n`  | Yes      | -         | Skill name (used as directory name)            |
-| `--description` | `-d`  | Yes      | -         | Human-readable description                     |
-| `--version`     | `-V`  | No       | -         | Version string                                 |
-| `--out-dir`     | `-o`  | No       | `.`       | Output directory                               |
-| `--clean`       | -     | No       | `true`    | Remove existing skill directory before writing |
-| `--export`      | `-e`  | No       | `default` | Named export to use from the module            |
-
-### Examples
-
-```sh
-# Basic generation
-crust skills generate ./src/cli.ts --name my-cli --description "My CLI"
-
-# With version and custom output directory
-crust skills generate ./src/cli.ts -n my-cli -d "My CLI" --version 1.0.0 -o ./dist
-
-# Using a named export instead of the default export
-crust skills generate ./src/cli.ts -n my-cli -d "My CLI" --export rootCommand
-
-# Keep existing files (no clean)
-crust skills generate ./src/cli.ts -n my-cli -d "My CLI" --no-clean
-```
-
-## Programmatic API
-
-### `generateSkill(options)`
-
-High-level API that runs the full pipeline: introspection, rendering, and writing to disk.
-
-The `meta.name` must be a valid skill name — lowercase alphanumeric with hyphens, 1–64 characters (validated against the [Agent Skills spec](https://agentskills.io/specification) pattern). Use `isValidSkillName()` to check before calling.
-
-```ts
-import { generateSkill } from "@crustjs/skills";
-
-const result = await generateSkill({
-	command: rootCommand,
-	meta: {
-		name: "my-cli",
-		description: "My CLI tool",
-		version: "1.0.0",
-		instructions: ["Prefer readonly commands before making changes."],
-	},
-	agents: ["opencode"],
-	scope: "project", // default: "global"
-	installMode: "auto", // default: "auto" — symlink first, fallback to copy
-	clean: true, // default: true — removes existing skill dir first
-	force: false, // default: false — set true to rewrite same-version output or overwrite conflicts
-});
-
-// result.agents — per-agent install results
-```
-
-### `buildManifest(command)`
-
-Introspects a command tree and produces a canonical, serializable manifest.
-
-```ts
-import { buildManifest } from "@crustjs/skills";
-
-const manifest = buildManifest(rootCommand);
-// manifest.name, manifest.path, manifest.args, manifest.flags, manifest.children
-```
-
-### `renderSkill(manifest, meta)`
-
-Renders markdown files from a manifest tree without writing to disk.
-
-```ts
-import { buildManifest, renderSkill } from "@crustjs/skills";
-
-const manifest = buildManifest(rootCommand);
-const files = renderSkill(manifest, { name: "my-cli", description: "My CLI" });
-
-for (const file of files) {
-	console.log(file.path); // e.g. "SKILL.md", "commands/serve.md"
-	console.log(file.content); // markdown content
-}
-```
-
-### `resolveCanonicalSkillPath(scope, name)`
-
-Resolves the canonical store path where Crust writes the single source-of-truth skill bundle. Agent install paths are symlinked (or copied) from this location.
-
-```ts
-import { resolveCanonicalSkillPath } from "@crustjs/skills";
-
-resolveCanonicalSkillPath("project", "my-cli");
-// → "<cwd>/.crust/skills/my-cli"
-
-resolveCanonicalSkillPath("global", "my-cli");
-// → "~/.crust/skills/my-cli"
-```
-
-When `process.cwd()` is the home directory, `resolveCanonicalSkillPath("project", ...)` returns the same global path as `resolveCanonicalSkillPath("global", ...)`.
-
-### `isValidSkillName(name)`
-
-Validates a skill name against the [Agent Skills spec](https://agentskills.io/specification) pattern: 1–64 lowercase alphanumeric characters and hyphens, no leading/trailing/consecutive hyphens.
-
-```ts
-import { isValidSkillName } from "@crustjs/skills";
-
-isValidSkillName("my-cli"); // true
-isValidSkillName("My_CLI"); // false — uppercase and underscores not allowed
-isValidSkillName("-leading"); // false — leading hyphen
-isValidSkillName("a".repeat(65)); // false — exceeds 64 characters
-```
-
-> **Note:** `generateSkill()` automatically validates `meta.name` and throws a descriptive error if the name is invalid.
-
-## Skill Metadata
-
-The `SkillMeta` object controls the generated `SKILL.md` frontmatter. Beyond the required `name`, `description`, and `version` fields, several optional fields are supported:
-
-```ts
-const meta: SkillMeta = {
-	name: "my-cli",
-	description: "CLI tool for managing widgets",
-	version: "1.0.0",
-
-	// Optional fields — emitted in SKILL.md YAML frontmatter when set
-	allowedTools: "Bash(my-cli *) Read Grep", // Pre-approved tools (avoids per-use prompts)
-	license: "MIT", // License name or reference
-	compatibility: "Requires my-cli on PATH", // Environment requirements (max 500 chars)
-	disableModelInvocation: false, // true = agent won't auto-load; user must invoke manually
-};
-```
-
-| Field                    | Frontmatter Key            | Description                                                                  |
-| ------------------------ | -------------------------- | ---------------------------------------------------------------------------- |
-| `allowedTools`           | `allowed-tools`            | Space-delimited list of pre-approved tools (e.g. `Bash(my-cli *) Read Grep`) |
-| `license`                | `license`                  | License name or file reference                                               |
-| `compatibility`          | `compatibility`            | Environment requirements or compatibility notes                              |
-| `disableModelInvocation` | `disable-model-invocation` | When `true`, prevents agents from auto-loading the skill                     |
-
-## Escaping
-
-The renderer automatically handles special characters in generated output:
-
-- **YAML frontmatter**: Values containing YAML-special characters (`:`, `#`, `*`, `!`, `[`, `{`, `'`, `"`, etc.) are wrapped in double quotes with internal quotes escaped.
-- **Markdown tables**: Literal `|` characters in argument/flag descriptions are escaped as `\|` to prevent broken table rendering.
-
-No manual escaping is needed — pass raw values and the renderer handles the rest.
-
-## Output Structure
-
-Generated output goes to `<outDir>/skills/<name>/`:
-
-```
-skills/my-cli/
-  SKILL.md            # Entrypoint — loaded by the agent
-  commands/           # Per-command documentation mirroring the CLI hierarchy
-    my-cli.md         # Root command
-    serve.md          # Subcommand
-    db/
-      migrate.md      # Nested subcommand
-      seed.md
-  crust.json          # Machine-readable bundle metadata (Crust ownership marker)
-```
-
-### File Details
-
-| File            | Purpose                                                                                                                                                     |
-| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `SKILL.md`      | Agent entrypoint with YAML frontmatter and an embedded command reference table listing every command path, type (runnable/group), and documentation link.   |
-| `commands/*.md` | Per-command reference files. Leaf commands include usage, arguments, flags, defaults, and aliases. Group commands list subcommands with links.              |
-| `crust.json`    | Crust-specific JSON metadata: name, description, and version. Also serves as an ownership marker — its presence indicates the skill was generated by Crust. |
-
-## Conflict Detection
-
-Each Crust-managed skill directory contains a `crust.json` file that acts
-as an ownership marker. Both `generateSkill()` and `installSkillBundle()`
-refuse to overwrite a target directory in three cases:
-
-1. **No `crust.json`** — the directory exists but was not created by Crust
-   (e.g. manually authored or installed by another tool).
-2. **Kind mismatch** — `crust.json` records a different
-   [`kind`](#kind-field-on-crustjson) than the install attempt (e.g. an
-   existing `generated` skill collides with an incoming `bundle`).
-3. **Malformed manifest** — `crust.json` is present but cannot be
-   interpreted (invalid JSON, top-level non-object, missing `version`, or
-   an unrecognized `kind` value such as a hand-edit typo).
-
-All three throw `SkillConflictError`. Pass `force: true` to overwrite, or
-uninstall the existing skill first.
-
-`SkillConflictError.details` carries optional discriminators:
-
-- `details.kindMismatch?: { existing, attempted }` — set on kind mismatch.
-- `details.manifestMalformed?: { reason, rawKind? }` — set on malformed
-  `crust.json`. `reason` is one of `"parse-error"`, `"not-an-object"`,
-  `"missing-version"`, or `"unknown-kind"`. `rawKind` is populated only
-  when `reason === "unknown-kind"`.
-- Neither field set — the original "directory exists with no `crust.json`" case.
-
-```ts
-import { generateSkill, SkillConflictError } from "@crustjs/skills";
-
-try {
-	await generateSkill({ command, meta, agents });
-} catch (err) {
-	if (!(err instanceof SkillConflictError)) throw err;
-
-	if (err.details.kindMismatch) {
-		const { existing, attempted } = err.details.kindMismatch;
-		console.error(
-			`Cannot install ${attempted} skill at ${err.details.outputDir} — ` +
-				`existing skill was installed as ${existing}.`,
-		);
-	} else if (err.details.manifestMalformed) {
-		console.error(
-			`crust.json at ${err.details.outputDir} is malformed: ` +
-				`${err.details.manifestMalformed.reason}.`,
-		);
-	} else {
-		console.error(`${err.details.outputDir} exists but was not created by Crust.`);
-	}
-}
-```
-
-### Uninstall Cleanup
-
-When `uninstallSkill()` removes agent install paths, it also checks whether any other agent paths still reference the skill. If no agent installs remain, the canonical store entry (`.crust/skills/<skill>` or `~/.crust/skills/<skill>`) is automatically removed.
-
-## Installing Generated Skills
-
-After generating a skill bundle, consumers can install it by copying the skill directory.
-
-### Universal agents (OpenCode, Codex, Cursor, and others)
-
-```sh
-cp -r skills/my-cli/ .agents/skills/my-cli/
-```
-
-Global install for universal agents:
-
-```sh
-cp -r skills/my-cli/ ~/.agents/skills/my-cli/
-```
-
-### Claude Code
-
-```sh
-cp -r skills/my-cli/ .claude/skills/my-cli/
-```
-
-The agent will discover the skill from `SKILL.md` and load command documentation on demand from the `commands/` directory.
-
-## Installing Hand-Authored Bundles
-
-`generateSkill()` produces a skill bundle from a Crust command tree.
-`installSkillBundle()` is the dual entrypoint for **hand-authored** bundles —
-use it when you have a directory containing `SKILL.md` and any supporting
-files that you want to install through the same canonical-store + agent
-fan-out pipeline.
-
-Use `installSkillBundle()` when:
-
-- You ship a published CLI package that bundles authored skill directories
-  alongside generated ones.
-- The skill's `SKILL.md` is hand-curated (or produced by your own renderer)
-  and Crust just needs to handle install plumbing — canonical storage,
-  symlink/copy fan-out, version tracking, and conflict detection.
-
-```ts
-import { installSkillBundle } from "@crustjs/skills";
-import pkg from "./package.json" with { type: "json" };
-
-await installSkillBundle({
-	// Resolved relative to the nearest package.json walking up from
-	// process.argv[1]. You can also pass an absolute string or a file: URL.
-	sourceDir: "skills/funnel-builder",
-	agents: ["claude-code", "opencode"],
-	version: pkg.version,
-});
-```
-
-### Where `name`, `description`, and `version` come from
-
-The bundle's `SKILL.md` frontmatter is the source of truth for `name` and
-`description` — Crust reads them but never rewrites the file. Both fields
-are required:
-
-```yaml
----
-name: funnel-builder
-description: Build a sales funnel
----
-```
-
-`version` is supplied by the caller and recorded in `crust.json`. Wiring
-it to the consuming package's `package.json` `version` (as in the example
-above) is the typical pattern; pass any string explicitly when one package
-publishes multiple bundles with independent versions:
-
-```ts
-await installSkillBundle({
-	sourceDir: "skills/funnel-builder",
-	agents: ["claude-code"],
-	version: "2.0.0",
-});
-```
-
-> **Note:** `metadata.version` declared inside the bundle's SKILL.md
-> frontmatter is **not** read — the `version` option is the sole source of
-> truth for `crust.json` and update detection. If you keep a
-> `metadata.version` in your SKILL.md for Agent Skills spec compliance,
-> keep it in sync with the value you pass here.
-
-### Options
-
-| Option        | Type                            | Default    | Description                                                                                                         |
-| ------------- | ------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------- |
-| `sourceDir`   | `string \| URL`                 | — required | Bundle directory. Absolute path, `file:` URL, or relative path resolved from the nearest `package.json`.            |
-| `agents`      | `AgentTarget[]`                 | — required | Agents to install for. `[]` validates the bundle without installing (no auto-detection — unlike `generateSkill()`). |
-| `version`     | `string`                        | — required | Recorded in `crust.json` and compared on subsequent installs.                                                       |
-| `scope`       | `"global" \| "project"`         | `"global"` | Install scope. When `process.cwd()` is the home directory, `"project"` normalizes to `"global"`.                    |
-| `installMode` | `"auto" \| "symlink" \| "copy"` | `"auto"`   | Same semantics as `generateSkill()`. `"auto"` symlinks from the canonical store, falling back to copy.              |
-| `clean`       | `boolean`                       | `true`     | Remove the existing skill directory before writing.                                                                 |
-| `force`       | `boolean`                       | `false`    | Rewrite even when the recorded version is unchanged, and overwrite a conflicting directory instead of throwing.     |
-
-### What gets copied
-
-The bundle's `SKILL.md` plus every supporting file is copied into the
-canonical Crust store — markdown, configs, scripts, images, fonts, and other
-assets. Bundle files are copied as raw bytes; `SKILL.md` is also parsed as
-UTF-8 to read its required frontmatter.
-
-Bundle content changes do not propagate without a `version` bump:
-identical-version reinstalls report `up-to-date` and leave the canonical
-store untouched, unless `force: true` is passed. Pass a fresh `version`
-(typically wired to the consuming package's `package.json` `version`)
-whenever the bundle contents change.
-
-Bundle contents are copied as authored — no implicit name-based filtering.
-Dotfiles, `node_modules/`, `.DS_Store`, and editor cruft are all copied if
-present. Keep `sourceDir` clean. The only reserved filename is
-`crust.json` at the bundle root (Crust generates this and rejects bundles
-that ship one).
-
-### Publishing a bundle to npm
-
-Two gotchas trip up bundle authors who publish to npm:
-
-1. **Include the bundle directory in the published tarball.** Add the path
-   to your `package.json` `files` array and verify with `npm pack --dry-run`
-   before publishing. Local installs work even when the directory would be
-   excluded from the tarball, but consumers will hit a missing-`SKILL.md`
-   error.
-
-   ```json
-   {
-   	"name": "acme-skills",
-   	"version": "1.0.0",
-   	"files": ["dist", "skills"]
-   }
-   ```
-
-2. **Consumers point at the published path with `import.meta.resolve`.**
-   Relative `sourceDir` resolution walks up from the consumer's
-   `process.argv[1]`, so it lands in the consumer's package — not yours.
-   Consumers should use a `file:` URL via `import.meta.resolve`:
-
-   ```ts
-   import skillsPkg from "acme-skills/package.json" with { type: "json" };
-
-   await installSkillBundle({
-   	sourceDir: new URL(import.meta.resolve("acme-skills/skills/funnel-builder")),
-   	agents: ["claude-code"],
-   	version: skillsPkg.version,
-   });
-   ```
-
-   For this to work, the bundle directory must be reachable from your
-   package's `exports` (or accessible as a subpath of the package root).
-   Bundle authors who want explicit subpath access can declare it in
-   `package.json` `exports`.
-
-### `kind` field on `crust.json`
-
-Every installed bundle records its origin in `crust.json` as a `kind`
-field: `"generated"` for `generateSkill()` output, `"bundle"` for
-`installSkillBundle()`. This prevents accidental cross-overwrites:
-
-- Trying to install a bundle on top of a generated skill (or vice versa) at
-  the same name throws a `SkillConflictError` whose `details.kindMismatch`
-  carries `{ existing, attempted }`.
-- To proceed anyway, uninstall the existing skill first or pass
-  `force: true`.
-
-Legacy `crust.json` files written before this field existed are read as
-`kind: "generated"` for backward compatibility — generated installs continue
-to update cleanly with no migration step.
-
 ## Documentation
 
-See the full docs at [crustjs.com](https://crustjs.com).
-
-## License
-
-MIT
+Full docs: [crustjs.com/docs/modules/skills](https://crustjs.com/docs/modules/skills)