skanvil 1.0.0 → 1.1.0

package/dist/cli.js

@@ -5,6 +5,7 @@ import {
   RULES,
   TARGET_PRESETS,
   addCommand,
+  buildLibrary,
   collectSkills,
   createLibrary,
   displayPath,
@@ -20,6 +21,7 @@ import {
   listCommand,
   openLibrary,
   packageVersion,
+  parseParamPairs,
   printValidation,
   rebuildIndex,
   removeSkill,
@@ -31,7 +33,7 @@ import {
   toKebabCase,
   toTitleCase,
   validateLibrary
-} from "./chunk-TYO4LLN5.js";
+} from "./chunk-WXEWECJP.js";
 
 // src/cli.ts
 import { Command, Option } from "commander";
@@ -170,7 +172,8 @@ async function syncCommand(dest, options) {
     force: options.force,
     categories: splitList(options.category),
     skills: splitList(options.skill),
-    scope: options.global ? "user" : "project"
+    scope: options.global ? "user" : "project",
+    params: options.param?.length ? parseParamPairs(options.param) : void 0
   });
   if (options.json) {
     console.log(JSON.stringify({ dryRun: Boolean(options.dryRun), mode, results }, null, 2));
@@ -188,6 +191,21 @@ async function syncCommand(dest, options) {
   }
   return 0;
 }
+async function buildCommand(options) {
+  const library = await openLibrary(options);
+  const out = new Output("build", options.json);
+  const result = await buildLibrary(library, { outDir: options.out, force: options.force });
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return 0;
+  }
+  out.success(`Built ${result.skills.length} skill(s) into ${displayPath(result.outDir)}`);
+  for (const skill of result.skills) {
+    const params = skill.params.length ? ` (params: ${skill.params.join(", ")})` : "";
+    out.print(`   ${skill.exportName}  ${skill.name}${params}`);
+  }
+  return 0;
+}
 
 // src/commands/wizard.ts
 import fs from "fs/promises";
@@ -747,6 +765,7 @@ ${Object.entries(RULES).map(([id, rule]) => `  ${id.padEnd(22)} ${rule.severity.
   program2.command("doctor").description("diagnose the library and optionally repair fixable problems").option("--fix", "apply automatic fixes (README entries, name mismatch, tabs, tools -> allowed-tools)").addOption(cwdOption()).addOption(jsonOption()).action(run((options) => doctorCommand(options)));
   const templates = program2.command("templates").description("manage skill templates");
   templates.command("eject").description("copy the built-in skill template into the library for customisation").option("--category <id>", "eject as a category-specific template (skill-<id>)").option("--force", "overwrite an existing template folder").addOption(cwdOption()).addOption(jsonOption()).action(run((options) => ejectCommand(options)));
+  program2.command("build").description("generate the library's npm exports: one typed function per skill (dist/index.mjs, index.cjs, .d.ts)").option("--out <dir>", "output folder relative to the library root (default: dist)").option("--force", "build even when validation reports errors").addOption(cwdOption()).addOption(jsonOption()).action(run((options) => buildCommand(options)));
   program2.command("install-skill [dest]").description("install or update the skanvil agent skill so coding agents in a project know how to use skanvil").option(
     "--target <name>",
     `preset (${Object.keys(TARGET_PRESETS).join(", ")}) or path relative to dest; repeatable or comma-separated (default: claude)`,
@@ -756,7 +775,7 @@ ${Object.entries(RULES).map(([id, rule]) => `  ${id.padEnd(22)} ${rule.severity.
     "--target <name>",
     `preset (${Object.keys(TARGET_PRESETS).join(", ")}) or path relative to dest; repeatable or comma-separated`,
     collect
-  ).option("--from <pkg|path>", "skills library to install (npm package in node_modules or folder); default: --cwd").option("--link", "symlink skills instead of copying (junctions on Windows)").option("--copy", "copy skills (overrides sync.mode = link)").option("--category <id>", "only skills of this category (repeatable)", collect).option("--skill <name>", "only this skill (repeatable)", collect).option("--force", "also sync skills with validation errors").option("--dry-run", "show what would change without writing").option("--global", "install into your user folders (~/.claude/skills, ~/.copilot/skills, ~/.agents/skills)").addOption(cwdOption()).addOption(jsonOption()).action(run((dest, options) => syncCommand(dest, options)));
+  ).option("--from <pkg|path>", "skills library to install (npm package in node_modules or folder); default: --cwd").option("--link", "symlink skills instead of copying (junctions on Windows)").option("--copy", "copy skills (overrides sync.mode = link)").option("--category <id>", "only skills of this category (repeatable)", collect).option("--skill <name>", "only this skill (repeatable)", collect).option("--force", "also sync skills with validation errors").option("--dry-run", "show what would change without writing").option("--param <name=value>", "value for parametrized skills (repeatable); remembered per target", collect).option("--global", "install into your user folders (~/.claude/skills, ~/.copilot/skills, ~/.agents/skills)").addOption(cwdOption()).addOption(jsonOption()).action(run((dest, options) => syncCommand(dest, options)));
   return program2;
 }
 var argv = process.argv.slice(2);

package/dist/index.d.ts

@@ -270,6 +270,104 @@ declare class Categories {
     buildTitle(type: unknown, rawName: unknown, explicitTitle?: unknown): string;
 }
 
+/** File that declares a skill's parameters, next to its `SKILL.md`. Not part of the Agent Skills spec. */
+declare const PARAMS_FILE = "params.json";
+declare const ParamSchema: z.ZodUnion<readonly [z.ZodObject<{
+    type: z.ZodLiteral<"enum">;
+    values: z.ZodArray<z.ZodString>;
+    default: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"string">;
+    default: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"boolean">;
+    default: z.ZodBoolean;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>]>;
+/** One parameter definition. Every parameter has a default, so skills always render. */
+type ParamDefinition = z.infer<typeof ParamSchema>;
+/** Parameter definitions of a skill, by name. */
+type ParamDefinitions = Record<string, ParamDefinition>;
+/** Parameter values, as passed by users (`--param key=value` gives strings). */
+type ParamValues = Record<string, string | boolean>;
+/**
+ * Parses and checks the content of a `params.json`.
+ *
+ * @param text - File content.
+ * @returns The definitions.
+ * @throws Error describing the first problems: invalid JSON, unknown fields, missing defaults,
+ *   or an enum default that is not one of its values.
+ */
+declare function parseParams(text: string): ParamDefinitions;
+/**
+ * Reads a skill folder's `params.json`.
+ *
+ * @param skillDir - Absolute skill folder.
+ * @returns The definitions, or `null` when the skill has no `params.json`.
+ * @throws Error when the file exists but is invalid (see {@link parseParams}).
+ */
+declare function readParams(skillDir: string): Promise<ParamDefinitions | null>;
+/**
+ * Checks values against definitions and fills in defaults.
+ *
+ * Strings `"true"` / `"false"` are accepted for boolean parameters, so CLI values work.
+ *
+ * @param definitions - The skill's parameters.
+ * @param given - Values to apply. @defaultValue `{}`
+ * @param skill - Skill name used in error messages.
+ * @param ignoreUnknown - Ignore values for parameters this skill does not declare (used when one
+ *   set of values is applied to many skills). @defaultValue `false`
+ * @returns A value for every declared parameter.
+ * @throws Error for an unknown parameter (unless ignored), an enum value outside its list, or a
+ *   value of the wrong type.
+ *
+ * @remarks Self-contained on purpose: `skanvil build` embeds this function's source.
+ */
+declare function resolveParamValues(definitions: ParamDefinitions, given?: Record<string, unknown>, skill?: string, ignoreUnknown?: boolean): ParamValues;
+/**
+ * Renders a skill template.
+ *
+ * Syntax:
+ * - `{{name}}` is replaced by the value of a declared parameter. Names that are not parameters are
+ *   left untouched, so literal `{{…}}` text in a skill without parameters is safe.
+ * - `{{#if name}}`, `{{#if !name}}`, `{{#if name == "value"}}` and `{{#if name != "value"}}`
+ *   (single or double quotes) start a block, with an optional `{{else}}`, closed by `{{/if}}`.
+ *   Blocks nest. A tag alone on its line removes the whole line, so blocks leave no blank lines.
+ *
+ * @param text - Template (LF or CRLF).
+ * @param values - Values for every parameter, normally from {@link resolveParamValues}.
+ * @returns The rendered text.
+ * @throws Error for an `{{#if}}` on an unknown parameter, a malformed condition, or unbalanced
+ *   `{{#if}}` / `{{else}}` / `{{/if}}` tags.
+ *
+ * @example
+ * ```ts
+ * renderTemplate('Use {{tracker}}.\n{{#if tracker == "jira"}}\nAdd the key.\n{{/if}}\n', { tracker: "jira" });
+ * // "Use jira.\nAdd the key.\n"
+ * ```
+ *
+ * @remarks Self-contained on purpose: `skanvil build` embeds this function's source.
+ */
+declare function renderTemplate(text: string, values: Record<string, string | boolean>): string;
+/**
+ * Lists the `{{name}}` placeholders of a template that are not declared parameters.
+ *
+ * @param text - Template.
+ * @param definitions - Declared parameters.
+ * @returns Unique undeclared names, in order of appearance.
+ */
+declare function findUndeclaredParams(text: string, definitions: ParamDefinitions): string[];
+/**
+ * Parses `key=value` pairs (from repeated `--param` options).
+ *
+ * @param pairs - Entries such as `ticketTracker=jira`; values may contain `=`.
+ * @returns The values (strings; booleans are converted by {@link resolveParamValues}).
+ * @throws Error for an entry without `=` or with an invalid name.
+ */
+declare function parseParamPairs(pairs: string[]): Record<string, string>;
+
 /**
  * Reading and editing `SKILL.md` files.
  *
@@ -471,6 +569,25 @@ declare class Library {
      * @throws The file system error when the file cannot be read.
      */
     readSkill(name: string): Promise<SkillFile>;
+    /**
+     * Reads a skill's parameter definitions (`params.json`).
+     *
+     * @param name - Skill folder name.
+     * @returns The definitions, or `null` when the skill has none.
+     * @throws Error when `params.json` exists but is invalid.
+     */
+    readSkillParams(name: string): Promise<ParamDefinitions | null>;
+    /**
+     * Reads a skill's `SKILL.md` rendered with parameter values. Skills without `params.json` are
+     * returned as they are.
+     *
+     * @param name - Skill folder name.
+     * @param values - Parameter values; missing ones take their defaults. @defaultValue `{}`
+     * @returns The rendered file.
+     * @throws Error when the file cannot be read, `params.json` is invalid, a value is invalid, or
+     *   the template is malformed.
+     */
+    readSkillRendered(name: string, values?: Record<string, unknown>): Promise<SkillFile>;
     /**
      * Writes a skill's `SKILL.md`, keeping the line ending it was read with.
      *
@@ -567,6 +684,12 @@ interface SyncOptions {
     scope?: TargetScope;
     /** Home folder for the `user` scope. @defaultValue `os.homedir()` */
     homeDir?: string;
+    /**
+     * Values for parametrized skills (`params.json`), applied to every skill that declares them.
+     * When omitted, each target reuses the values of its previous sync, then the defaults.
+     * Every key must be declared by at least one synced skill.
+     */
+    params?: Record<string, string | boolean>;
 }
 /** Outcome of {@link syncSkills} for one target. */
 interface TargetResult {
@@ -589,6 +712,8 @@ interface TargetResult {
     }[];
     /** Non-fatal problems, such as a link that fell back to a copy. */
     warnings: string[];
+    /** Parameter values used for this target (empty when no synced skill has parameters). */
+    params: Record<string, string | boolean>;
 }
 /**
  * Resolves a sync target to an absolute folder.
@@ -689,6 +814,60 @@ interface AgentSkillResult {
  */
 declare function installAgentSkill(options: InstallAgentSkillOptions): Promise<AgentSkillResult[]>;
 
+/** Options of {@link buildLibrary}. */
+interface BuildOptions {
+    /** Output folder, relative to the library root. @defaultValue `"dist"` */
+    outDir?: string;
+    /** Build even when validation reports errors. @defaultValue `false` */
+    force?: boolean;
+}
+/** One exported skill. */
+interface BuiltSkill {
+    /** Skill folder name. */
+    name: string;
+    /** Name of the exported function. */
+    exportName: string;
+    /** Category id. */
+    category: string;
+    /** Declared parameter names. */
+    params: string[];
+}
+/** Result of {@link buildLibrary}. */
+interface BuildResult {
+    /** Absolute output folder. */
+    outDir: string;
+    /** Generated files, relative to the library root (posix). */
+    files: string[];
+    /** Exported skills, in folder order. */
+    skills: BuiltSkill[];
+}
+/**
+ * Chooses export names: the folder name without its category prefix, in camelCase
+ * (`front-api-review` becomes `apiReview`). Names that would collide fall back to the full folder
+ * name (`frontReview`, `backReview`), and invalid or reserved identifiers get a `skill` prefix.
+ *
+ * @param library - Library whose categories define the prefixes.
+ * @param names - Skill folder names.
+ * @returns Export name by folder name.
+ */
+declare function exportNames(library: Library, names: string[]): Map<string, string>;
+/**
+ * Generates `index.mjs`, `index.cjs`, `index.d.mts` and `index.d.cts` for the library's
+ * publishable skills (categories with `validated: true`).
+ *
+ * @param library - Library to build.
+ * @param options - Output folder and error handling.
+ * @returns What was generated.
+ * @throws Error when validation reports errors (unless `force`), or a skill's parameters are invalid.
+ *
+ * @example
+ * ```ts
+ * const { skills } = await buildLibrary(await Library.open("."));
+ * // then, in a consumer: import { apiReview } from "@acme/my-skills";
+ * ```
+ */
+declare function buildLibrary(library: Library, options?: BuildOptions): Promise<BuildResult>;
+
 /** Severity of a reported diagnostic (rules set to `off` report nothing). */
 type DiagnosticSeverity = Exclude<Severity, "off">;
 /** A single validation finding. */
@@ -1079,4 +1258,4 @@ interface ListedSkill {
  */
 declare function collectSkills(library: Library, category?: string): Promise<ListedSkill[]>;
 
-export { AGENT_SKILL_NAME, type AddSkillOptions, type AgentSkillResult, CONFIG_FILE, Categories, type Category, ConfigSchema, type CreateLibraryOptions, DEFAULT_CATEGORIES, type Diagnostic, type DoctorResult, type EditSkillOptions, type InstallAgentSkillOptions, Library, type ListedSkill, MANIFEST_FILE, RULES, type RawConfig, type ResolveTargetOptions, type ResolvedConfig, type Severity, SkillFile, type SkillInfo, type SyncOptions, TARGET_PRESETS, type TargetResult, type TargetScope, USER_TARGET_PRESETS, type ValidationResult, agentSkillSource, collectSkills, configJsonSchema, createLibrary, doctor, editSkill, ejectSkillTemplate, formatDiagnostic, installAgentSkill, loadConfig, parseProfile, rebuildIndex, reconcileIndex, removeSkill, resolveConfig, resolveSkillTemplate, resolveTarget, scaffoldSkill, syncSkills, validateLibrary };
+export { AGENT_SKILL_NAME, type AddSkillOptions, type AgentSkillResult, type BuildOptions, type BuildResult, type BuiltSkill, CONFIG_FILE, Categories, type Category, ConfigSchema, type CreateLibraryOptions, DEFAULT_CATEGORIES, type Diagnostic, type DoctorResult, type EditSkillOptions, type InstallAgentSkillOptions, Library, type ListedSkill, MANIFEST_FILE, PARAMS_FILE, type ParamDefinition, type ParamDefinitions, type ParamValues, RULES, type RawConfig, type ResolveTargetOptions, type ResolvedConfig, type Severity, SkillFile, type SkillInfo, type SyncOptions, TARGET_PRESETS, type TargetResult, type TargetScope, USER_TARGET_PRESETS, type ValidationResult, agentSkillSource, buildLibrary, collectSkills, configJsonSchema, createLibrary, doctor, editSkill, ejectSkillTemplate, exportNames, findUndeclaredParams, formatDiagnostic, installAgentSkill, loadConfig, parseParamPairs, parseParams, parseProfile, readParams, rebuildIndex, reconcileIndex, removeSkill, renderTemplate, resolveConfig, resolveParamValues, resolveSkillTemplate, resolveTarget, scaffoldSkill, syncSkills, validateLibrary };

package/dist/index.js

@@ -6,31 +6,40 @@ import {
   DEFAULT_CATEGORIES,
   Library,
   MANIFEST_FILE,
+  PARAMS_FILE,
   RULES,
   SkillFile,
   TARGET_PRESETS,
   USER_TARGET_PRESETS,
   agentSkillSource,
+  buildLibrary,
   collectSkills,
   configJsonSchema,
   createLibrary,
   doctor,
   editSkill,
   ejectSkillTemplate,
+  exportNames,
+  findUndeclaredParams,
   formatDiagnostic,
   installAgentSkill,
   loadConfig,
+  parseParamPairs,
+  parseParams,
   parseProfile,
+  readParams,
   rebuildIndex,
   reconcileIndex,
   removeSkill,
+  renderTemplate,
   resolveConfig,
+  resolveParamValues,
   resolveSkillTemplate,
   resolveTarget,
   scaffoldSkill,
   syncSkills,
   validateLibrary
-} from "./chunk-TYO4LLN5.js";
+} from "./chunk-WXEWECJP.js";
 export {
   AGENT_SKILL_NAME,
   CONFIG_FILE,
@@ -39,25 +48,34 @@ export {
   DEFAULT_CATEGORIES,
   Library,
   MANIFEST_FILE,
+  PARAMS_FILE,
   RULES,
   SkillFile,
   TARGET_PRESETS,
   USER_TARGET_PRESETS,
   agentSkillSource,
+  buildLibrary,
   collectSkills,
   configJsonSchema,
   createLibrary,
   doctor,
   editSkill,
   ejectSkillTemplate,
+  exportNames,
+  findUndeclaredParams,
   formatDiagnostic,
   installAgentSkill,
   loadConfig,
+  parseParamPairs,
+  parseParams,
   parseProfile,
+  readParams,
   rebuildIndex,
   reconcileIndex,
   removeSkill,
+  renderTemplate,
   resolveConfig,
+  resolveParamValues,
   resolveSkillTemplate,
   resolveTarget,
   scaffoldSkill,

package/docs/commands.md

@@ -176,17 +176,18 @@ Copy the built-in skill template into the library so you can edit it.
 
 Install the library's skills into a project. `dest` defaults to the current directory. See [Sync](sync.md).
 
-| Option               | Description                                                                                                                                                 |
-| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--target <name>`    | `claude`, `copilot`, `agents`, `codex`, or a path relative to `dest`. Repeatable and comma-separated. Default: `sync.targets` from the config, or `claude`. |
-| `--from <pkg\|path>` | Source library: a folder, or an npm package installed in a `node_modules` above `dest`. Default: `--cwd`.                                                   |
-| `--link`             | Symlink instead of copying (junctions on Windows).                                                                                                          |
-| `--copy`             | Copy, even if the config sets `sync.mode: "link"`.                                                                                                          |
-| `--category <id>`    | Only sync this category. Repeatable. Disables pruning.                                                                                                      |
-| `--skill <name>`     | Only sync this skill. Repeatable. Disables pruning.                                                                                                         |
-| `--force`            | Also sync skills that have validation errors.                                                                                                               |
-| `--dry-run`          | Show what would change without writing.                                                                                                                     |
-| `--global`           | Install into your user folders instead of a project (see below). Do not pass `dest` with it.                                                                |
+| Option                 | Description                                                                                                                                                                    |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `--target <name>`      | `claude`, `copilot`, `agents`, `codex`, or a path relative to `dest`. Repeatable and comma-separated. Default: `sync.targets` from the config, or `claude`.                    |
+| `--from <pkg\|path>`   | Source library: a folder, or an npm package installed in a `node_modules` above `dest`. Default: `--cwd`.                                                                      |
+| `--link`               | Symlink instead of copying (junctions on Windows).                                                                                                                             |
+| `--copy`               | Copy, even if the config sets `sync.mode: "link"`.                                                                                                                             |
+| `--category <id>`      | Only sync this category. Repeatable. Disables pruning.                                                                                                                         |
+| `--skill <name>`       | Only sync this skill. Repeatable. Disables pruning.                                                                                                                            |
+| `--force`              | Also sync skills that have validation errors.                                                                                                                                  |
+| `--dry-run`            | Show what would change without writing.                                                                                                                                        |
+| `--param <name=value>` | Value for [parametrized skills](params-and-exports.md). Repeatable. It applies to every synced skill that declares it, and an unknown name is an error. Remembered per target. |
+| `--global`             | Install into your user folders instead of a project (see below). Do not pass `dest` with it.                                                                                   |
 
 Custom `--target` paths must resolve to a folder inside `dest`: `../shared` or `.` are rejected before anything is written. With `--global`, only presets are accepted:
 
@@ -200,6 +201,17 @@ skanvil sync --from @acme/my-skills --target agents --link
 skanvil sync -C ./my-skills --global --target claude
 ```
 
+## `build`
+
+Generate the library's npm exports in `dist/`: `index.mjs`, `index.cjs` and their type declarations. They contain one function per publishable skill that returns its `SKILL.md` (rendered with parameters), a `skills` list and `getSkill(name)`. See [Parameters and exports](params-and-exports.md).
+
+| Option        | Description                                                  |
+| ------------- | ------------------------------------------------------------ |
+| `--out <dir>` | Output folder relative to the library root. Default: `dist`. |
+| `--force`     | Build even when validation reports errors.                   |
+
+`--json` prints `{ outDir, files, skills: [{ name, exportName, category, params }] }`.
+
 ## `install-skill [dest]`
 
 Install or update the `skanvil` agent skill in a project, so coding agents there know how to use skanvil: which commands to run, the golden rules, and how to fix each diagnostic. `dest` defaults to the current directory.

package/docs/getting-started.md

@@ -4,6 +4,52 @@ This guide creates a skills library, adds and edits skills, checks them in CI, p
 
 > **Prefer menus?** Run `npx skanvil` without arguments in a terminal. The [wizard](commands.md#wizard) walks through every step below. After each action it prints the equivalent command, which is the one this guide uses.
 
+## 0. Let your AI agent learn skanvil (optional)
+
+skanvil ships an agent skill that teaches coding agents (Claude Code, GitHub Copilot, Codex…) how to use it:
+
+- the commands and the rules (never rename folders or edit the README index by hand);
+- how to fix every validation error;
+- how to write good skill content.
+
+Paste this prompt into your agent, inside the repository where you want to work. That can be an existing skills library, an application that consumes one, or an empty folder for a new library.
+
+```text
+Install and learn the skanvil agent skill in this repository.
+
+1. Work out which skills folder you read: Claude Code uses .claude/skills, GitHub Copilot
+   .github/skills, Codex .agents/skills. Then run the matching command, for example:
+     npx skanvil@latest install-skill --target claude
+   Use --target copilot or --target agents (comma-separated for several) if that fits you
+   better. Do not use --global unless I ask for it.
+2. Read the installed <skills folder>/skanvil/SKILL.md completely (for example
+   .claude/skills/skanvil/SKILL.md), and then its references/REFERENCE.md.
+3. Detect the context:
+   - if there is a .skanvilrc.json, run `npx skanvil list --json` and `npx skanvil validate --json`;
+   - otherwise, tell me this is not a skills library yet.
+4. Reply with:
+   - a short summary of how you will use skanvil here;
+   - the golden rules you will follow;
+   - what the library contains and any validation problems you found.
+   Do not change any skill until I ask.
+
+From now on, whenever I ask you to create, rename, move, delete, validate, parametrize, build or
+install skills, use the skanvil skill and its commands. Do not edit skill folders or the README
+index by hand, always pass every option (the commands are interactive otherwise), and never run
+`skanvil` without arguments, because that opens a menu meant for humans.
+```
+
+After that, you can ask in plain language, and the agent will turn each request into the right commands. For example:
+
+- _"Create a skills library called acme-skills with categories mobile and data."_
+- _"Add a backend skill for zero-downtime database migrations and write its content."_
+- _"Make the code-review skill configurable for GitHub or Jira."_
+- _"Install the library's skills into ../my-app for Claude Code and Copilot."_
+
+The agent will then run `init`, `add`, `edit`, `validate`, `sync --param`, `build` and so on, and check the result with `skanvil validate`.
+
+`skanvil init` already installs this skill in new libraries, in `.claude/skills/skanvil` by default. Run the prompt again after upgrading skanvil, and `install-skill` will refresh the skill.
+
 ## 1. Create a library
 
 ```bash

package/docs/params-and-exports.md

@@ -0,0 +1,196 @@
+# Parameters and package exports
+
+Two optional features turn a skills library into something other code can use.
+
+- **Parameters** make one skill adapt to each team or project: the issue tracker, the package
+  manager, a dashboard URL. You keep one skill instead of near-identical copies.
+- **Exports** (`skanvil build`) make the library's npm package importable:
+  `import { codeReview } from "@acme/skills"` returns the skill's `SKILL.md`, rendered with the
+  parameters you pass. The result is fully typed.
+
+Skills without parameters work exactly as before. You can use exports without ever adding a
+parameter.
+
+## When this is worth it
+
+- **One skill, many variants.** Teams use different trackers, CI systems or package managers, and
+  you are about to duplicate a skill to change a few lines.
+- **Facts an agent cannot infer.** For example the Grafana URL, the incident Slack channel or the
+  real deploy command. A parameter keeps them out of the shared text.
+- **Skills consumed by code**, such as a project generator that installs tailored skills, a custom
+  agent built with an SDK that puts a skill in its prompt, or a monorepo script that installs a
+  skill per package.
+
+If every project uses the same tools, plain `SKILL.md` files plus `skanvil sync` are simpler.
+
+## Declaring parameters
+
+Add a `params.json` next to the skill's `SKILL.md`:
+
+```text
+skills/front-code-review/
+├── SKILL.md
+├── params.json
+└── references/
+```
+
+```json
+{
+  "ticketTracker": {
+    "type": "enum",
+    "values": ["github", "jira", "linear"],
+    "default": "github",
+    "description": "Where findings are filed"
+  },
+  "packageManager": { "type": "string", "default": "npm" },
+  "strict": { "type": "boolean", "default": false, "description": "Block merges on any finding" }
+}
+```
+
+Rules for `params.json`:
+
+- **Names** are camelCase letters and digits.
+- **Types** are `enum` (with `values`), `string` or `boolean`.
+- **Defaults** are required, so a skill always renders. An enum default must be one of its values.
+- **The file stays out of agents' folders.** `params.json` is not part of the Agent Skills spec, so
+  `sync` and `build` never copy it to them.
+
+## Template syntax
+
+Use the parameters anywhere in `SKILL.md`, including the frontmatter:
+
+```md
+Run `{{packageManager}} test` before reviewing, and file each finding in {{ticketTracker}}.
+
+{{#if ticketTracker == "jira"}}
+Use the `PROJ-123` key format in the summary.
+{{else}}
+Reference issues as `#123`.
+{{/if}}
+
+{{#if strict}}
+Block the merge until every finding is resolved.
+{{/if}}
+```
+
+| Syntax                                                | Meaning                                                               |
+| ----------------------------------------------------- | --------------------------------------------------------------------- |
+| `{{name}}`                                            | The parameter's value.                                                |
+| `{{#if name}}` / `{{#if !name}}`                      | The parameter is true, or false. For strings, "true" means not empty. |
+| `{{#if name == "value"}}` / `{{#if name != "value"}}` | Equality test (single or double quotes).                              |
+| `{{else}}`, `{{/if}}`                                 | Else branch and end of block. Blocks can nest.                        |
+
+How rendering behaves:
+
+- **Tag lines vanish.** A block tag alone on its line removes the whole line, so blocks leave no
+  blank lines behind.
+- **Literal braces are safe.** `{{text}}` that is not a declared parameter is left as it is. In a
+  skill that has a `params.json`, validation reports it, because it is usually a typo.
+
+## Validation
+
+`skanvil validate` checks parametrized skills as rendered with their defaults, so every spec and
+library rule still applies. Two extra rules apply:
+
+- **`params-file`**: `params.json` is valid.
+- **`params-template`**: `{{…}}` references and `{{#if}}` blocks use declared parameters and are
+  balanced.
+
+Fix the defaults first: the README index and `skanvil list` show the description rendered with
+them.
+
+## Installing with values (`sync --param`)
+
+```bash
+npx skanvil sync --from @acme/skills --target claude \
+  --param ticketTracker=jira --param packageManager=pnpm --param strict=true
+```
+
+What happens:
+
+- **Rendering.** Every synced skill that declares a parameter gets that value. The others take
+  their defaults. The installed `SKILL.md` is rendered and `params.json` is left out.
+- **Typos fail early.** A name that no synced skill declares is an error, raised before anything
+  is written.
+- **Values are remembered per target**, in `.skanvil-sync.json`. A later `skanvil sync` without
+  `--param` reuses them, and passing `--param` again replaces them.
+- **No links.** A rendered skill cannot be linked, so `--link` copies parametrized skills (with a
+  warning) and still links the others.
+
+## Package exports (`skanvil build`)
+
+```bash
+npx skanvil build          # writes dist/index.mjs, index.cjs, index.d.mts, index.d.cts
+```
+
+Generated libraries already wire this up:
+
+- `npm run build` runs `skanvil validate` and then `skanvil build`.
+- `prepublishOnly` builds before every publish.
+- `package.json` has `exports`, `main` and `types` pointing at `dist/`.
+- `dist/` is gitignored.
+
+The build refuses to run while validation reports errors, unless you pass `--force`.
+
+For a library with `front-code-review` (with the parameters above) and `back-migrations`,
+consumers get:
+
+```ts
+import { codeReview, migrations, skills, getSkill, type CodeReviewParams } from "@acme/skills";
+
+codeReview(); // SKILL.md with the defaults
+codeReview({ ticketTracker: "jira", strict: true }); // rendered for one team
+codeReview({ ticketTracker: "trello" }); // type error, and a runtime error in plain JS
+
+migrations(); // a skill without parameters: its SKILL.md as is
+
+for (const skill of skills) console.log(skill.name, skill.category, skill.description);
+
+// Every file of a skill (references, scripts, assets), with SKILL.md rendered:
+const files = getSkill("front-code-review").files({ ticketTracker: "linear" });
+// { "SKILL.md": { encoding: "utf8", content: "…" }, "references/REFERENCE.md": { … }, … }
+```
+
+How exports are named:
+
+- **The default** is the folder name without its category prefix, in camelCase:
+  `front-code-review` becomes `codeReview`.
+- **Clashes** use the full folder name, for example `frontReview` and `backReview`.
+- **Names that cannot be identifiers** get a `skill` prefix, for example `skill2faSetup`.
+- **What is exported:** only publishable skills, meaning categories with `validated: true`.
+  `_internal` skills are never exported.
+
+The generated code has no dependencies, not even skanvil. It embeds the same renderer that
+skanvil uses, so `codeReview({ … })` and `skanvil sync --param …` always produce the same text.
+
+### Examples
+
+**A project generator** writes tailored skills into a new service:
+
+```ts
+import fs from "node:fs";
+import path from "node:path";
+import { getSkill } from "@acme/skills";
+
+function installSkill(name: string, params: Record<string, string | boolean>, root = ".claude/skills") {
+  for (const [file, { encoding, content }] of Object.entries(getSkill(name as never).files(params as never))) {
+    const target = path.join(root, name, file);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, Buffer.from(content, encoding));
+  }
+}
+
+installSkill("front-code-review", { ticketTracker: "jira", packageManager: "pnpm" });
+```
+
+**A custom agent** puts a skill in its system prompt:
+
+```ts
+import { codeReview } from "@acme/skills";
+
+const system = codeReview({ ticketTracker: "github", strict: true });
+// pass `system` to your Claude API / Agent SDK call
+```
+
+The skill is then versioned like any dependency, so Renovate or Dependabot tell you when it
+changes.