@invokable/skills 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Invokable
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,77 @@
+# @invokable/skills
+
+Turns an [invokable](https://github.com/beinvokable/invokable) tool schema into
+agent instructions, and installs them wherever the user's agent will look.
+
+```js
+import { initCommand } from '@invokable/skills';
+
+export default defineTool({
+  name: 'demo-tool',
+  commands: { init: initCommand(), /* … */ },
+});
+```
+
+```console
+$ demo-tool init
+created: .claude/skills/demo-tool/SKILL.md
+created: .codex/skills/demo-tool/SKILL.md
+…
+```
+
+## What it writes
+
+**One portable `SKILL.md`**, byte-identical, into every skills directory:
+`.claude/skills/`, `.codex/skills/`, `.cursor/skills/`, `.gemini/skills/` and
+`.agents/skills/`. Plus `references/commands.md`, `references/errors.md`, and
+`references/checkpoints.md` for tools with approval gates.
+
+**A short section** in the flat instruction files other agents read: `AGENTS.md`
+(Codex, Copilot, Cursor, Gemini, Jules, Aider, Zed, Windsurf, Devin, …),
+`.github/copilot-instructions.md`, and `.cursor/rules/<tool>.mdc` for Cursor
+versions predating skills. Only the region between
+`<!-- invokable:begin <tool> -->` and `<!-- invokable:end <tool> -->` is touched.
+
+`CLAUDE.md` gets `@AGENTS.md` rather than a copy of the section: Claude Code
+reads `CLAUDE.md` and not `AGENTS.md`, and duplicating would load the same text
+twice into every session.
+
+## Spec compliance
+
+Only the six frontmatter fields of the [Agent Skills spec](https://agentskills.io)
+are emitted — `name`, `description`, `license`, `compatibility`, `metadata`,
+`allowed-tools`. Claude Code accepts more, but a skill carrying a non-spec field
+fails to upload to claude.ai or the Skills API with a hard error, so emitting one
+would trade portability for nothing.
+
+`name` and `description` are validated against the API's constraints
+(`^[a-z0-9-]{1,64}$`, no reserved words; ≤ 1024 characters, no XML tags) and
+reported as `issues` rather than written out broken.
+
+## Keeping edits
+
+Anything inside `<!-- invokable:custom -->` … `<!-- /invokable:custom -->` is
+carried across regeneration. Blocks that no longer have a placeholder are
+appended rather than dropped — losing someone's edits silently is worse than an
+odd layout. `--force` overwrites them.
+
+## In CI
+
+```yaml
+- run: npx demo-tool init --check
+```
+
+Exits **30** when a schema change was not regenerated. A distinct code, so it
+does not look like a crash.
+
+## Options
+
+| Option | Effect |
+|---|---|
+| `--dir <path>` | Project root. Defaults to the working directory. |
+| `--targets <ids>` | Comma-separated subset. Default: all. |
+| `--check` | Report what is stale; write nothing; exit 30 if any. |
+| `--force` | Overwrite hand-edited custom blocks. |
+
+Target ids: `claude-code`, `codex`, `cursor`, `gemini`, `agents-skills`,
+`agents-md`, `claude-md`, `copilot`, `cursor-rules`.

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { renderSkill, renderSkillMd, renderCommandsReference, renderErrorsReference, renderCheckpointsReference, buildDescription, } from './render.js';
+export type { RenderOptions, RenderedSkill, RenderedFile } from './render.js';
+export { installSkills } from './install.js';
+export type { InstallOptions, InstallResult, InstalledFile, FileAction } from './install.js';
+export { TARGETS, DEFAULT_TARGET_IDS, targetById, renderSection, renderMdc } from './targets.js';
+export type { Target, TargetKind } from './targets.js';
+export { extractCustomBlocks, restoreCustomBlocks, upsertSection, beginMarker, endMarker, } from './markers.js';
+export { SPEC_FIELDS, NAME_PATTERN, DESCRIPTION_MAX, validateSkillName, validateDescription, } from './spec.js';
+export type { SpecField, ValidationIssue } from './spec.js';
+export { initCommand } from './init-command.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,aAAa,EACb,uBAAuB,EACvB,qBAAqB,EACrB,0BAA0B,EAC1B,gBAAgB,GACjB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE9E,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE7F,OAAO,EAAE,OAAO,EAAE,kBAAkB,EAAE,UAAU,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACjG,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAEvD,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,aAAa,EACb,WAAW,EACX,SAAS,GACV,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,WAAW,EACX,YAAY,EACZ,eAAe,EACf,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAE5D,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+export { renderSkill, renderSkillMd, renderCommandsReference, renderErrorsReference, renderCheckpointsReference, buildDescription, } from './render.js';
+export { installSkills } from './install.js';
+export { TARGETS, DEFAULT_TARGET_IDS, targetById, renderSection, renderMdc } from './targets.js';
+export { extractCustomBlocks, restoreCustomBlocks, upsertSection, beginMarker, endMarker, } from './markers.js';
+export { SPEC_FIELDS, NAME_PATTERN, DESCRIPTION_MAX, validateSkillName, validateDescription, } from './spec.js';
+export { initCommand } from './init-command.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,aAAa,EACb,uBAAuB,EACvB,qBAAqB,EACrB,0BAA0B,EAC1B,gBAAgB,GACjB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAG7C,OAAO,EAAE,OAAO,EAAE,kBAAkB,EAAE,UAAU,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAGjG,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,aAAa,EACb,WAAW,EACX,SAAS,GACV,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,WAAW,EACX,YAAY,EACZ,eAAe,EACf,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,WAAW,CAAC;AAGnB,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/init-command.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The `init` built-in from spec 5.3, provided here rather than in core so that
+ * the runtime does not depend on the generator. A tool opts in:
+ *
+ *   commands: { init: initCommand(), … }
+ */
+export declare function initCommand(): import("@invokable/core").CommandSpec<{
+    readonly dir: {
+        readonly type: "string";
+        readonly description: "Project root. Defaults to the working directory.";
+    };
+    readonly targets: {
+        readonly type: "string";
+        readonly description: `Comma-separated targets. Default: all (${string}).`;
+    };
+    readonly check: {
+        readonly type: "boolean";
+        readonly description: "Report what is out of date without writing.";
+    };
+    readonly force: {
+        readonly type: "boolean";
+        readonly description: "Overwrite hand-edited custom blocks.";
+    };
+}>;
+//# sourceMappingURL=init-command.d.ts.map

package/dist/init-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init-command.d.ts","sourceRoot":"","sources":["../src/init-command.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH,wBAAgB,WAAW;;;;;;;;;;;;;;;;;GAqD1B"}

package/dist/init-command.js

@@ -0,0 +1,61 @@
+import { InvokableError, buildManifest, command } from '@invokable/core';
+import { installSkills } from './install.js';
+import { DEFAULT_TARGET_IDS } from './targets.js';
+/**
+ * The `init` built-in from spec 5.3, provided here rather than in core so that
+ * the runtime does not depend on the generator. A tool opts in:
+ *
+ *   commands: { init: initCommand(), … }
+ */
+export function initCommand() {
+    return command({
+        description: 'Install agent instructions for this tool into the current project.',
+        options: {
+            dir: { type: 'string', description: 'Project root. Defaults to the working directory.' },
+            targets: {
+                type: 'string',
+                description: `Comma-separated targets. Default: all (${DEFAULT_TARGET_IDS.join(', ')}).`,
+            },
+            check: { type: 'boolean', description: 'Report what is out of date without writing.' },
+            force: { type: 'boolean', description: 'Overwrite hand-edited custom blocks.' },
+        },
+        exitCodes: { 30: 'Generated agent instructions are out of date (--check).' },
+        // The per-file notes below are the human output; dumping the result object
+        // underneath them would just repeat it at ten times the length.
+        formatHuman: () => null,
+        run: ({ opts, ctx }) => {
+            const result = installSkills({
+                manifest: buildManifest(ctx.tool),
+                ...(opts.dir !== undefined ? { root: opts.dir } : {}),
+                ...(opts.targets !== undefined
+                    ? { targets: opts.targets.split(',').map((s) => s.trim()).filter(Boolean) }
+                    : {}),
+                check: opts.check,
+                force: opts.force,
+            });
+            for (const issue of result.issues) {
+                ctx.io.warn(`warning: ${issue.field}: ${issue.message}`);
+            }
+            const changed = result.files.filter((f) => f.action !== 'unchanged');
+            const verb = (action) => opts.check ? (action === 'created' ? 'would create' : 'would update') : action;
+            for (const file of changed) {
+                ctx.io.note(`${verb(file.action)}: ${file.path}`);
+            }
+            if (!changed.length)
+                ctx.io.note('Agent instructions are up to date.');
+            if (opts.check && result.outOfDate) {
+                // A tool-defined code so CI can fail on stale generated files without
+                // conflating it with a real error.
+                throw new InvokableError({
+                    code: 'skills_out_of_date',
+                    message: `${changed.length} generated file(s) are out of date.`,
+                    remediation: `${ctx.tool.name} init`,
+                    exitCode: 30,
+                    retryable: false,
+                });
+            }
+            return result;
+        },
+    });
+}
+//# sourceMappingURL=init-command.js.map

package/dist/init-command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"init-command.js","sourceRoot":"","sources":["../src/init-command.ts"],"names":[],"mappings":"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"}

package/dist/install.d.ts

@@ -0,0 +1,36 @@
+import { type RenderOptions } from './render.js';
+import type { ValidationIssue } from './spec.js';
+export type FileAction = 'created' | 'updated' | 'unchanged';
+export interface InstalledFile {
+    path: string;
+    action: FileAction;
+    /** Custom blocks carried across from the previous version. */
+    preservedBlocks?: number;
+}
+export interface InstallResult {
+    tool: string;
+    files: InstalledFile[];
+    targets: string[];
+    issues: ValidationIssue[];
+    /** True when `check` was set and something is out of date. */
+    outOfDate: boolean;
+}
+export interface InstallOptions extends RenderOptions {
+    /** Project root. Defaults to the current working directory. */
+    root?: string;
+    /** Target ids; defaults to all of them. */
+    targets?: readonly string[];
+    /** Report what would change without writing. */
+    check?: boolean;
+    /** Overwrite hand-edited custom blocks instead of preserving them. */
+    force?: boolean;
+}
+/**
+ * Generates the skill and installs it into every requested target.
+ *
+ * The same SKILL.md bytes go to every `skill` target: that is what the Agent
+ * Skills standard buys, and duplicating rather than symlinking keeps it working
+ * on Windows and inside archives that do not preserve links.
+ */
+export declare function installSkills(options: InstallOptions): InstallResult;
+//# sourceMappingURL=install.d.ts.map

package/dist/install.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../src/install.ts"],"names":[],"mappings":"AAIA,OAAO,EAAiC,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAShF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAEjD,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,SAAS,GAAG,WAAW,CAAC;AAE7D,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,UAAU,CAAC;IACnB,8DAA8D;IAC9D,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,8DAA8D;IAC9D,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,cAAe,SAAQ,aAAa;IACnD,+DAA+D;IAC/D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,gDAAgD;IAChD,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,sEAAsE;IACtE,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAoBD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,cAAc,GAAG,aAAa,CAmFpE"}

package/dist/install.js

@@ -0,0 +1,90 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+import { extractCustomBlocks, restoreCustomBlocks, upsertSection } from './markers.js';
+import { buildDescription, renderSkill } from './render.js';
+import { DEFAULT_TARGET_IDS, renderClaudeMdPointer, renderMdc, renderSection, targetById, } from './targets.js';
+function writeIfChanged(absolute, content, opts) {
+    const path = relative(opts.root, absolute) || absolute;
+    const exists = existsSync(absolute);
+    const current = exists ? readFileSync(absolute, 'utf8') : null;
+    if (current === content)
+        return { path, action: 'unchanged' };
+    if (!opts.check) {
+        mkdirSync(dirname(absolute), { recursive: true });
+        writeFileSync(absolute, content, 'utf8');
+    }
+    return { path, action: exists ? 'updated' : 'created' };
+}
+/**
+ * Generates the skill and installs it into every requested target.
+ *
+ * The same SKILL.md bytes go to every `skill` target: that is what the Agent
+ * Skills standard buys, and duplicating rather than symlinking keeps it working
+ * on Windows and inside archives that do not preserve links.
+ */
+export function installSkills(options) {
+    const root = options.root ?? process.cwd();
+    const check = options.check ?? false;
+    const ids = options.targets ?? DEFAULT_TARGET_IDS;
+    const targets = [];
+    for (const id of ids) {
+        const target = targetById(id);
+        if (!target) {
+            throw new Error(`Unknown skills target "${id}". Known targets: ${DEFAULT_TARGET_IDS.join(', ')}.`);
+        }
+        targets.push(target);
+    }
+    const rendered = renderSkill(options);
+    const manifest = options.manifest;
+    const description = buildDescription(options);
+    const files = [];
+    // The canonical skill location, referenced by every section target so an
+    // agent reading AGENTS.md knows where the detail lives.
+    const canonical = targets.find((t) => t.kind === 'skill')?.path(manifest.name) ??
+        `.claude/skills/${manifest.name}`;
+    for (const target of targets) {
+        if (target.kind === 'skill') {
+            const dir = join(root, target.path(manifest.name));
+            for (const file of rendered.files) {
+                const absolute = join(dir, file.path);
+                let content = file.content;
+                let preserved = 0;
+                if (!options.force && existsSync(absolute)) {
+                    const blocks = extractCustomBlocks(readFileSync(absolute, 'utf8'));
+                    if (blocks.length) {
+                        content = restoreCustomBlocks(content, blocks);
+                        preserved = blocks.length;
+                    }
+                }
+                const result = writeIfChanged(absolute, content, { check, root });
+                files.push(preserved ? { ...result, preservedBlocks: preserved } : result);
+            }
+            continue;
+        }
+        const absolute = join(root, target.path(manifest.name));
+        if (target.kind === 'mdc') {
+            files.push(writeIfChanged(absolute, renderMdc(manifest, description, canonical), { check, root }));
+            continue;
+        }
+        // kind === 'section': touch only our marked region of someone else's file.
+        const existing = existsSync(absolute) ? readFileSync(absolute, 'utf8') : '';
+        // Claude Code does not read AGENTS.md, so CLAUDE.md has to carry the
+        // content somehow. When AGENTS.md is also a target it already has it, and
+        // an import is enough — repeating the section would load the same text
+        // twice into every Claude Code session.
+        const writesAgentsMd = ids.includes('agents-md');
+        const section = target.id === 'claude-md' && writesAgentsMd
+            ? renderClaudeMdPointer()
+            : renderSection(manifest, canonical);
+        const next = upsertSection(existing, manifest.name, section);
+        files.push(writeIfChanged(absolute, next, { check, root }));
+    }
+    return {
+        tool: manifest.name,
+        files,
+        targets: targets.map((t) => t.id),
+        issues: rendered.issues,
+        outOfDate: files.some((f) => f.action !== 'unchanged'),
+    };
+}
+//# sourceMappingURL=install.js.map

package/dist/install.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.js","sourceRoot":"","sources":["../src/install.ts"],"names":[],"mappings":"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"}

package/dist/markers.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Generated files are regenerated whenever the tool schema changes, so anything
+ * a developer writes by hand has to survive that. Two marker pairs make it:
+ *
+ *   <!-- invokable:custom --> … <!-- /invokable:custom -->
+ *     Inside a generated file. Content is carried across regeneration.
+ *
+ *   <!-- invokable:begin <tool> --> … <!-- invokable:end <tool> -->
+ *     Around our section of a shared file such as AGENTS.md, so we can update
+ *     just that region and never touch the rest of someone's file.
+ */
+export declare function beginMarker(tool: string): string;
+export declare function endMarker(tool: string): string;
+/** Extracts custom blocks in document order. */
+export declare function extractCustomBlocks(content: string): string[];
+/**
+ * Re-inserts previously extracted blocks into freshly generated content,
+ * matching them to placeholders in order. Extra blocks are appended rather than
+ * dropped: losing a developer's edits silently is worse than an odd layout.
+ */
+export declare function restoreCustomBlocks(generated: string, blocks: string[]): string;
+export declare function emptyCustomBlock(hint: string): string;
+/**
+ * Replaces our marked region of a shared file, or appends it when absent.
+ * Content outside the markers is returned untouched.
+ */
+export declare function upsertSection(existing: string, tool: string, section: string): string;
+//# sourceMappingURL=markers.d.ts.map

package/dist/markers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markers.d.ts","sourceRoot":"","sources":["../src/markers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEhD;AACD,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED,gDAAgD;AAChD,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAY7D;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CA0B/E;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAarF"}

package/dist/markers.js

@@ -0,0 +1,88 @@
+/**
+ * Generated files are regenerated whenever the tool schema changes, so anything
+ * a developer writes by hand has to survive that. Two marker pairs make it:
+ *
+ *   <!-- invokable:custom --> … <!-- /invokable:custom -->
+ *     Inside a generated file. Content is carried across regeneration.
+ *
+ *   <!-- invokable:begin <tool> --> … <!-- invokable:end <tool> -->
+ *     Around our section of a shared file such as AGENTS.md, so we can update
+ *     just that region and never touch the rest of someone's file.
+ */
+const CUSTOM_OPEN = '<!-- invokable:custom -->';
+const CUSTOM_CLOSE = '<!-- /invokable:custom -->';
+export function beginMarker(tool) {
+    return `<!-- invokable:begin ${tool} -->`;
+}
+export function endMarker(tool) {
+    return `<!-- invokable:end ${tool} -->`;
+}
+/** Extracts custom blocks in document order. */
+export function extractCustomBlocks(content) {
+    const blocks = [];
+    let index = 0;
+    for (;;) {
+        const open = content.indexOf(CUSTOM_OPEN, index);
+        if (open === -1)
+            break;
+        const close = content.indexOf(CUSTOM_CLOSE, open);
+        if (close === -1)
+            break;
+        blocks.push(content.slice(open + CUSTOM_OPEN.length, close).trim());
+        index = close + CUSTOM_CLOSE.length;
+    }
+    return blocks;
+}
+/**
+ * Re-inserts previously extracted blocks into freshly generated content,
+ * matching them to placeholders in order. Extra blocks are appended rather than
+ * dropped: losing a developer's edits silently is worse than an odd layout.
+ */
+export function restoreCustomBlocks(generated, blocks) {
+    if (blocks.length === 0)
+        return generated;
+    let result = generated;
+    let used = 0;
+    for (;;) {
+        const open = result.indexOf(CUSTOM_OPEN, used === 0 ? 0 : result.indexOf(CUSTOM_CLOSE) + 1);
+        if (open === -1 || used >= blocks.length)
+            break;
+        const close = result.indexOf(CUSTOM_CLOSE, open);
+        if (close === -1)
+            break;
+        const body = blocks[used] ?? '';
+        const replacement = `${CUSTOM_OPEN}\n${body ? body + '\n' : ''}${CUSTOM_CLOSE}`;
+        result = result.slice(0, open) + replacement + result.slice(close + CUSTOM_CLOSE.length);
+        used += 1;
+    }
+    if (used < blocks.length) {
+        const leftover = blocks.slice(used).filter(Boolean);
+        if (leftover.length) {
+            result +=
+                `\n\n${CUSTOM_OPEN}\n` +
+                    leftover.join('\n\n') +
+                    `\n${CUSTOM_CLOSE}\n`;
+        }
+    }
+    return result;
+}
+export function emptyCustomBlock(hint) {
+    return `${CUSTOM_OPEN}\n<!-- ${hint} -->\n${CUSTOM_CLOSE}`;
+}
+/**
+ * Replaces our marked region of a shared file, or appends it when absent.
+ * Content outside the markers is returned untouched.
+ */
+export function upsertSection(existing, tool, section) {
+    const begin = beginMarker(tool);
+    const end = endMarker(tool);
+    const block = `${begin}\n${section.trim()}\n${end}`;
+    const start = existing.indexOf(begin);
+    const stop = existing.indexOf(end);
+    if (start !== -1 && stop !== -1 && stop > start) {
+        return existing.slice(0, start) + block + existing.slice(stop + end.length);
+    }
+    const base = existing.trimEnd();
+    return base ? `${base}\n\n${block}\n` : `${block}\n`;
+}
+//# sourceMappingURL=markers.js.map

package/dist/markers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"markers.js","sourceRoot":"","sources":["../src/markers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,GAAG,2BAA2B,CAAC;AAChD,MAAM,YAAY,GAAG,4BAA4B,CAAC;AAElD,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,OAAO,wBAAwB,IAAI,MAAM,CAAC;AAC5C,CAAC;AACD,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,OAAO,sBAAsB,IAAI,MAAM,CAAC;AAC1C,CAAC;AAED,gDAAgD;AAChD,MAAM,UAAU,mBAAmB,CAAC,OAAe;IACjD,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,SAAS,CAAC;QACR,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;QACjD,IAAI,IAAI,KAAK,CAAC,CAAC;YAAE,MAAM;QACvB,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;QAClD,IAAI,KAAK,KAAK,CAAC,CAAC;YAAE,MAAM;QACxB,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,GAAG,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;QACpE,KAAK,GAAG,KAAK,GAAG,YAAY,CAAC,MAAM,CAAC;IACtC,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,SAAiB,EAAE,MAAgB;IACrE,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAE1C,IAAI,MAAM,GAAG,SAAS,CAAC;IACvB,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,SAAS,CAAC;QACR,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,WAAW,EAAE,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC;QAC5F,IAAI,IAAI,KAAK,CAAC,CAAC,IAAI,IAAI,IAAI,MAAM,CAAC,MAAM;YAAE,MAAM;QAChD,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;QACjD,IAAI,KAAK,KAAK,CAAC,CAAC;YAAE,MAAM;QACxB,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QAChC,MAAM,WAAW,GAAG,GAAG,WAAW,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,EAAE,GAAG,YAAY,EAAE,CAAC;QAChF,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,WAAW,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;QACzF,IAAI,IAAI,CAAC,CAAC;IACZ,CAAC;IAED,IAAI,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC;QACzB,MAAM,QAAQ,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACpD,IAAI,QAAQ,CAAC,MAAM,EAAE,CAAC;YACpB,MAAM;gBACJ,OAAO,WAAW,IAAI;oBACtB,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC;oBACrB,KAAK,YAAY,IAAI,CAAC;QAC1B,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,OAAO,GAAG,WAAW,UAAU,IAAI,SAAS,YAAY,EAAE,CAAC;AAC7D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,QAAgB,EAAE,IAAY,EAAE,OAAe;IAC3E,MAAM,KAAK,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;IAChC,MAAM,GAAG,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;IAC5B,MAAM,KAAK,GAAG,GAAG,KAAK,KAAK,OAAO,CAAC,IAAI,EAAE,KAAK,GAAG,EAAE,CAAC;IAEpD,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IACtC,MAAM,IAAI,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAEnC,IAAI,KAAK,KAAK,CAAC,CAAC,IAAI,IAAI,KAAK,CAAC,CAAC,IAAI,IAAI,GAAG,KAAK,EAAE,CAAC;QAChD,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,GAAG,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC;IAC9E,CAAC;IACD,MAAM,IAAI,GAAG,QAAQ,CAAC,OAAO,EAAE,CAAC;IAChC,OAAO,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,GAAG,KAAK,IAAI,CAAC;AACvD,CAAC"}

package/dist/render.d.ts

@@ -0,0 +1,39 @@
+import { type ToolManifest } from '@invokable/core';
+import { type ValidationIssue } from './spec.js';
+export interface RenderOptions {
+    manifest: ToolManifest;
+    /** Overrides the generated `description` frontmatter. */
+    description?: string;
+    license?: string;
+    /** Extra trigger phrases folded into the description. */
+    triggers?: readonly string[];
+    /** Defaults to `Bash, Read`. */
+    allowedTools?: readonly string[];
+}
+export interface RenderedFile {
+    /** Path relative to the skill directory. */
+    path: string;
+    content: string;
+}
+export interface RenderedSkill {
+    name: string;
+    files: RenderedFile[];
+    issues: ValidationIssue[];
+}
+/**
+ * Builds the `description`, which is the single most important line: it is what
+ * every agent reads to decide whether to load the skill at all. Leads with the
+ * capability, then the trigger phrases, then the auth precondition.
+ */
+export declare function buildDescription(opts: RenderOptions): string;
+/** The main SKILL.md, using only the six spec-portable frontmatter fields. */
+export declare function renderSkillMd(opts: RenderOptions): {
+    content: string;
+    issues: ValidationIssue[];
+};
+export declare function renderCommandsReference(manifest: ToolManifest): string;
+export declare function renderErrorsReference(manifest: ToolManifest): string;
+export declare function renderCheckpointsReference(manifest: ToolManifest): string;
+/** Renders the complete portable skill bundle. */
+export declare function renderSkill(opts: RenderOptions): RenderedSkill;
+//# sourceMappingURL=render.d.ts.map

package/dist/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AAAA,OAAO,EAAyC,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE3F,OAAO,EAA2D,KAAK,eAAe,EAAE,MAAM,WAAW,CAAC;AAE1G,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,YAAY,CAAC;IACvB,yDAAyD;IACzD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7B,gCAAgC;IAChC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED,MAAM,WAAW,YAAY;IAC3B,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,MAAM,EAAE,eAAe,EAAE,CAAC;CAC3B;AAwBD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAyB5D;AAuCD,8EAA8E;AAC9E,wBAAgB,aAAa,CAAC,IAAI,EAAE,aAAa,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,eAAe,EAAE,CAAA;CAAE,CAoGjG;AAED,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,YAAY,GAAG,MAAM,CA2CtE;AAED,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,YAAY,GAAG,MAAM,CA4CpE;AAED,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,YAAY,GAAG,MAAM,CA0DzE;AAED,kDAAkD;AAClD,wBAAgB,WAAW,CAAC,IAAI,EAAE,aAAa,GAAG,aAAa,CAc9D"}

package/dist/render.js

@@ -0,0 +1,319 @@
+import { EXIT, EXIT_DESCRIPTION } from '@invokable/core';
+import { emptyCustomBlock } from './markers.js';
+import { DESCRIPTION_MAX, validateDescription, validateSkillName } from './spec.js';
+function yamlString(value) {
+    // Quote whenever YAML would otherwise misread the value.
+    if (/^[\w][\w .,'()/-]*$/.test(value) && !/:\s/.test(value))
+        return value;
+    return JSON.stringify(value);
+}
+function table(headers, rows) {
+    const lines = [`| ${headers.join(' | ')} |`, `|${headers.map(() => '---').join('|')}|`];
+    for (const row of rows)
+        lines.push(`| ${row.join(' | ')} |`);
+    return lines.join('\n');
+}
+function commandSignature(tool, cmd) {
+    const parts = [tool, cmd.name];
+    for (const p of cmd.positionals)
+        parts.push(`<${p}>`);
+    for (const opt of cmd.options) {
+        if (!opt.required)
+            continue;
+        parts.push(opt.type === 'boolean' ? `--${opt.name}` : `--${opt.name} <${opt.type}>`);
+    }
+    return parts.join(' ');
+}
+/**
+ * Builds the `description`, which is the single most important line: it is what
+ * every agent reads to decide whether to load the skill at all. Leads with the
+ * capability, then the trigger phrases, then the auth precondition.
+ */
+export function buildDescription(opts) {
+    if (opts.description)
+        return opts.description;
+    const { manifest } = opts;
+    const verbs = manifest.commands
+        .filter((c) => !['login', 'logout', 'whoami', 'doctor', 'init', 'update'].includes(c.name))
+        .map((c) => c.name)
+        .slice(0, 8);
+    const base = manifest.description ??
+        `Run ${manifest.name} commands from the CLI.`;
+    const triggerText = opts.triggers?.length
+        ? opts.triggers.join(', ')
+        : verbs.join(', ');
+    const parts = [
+        base.replace(/\s+$/, ''),
+        triggerText ? `Use when the user asks to: ${triggerText}.` : '',
+        `Always pass --json and read the exit code. Requires \`${manifest.name} login\` first.`,
+    ].filter(Boolean);
+    const joined = parts.join(' ');
+    return joined.length > DESCRIPTION_MAX ? joined.slice(0, DESCRIPTION_MAX - 1) + '…' : joined;
+}
+function renderFrontmatter(opts, description) {
+    const { manifest } = opts;
+    const allowed = (opts.allowedTools ?? ['Bash', 'Read']).join(', ');
+    const lines = [
+        '---',
+        `name: ${manifest.name}`,
+        `description: ${yamlString(description)}`,
+        `allowed-tools: ${allowed}`,
+    ];
+    if (opts.license)
+        lines.push(`license: ${yamlString(opts.license)}`);
+    lines.push('metadata:', `  tool-version: ${yamlString(manifest.version)}`, '  generated-by: "@invokable/skills"');
+    lines.push('---');
+    return lines.join('\n');
+}
+function renderCommandsSection(manifest) {
+    const rows = manifest.commands.map((c) => [
+        `\`${commandSignature(manifest.name, c)}\``,
+        c.description.replace(/\|/g, '\\|') + (c.spends ? ' **(spends money)**' : ''),
+    ]);
+    return table(['Command', 'What it does'], rows);
+}
+function renderExitCodesSection(manifest) {
+    const rows = manifest.exitCodes.map((e) => [
+        String(e.code),
+        `\`${e.name}\``,
+        e.description.replace(/\|/g, '\\|'),
+    ]);
+    return table(['Exit', 'Name', 'What to do'], rows);
+}
+/** The main SKILL.md, using only the six spec-portable frontmatter fields. */
+export function renderSkillMd(opts) {
+    const { manifest } = opts;
+    const description = buildDescription(opts);
+    const issues = [...validateSkillName(manifest.name), ...validateDescription(description)];
+    const spending = manifest.commands.filter((c) => c.spends);
+    const body = `
+# ${manifest.name}
+
+${manifest.description ?? `The \`${manifest.name}\` command-line tool.`}
+
+Every command returns **one JSON document on stdout** when given \`--json\`, and a
+**semantic exit code**. Read both. Progress and warnings go to stderr and are not
+part of the result.
+
+## Check auth before the first command
+
+\`\`\`bash
+${manifest.name} doctor --json
+\`\`\`
+
+Read \`.data.auth.ok\`:
+
+- \`true\` — proceed.
+- \`false\` — tell the user to run \`${manifest.name} login\` themselves. **Do not run it
+  for them**: it opens a browser and waits for a human to approve a code. Running it
+  will hang.
+
+If \`.data.api.reachable\` is \`false\`, the network or the service is down. Say so;
+do not retry in a loop.
+
+## Reading a result
+
+\`\`\`bash
+${manifest.name} <command> --json
+\`\`\`
+
+| stdout \`status\` | Meaning | What to do |
+|---|---|---|
+| \`ok\` | Succeeded | Use \`.data\`. |
+| \`error\` | Failed | Read \`.message\`. If \`.remediation\` is present it is the exact next command. Honour \`.retryable\`: when \`false\`, do not retry. |
+| \`checkpoint\` | Waiting for approval | Show \`.display\` to the user verbatim and stop. See below. |
+
+## Commands
+
+${renderCommandsSection(manifest)}
+
+## Exit codes
+
+${renderExitCodesSection(manifest)}
+
+${spending.length
+        ? `## Approval gates
+
+${spending.map((c) => `\`${manifest.name} ${c.name}\``).join(', ')} can spend the user's money.
+${spending.length === 1 ? 'It stops' : 'They stop'} before doing so and ${spending.length === 1 ? 'exits' : 'exit'} **10** with \`"status": "checkpoint"\`.
+
+When that happens:
+
+1. Print \`.display\` to the user **exactly as given**. It is a pre-rendered panel
+   showing the plan and the cost. Do not summarise, shorten or paraphrase it —
+   the user is deciding whether to pay, and they must see the real numbers.
+2. Ask whether to proceed.
+3. Only if they agree, run \`.next.approve\` verbatim. It is a complete command.
+4. If they decline, run \`.next.reject\` when present, and otherwise stop.
+
+Exit **12** (\`checkpoint_stale\`) means the approval no longer matches reality —
+it was already used, it expired, or the plan changed. Re-run the original command
+without \`--approve\` to get a fresh plan, and ask the user again.
+
+See \`references/checkpoints.md\`.
+`
+        : ''}
+## Never
+
+- **Never pass \`--yes\`.** It approves spending without asking the user. The gate
+  exists because the cost is theirs, not yours.
+- **Never pass \`--token\` on the command line.** It is visible to every process on
+  the machine via \`ps\`. Authentication comes from \`${manifest.name} login\`.
+- **Never retry on exit 7** (\`rate_limited\`). Retrying makes it worse. Report it.
+- **Never retry on exit 4** (\`insufficient_spend\`) or **20** (\`declined\`). Neither
+  will succeed on a second attempt, and 20 means the user said no.
+- **Never parse stderr** for results. It carries progress text whose wording changes.
+- **Never invent a command.** Run \`${manifest.name} --help --json\` for the exact
+  schema of every command and option.
+
+${emptyCustomBlock('Add project-specific guidance here. It survives regeneration.')}
+
+## Reference
+
+- \`references/commands.md\` — every option of every command
+- \`references/errors.md\` — every exit code and the correct response
+${spending.length ? '- `references/checkpoints.md` — the approval flow in detail\n' : ''}`.trimStart();
+    return { content: `${renderFrontmatter(opts, description)}\n\n${body}`, issues };
+}
+export function renderCommandsReference(manifest) {
+    const sections = manifest.commands.map((cmd) => {
+        const lines = [`## \`${manifest.name} ${cmd.name}\``, '', cmd.description, ''];
+        if (cmd.spends) {
+            lines.push('**Spends money.** Stops at an approval gate and exits 10.', '');
+        }
+        lines.push('```bash', commandSignature(manifest.name, cmd) + ' --json', '```', '');
+        if (cmd.positionals.length) {
+            lines.push(table(['Positional', 'Required'], cmd.positionals.map((p) => [`\`<${p}>\``, 'yes'])), '');
+        }
+        if (cmd.options.length) {
+            lines.push(table(['Option', 'Type', 'Required', 'Values', 'Description'], cmd.options.map((o) => [
+                `\`--${o.name}\`` + (o.short ? ` / \`-${o.short}\`` : ''),
+                o.type,
+                o.required ? 'yes' : 'no',
+                o.choices ? o.choices.map((c) => `\`${c}\``).join(', ') : o.default !== undefined ? `default \`${String(o.default)}\`` : '—',
+                (o.description ?? '').replace(/\|/g, '\\|'),
+            ])), '');
+        }
+        else if (!cmd.positionals.length) {
+            lines.push('Takes no options.', '');
+        }
+        return lines.join('\n');
+    });
+    return `# ${manifest.name} — command reference
+
+Generated from the tool schema; do not edit by hand.
+
+${sections.join('\n')}`;
+}
+export function renderErrorsReference(manifest) {
+    const custom = manifest.commands.flatMap((c) => Object.entries(c.exitCodes ?? {}).map(([code, desc]) => [c.name, code, desc]));
+    return `# ${manifest.name} — errors and exit codes
+
+Every failure is one JSON document on stdout plus an exit code:
+
+\`\`\`json
+{"status":"error","code":"not_found","message":"…","remediation":"…","retryable":false}
+\`\`\`
+
+- \`remediation\`, when present, is the **exact command to run next**. Prefer it over
+  guessing.
+- \`retryable: false\` means a retry cannot succeed. Do not loop.
+
+## Reserved exit codes
+
+${table(['Exit', 'Name', 'Retry?', 'What to do'], manifest.exitCodes.map((e) => [
+        String(e.code),
+        `\`${e.name}\``,
+        ['timeout', 'network'].includes(e.name) ? 'once' : 'no',
+        e.description.replace(/\|/g, '\\|'),
+    ]))}
+
+${custom.length
+        ? `## Tool-specific exit codes
+
+${table(['Command', 'Exit', 'Meaning'], custom.map(([cmd, code, desc]) => [`\`${cmd}\``, code, String(desc)]))}
+`
+        : ''}
+## Codes that mean "stop", not "try again"
+
+- **${EXIT.rate_limited} (\`rate_limited\`)** — ${EXIT_DESCRIPTION['rate_limited']}
+- **${EXIT.insufficient_spend} (\`insufficient_spend\`)** — the user is out of balance. Only they can fix it.
+- **${EXIT.declined} (\`declined\`)** — the user said no. Do not ask again in the same turn.
+- **${EXIT.auth} (\`auth\`)** — run the \`remediation\`, which is \`${manifest.name} login\`, by telling the **user** to run it.
+`;
+}
+export function renderCheckpointsReference(manifest) {
+    const spending = manifest.commands.filter((c) => c.spends);
+    const example = spending[0]?.name ?? 'deploy';
+    return `# ${manifest.name} — approval gates
+
+Commands that spend money stop first and ask. This is not an error.
+
+## What you receive
+
+\`\`\`json
+{
+  "status": "checkpoint",
+  "schema": "invokable.checkpoint/v1",
+  "gate": "deploy_review",
+  "fingerprint": "GCI3HOREK4LY34J7",
+  "display": "┌───────────…┐\\n│ …the panel… │\\n└───────────┘",
+  "question": "Deploy this plan to production?",
+  "explain": "Approving starts the deploy and bills 1 credit per minute.",
+  "spend": { "estimated": 12, "balance": 100 },
+  "next": {
+    "approve": "${manifest.name} ${example} --env prod --json --approve deploy_review@GCI3HOREK4LY34J7",
+    "reject": "${manifest.name} ${example} --env prod --dry-run"
+  }
+}
+\`\`\`
+
+Exit code: **10**.
+
+## What to do
+
+1. **Print \`display\` verbatim.** It is already formatted for a human and contains
+   the real cost. Paraphrasing it is how a user ends up agreeing to a number they
+   never saw.
+2. **Ask the user.** Quote \`question\`, and \`explain\` if present.
+3. **On yes:** run \`next.approve\` exactly as given. It is the original command with
+   the approval appended, so it needs no editing.
+4. **On no:** run \`next.reject\` if present; otherwise stop and say nothing was done.
+
+## Why you cannot skip this
+
+The fingerprint is issued by the server, not computed locally. It is bound to the
+gate, the target, and the exact plan you were shown; it expires; and it is consumed
+once, by the action it authorises.
+
+So an approval cannot be reused, and one issued against a plan that has since
+changed is rejected with exit **12** (\`checkpoint_stale\`). On 12: re-run the
+original command **without** \`--approve\`, show the user the new plan, and ask again.
+
+## \`--yes\`
+
+\`--yes\` skips the question. **Do not pass it.** The server still records an
+approval, so the audit trail will show that the spend was approved without a human
+being asked — which is exactly the thing the user will object to afterwards.
+
+If the user explicitly instructs you to run without prompting, prefer
+\`--max-spend <n>\`, which refuses to auto-approve anything above the cap.
+`;
+}
+/** Renders the complete portable skill bundle. */
+export function renderSkill(opts) {
+    const { content, issues } = renderSkillMd(opts);
+    const files = [
+        { path: 'SKILL.md', content },
+        { path: 'references/commands.md', content: renderCommandsReference(opts.manifest) },
+        { path: 'references/errors.md', content: renderErrorsReference(opts.manifest) },
+    ];
+    if (opts.manifest.commands.some((c) => c.spends)) {
+        files.push({
+            path: 'references/checkpoints.md',
+            content: renderCheckpointsReference(opts.manifest),
+        });
+    }
+    return { name: opts.manifest.name, files, issues };
+}
+//# sourceMappingURL=render.js.map

package/dist/render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.js","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"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"}

package/dist/spec.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Constraints from the Agent Skills specification (agentskills.io), as enforced
+ * by the Claude Skills API and by `package_skill.py` in anthropics/skills.
+ *
+ * Only six frontmatter fields are portable. Claude Code accepts many more, but
+ * a skill carrying any of them fails to upload to claude.ai or the Skills API
+ * with a hard error rather than being ignored — so a generator that wants one
+ * file to work everywhere must emit only these.
+ */
+export declare const SPEC_FIELDS: readonly ["name", "description", "license", "compatibility", "metadata", "allowed-tools"];
+export type SpecField = (typeof SPEC_FIELDS)[number];
+export declare const NAME_PATTERN: RegExp;
+export declare const NAME_MAX = 64;
+export declare const DESCRIPTION_MAX = 1024;
+export declare const COMPATIBILITY_MAX = 500;
+export interface ValidationIssue {
+    field: string;
+    message: string;
+}
+export declare function validateSkillName(name: string): ValidationIssue[];
+export declare function validateDescription(description: string): ValidationIssue[];
+//# sourceMappingURL=spec.d.ts.map

package/dist/spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec.d.ts","sourceRoot":"","sources":["../src/spec.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,eAAO,MAAM,WAAW,2FAOd,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAErD,eAAO,MAAM,YAAY,QAAsB,CAAC;AAChD,eAAO,MAAM,QAAQ,KAAK,CAAC;AAC3B,eAAO,MAAM,eAAe,OAAO,CAAC;AACpC,eAAO,MAAM,iBAAiB,MAAM,CAAC;AAKrC,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,EAAE,CAmBjE;AAED,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,eAAe,EAAE,CAmB1E"}

package/dist/spec.js

@@ -0,0 +1,63 @@
+/**
+ * Constraints from the Agent Skills specification (agentskills.io), as enforced
+ * by the Claude Skills API and by `package_skill.py` in anthropics/skills.
+ *
+ * Only six frontmatter fields are portable. Claude Code accepts many more, but
+ * a skill carrying any of them fails to upload to claude.ai or the Skills API
+ * with a hard error rather than being ignored — so a generator that wants one
+ * file to work everywhere must emit only these.
+ */
+export const SPEC_FIELDS = [
+    'name',
+    'description',
+    'license',
+    'compatibility',
+    'metadata',
+    'allowed-tools',
+];
+export const NAME_PATTERN = /^[a-z0-9-]{1,64}$/;
+export const NAME_MAX = 64;
+export const DESCRIPTION_MAX = 1024;
+export const COMPATIBILITY_MAX = 500;
+/** Reserved by the spec; a skill named with these is rejected on upload. */
+const RESERVED_WORDS = ['anthropic', 'claude'];
+export function validateSkillName(name) {
+    const issues = [];
+    if (!NAME_PATTERN.test(name)) {
+        issues.push({
+            field: 'name',
+            message: `"${name}" is not a valid skill name. Use 1-${NAME_MAX} characters of ` +
+                'lowercase letters, digits and hyphens only.',
+        });
+    }
+    for (const word of RESERVED_WORDS) {
+        if (name.toLowerCase().includes(word)) {
+            issues.push({
+                field: 'name',
+                message: `Skill names may not contain the reserved word "${word}".`,
+            });
+        }
+    }
+    return issues;
+}
+export function validateDescription(description) {
+    const issues = [];
+    if (!description.trim()) {
+        issues.push({ field: 'description', message: 'description must not be empty.' });
+    }
+    if (description.length > DESCRIPTION_MAX) {
+        issues.push({
+            field: 'description',
+            message: `description is ${description.length} characters; the limit is ${DESCRIPTION_MAX}.`,
+        });
+    }
+    // XML tags are rejected by the Skills API validator.
+    if (/<[a-zA-Z/][^>]*>/.test(description)) {
+        issues.push({
+            field: 'description',
+            message: 'description must not contain XML/HTML tags.',
+        });
+    }
+    return issues;
+}
+//# sourceMappingURL=spec.js.map

package/dist/spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec.js","sourceRoot":"","sources":["../src/spec.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,MAAM;IACN,aAAa;IACb,SAAS;IACT,eAAe;IACf,UAAU;IACV,eAAe;CACP,CAAC;AAIX,MAAM,CAAC,MAAM,YAAY,GAAG,mBAAmB,CAAC;AAChD,MAAM,CAAC,MAAM,QAAQ,GAAG,EAAE,CAAC;AAC3B,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,CAAC;AACpC,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAAG,CAAC;AAErC,4EAA4E;AAC5E,MAAM,cAAc,GAAG,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;AAO/C,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,MAAM,MAAM,GAAsB,EAAE,CAAC;IACrC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC7B,MAAM,CAAC,IAAI,CAAC;YACV,KAAK,EAAE,MAAM;YACb,OAAO,EACL,IAAI,IAAI,sCAAsC,QAAQ,iBAAiB;gBACvE,6CAA6C;SAChD,CAAC,CAAC;IACL,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,cAAc,EAAE,CAAC;QAClC,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YACtC,MAAM,CAAC,IAAI,CAAC;gBACV,KAAK,EAAE,MAAM;gBACb,OAAO,EAAE,kDAAkD,IAAI,IAAI;aACpE,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,WAAmB;IACrD,MAAM,MAAM,GAAsB,EAAE,CAAC;IACrC,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,EAAE,CAAC;QACxB,MAAM,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,gCAAgC,EAAE,CAAC,CAAC;IACnF,CAAC;IACD,IAAI,WAAW,CAAC,MAAM,GAAG,eAAe,EAAE,CAAC;QACzC,MAAM,CAAC,IAAI,CAAC;YACV,KAAK,EAAE,aAAa;YACpB,OAAO,EAAE,kBAAkB,WAAW,CAAC,MAAM,6BAA6B,eAAe,GAAG;SAC7F,CAAC,CAAC;IACL,CAAC;IACD,qDAAqD;IACrD,IAAI,kBAAkB,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC;QACzC,MAAM,CAAC,IAAI,CAAC;YACV,KAAK,EAAE,aAAa;YACpB,OAAO,EAAE,6CAA6C;SACvD,CAAC,CAAC;IACL,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/targets.d.ts

@@ -0,0 +1,42 @@
+import type { ToolManifest } from '@invokable/core';
+/**
+ * Where each agent looks for instructions.
+ *
+ * Two kinds of target, because the ecosystem has two conventions:
+ *
+ * - `skill`: the Agent Skills standard (agentskills.io). One portable SKILL.md
+ *   directory, identical bytes for every one of these tools — that is the point
+ *   of the standard, and why this generator emits only the six spec-portable
+ *   frontmatter fields rather than the wider set Claude Code alone accepts.
+ * - `section`: a shared instruction file (AGENTS.md and friends) that many other
+ *   tools read. We own only a marked region of it and never touch the rest.
+ */
+export type TargetKind = 'skill' | 'section' | 'mdc';
+export interface Target {
+    id: string;
+    label: string;
+    kind: TargetKind;
+    /** Directory (kind `skill`) or file (kind `section`/`mdc`), relative to root. */
+    path: (toolName: string) => string;
+    /** Why this target exists, shown by `--check`. */
+    note: string;
+}
+export declare const TARGETS: readonly Target[];
+export declare const DEFAULT_TARGET_IDS: string[];
+export declare function targetById(id: string): Target | undefined;
+/** Just the `@AGENTS.md` import, for when AGENTS.md carries the content. */
+export declare function renderClaudeMdPointer(): string;
+/**
+ * The section written into a shared instruction file. Deliberately short: these
+ * files load into context on every request for every tool that reads them, so
+ * the detail lives in the skill and this only says enough to route the agent
+ * there and prevent the two expensive mistakes.
+ */
+export declare function renderSection(manifest: ToolManifest, skillPath: string): string;
+/**
+ * Cursor's legacy rule format. `alwaysApply: false` with a description makes it
+ * agent-requested: Cursor pulls it in when the description matches the task,
+ * rather than taxing every request.
+ */
+export declare function renderMdc(manifest: ToolManifest, description: string, skillPath: string): string;
+//# sourceMappingURL=targets.d.ts.map

package/dist/targets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"targets.d.ts","sourceRoot":"","sources":["../src/targets.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEpD;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,SAAS,GAAG,KAAK,CAAC;AAErD,MAAM,WAAW,MAAM;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,UAAU,CAAC;IACjB,iFAAiF;IACjF,IAAI,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;IACnC,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;CACd;AAED,eAAO,MAAM,OAAO,EAAE,SAAS,MAAM,EAmEpC,CAAC;AAEF,eAAO,MAAM,kBAAkB,UAA2B,CAAC;AAE3D,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEzD;AAED,4EAA4E;AAC5E,wBAAgB,qBAAqB,IAAI,MAAM,CAE9C;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAsB/E;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAQhG"}

package/dist/targets.js

@@ -0,0 +1,114 @@
+export const TARGETS = [
+    // ---- Agent Skills standard ----------------------------------------------
+    {
+        id: 'claude-code',
+        label: 'Claude Code',
+        kind: 'skill',
+        path: (t) => `.claude/skills/${t}`,
+        note: 'Claude Code loads project skills from .claude/skills/.',
+    },
+    {
+        id: 'codex',
+        label: 'OpenAI Codex',
+        kind: 'skill',
+        path: (t) => `.codex/skills/${t}`,
+        note: 'Codex loads skills from .codex/skills/.',
+    },
+    {
+        id: 'cursor',
+        label: 'Cursor',
+        kind: 'skill',
+        path: (t) => `.cursor/skills/${t}`,
+        note: 'Cursor 2.4+ loads .cursor/skills/, and also reads .claude/skills/ and .codex/skills/.',
+    },
+    {
+        id: 'gemini',
+        label: 'Gemini CLI',
+        kind: 'skill',
+        path: (t) => `.gemini/skills/${t}`,
+        note: 'Gemini CLI loads skills from .gemini/skills/.',
+    },
+    {
+        id: 'agents-skills',
+        label: 'Cross-agent (.agents)',
+        kind: 'skill',
+        path: (t) => `.agents/skills/${t}`,
+        note: 'Emerging vendor-neutral location; harmless where unsupported.',
+    },
+    // ---- Shared instruction files -------------------------------------------
+    {
+        id: 'agents-md',
+        label: 'AGENTS.md',
+        kind: 'section',
+        path: () => 'AGENTS.md',
+        note: 'Read by 30+ agents (Codex, Copilot, Cursor, Gemini, Jules, Aider, Zed, Windsurf, Devin).',
+    },
+    {
+        id: 'claude-md',
+        label: 'CLAUDE.md',
+        kind: 'section',
+        path: () => 'CLAUDE.md',
+        note: 'Claude Code reads CLAUDE.md, not AGENTS.md.',
+    },
+    {
+        id: 'copilot',
+        label: 'GitHub Copilot',
+        kind: 'section',
+        path: () => '.github/copilot-instructions.md',
+        note: 'Repository-wide Copilot instructions.',
+    },
+    {
+        id: 'cursor-rules',
+        label: 'Cursor rules (legacy)',
+        kind: 'mdc',
+        path: (t) => `.cursor/rules/${t}.mdc`,
+        note: 'For Cursor versions predating skills support.',
+    },
+];
+export const DEFAULT_TARGET_IDS = TARGETS.map((t) => t.id);
+export function targetById(id) {
+    return TARGETS.find((t) => t.id === id);
+}
+/** Just the `@AGENTS.md` import, for when AGENTS.md carries the content. */
+export function renderClaudeMdPointer() {
+    return '@AGENTS.md';
+}
+/**
+ * The section written into a shared instruction file. Deliberately short: these
+ * files load into context on every request for every tool that reads them, so
+ * the detail lives in the skill and this only says enough to route the agent
+ * there and prevent the two expensive mistakes.
+ */
+export function renderSection(manifest, skillPath) {
+    const spending = manifest.commands.filter((c) => c.spends);
+    return `## ${manifest.name}
+
+${manifest.description ?? `The \`${manifest.name}\` CLI.`}
+
+- Full instructions: \`${skillPath}/SKILL.md\`
+- Always pass \`--json\`: one JSON document on stdout, semantic exit code. Never parse stderr.
+- Check \`${manifest.name} doctor --json\` first. If \`.data.auth.ok\` is false, ask the
+  **user** to run \`${manifest.name} login\` — it needs a browser and will hang if you run it.
+- \`status: "error"\` carries \`remediation\` (the exact next command) and \`retryable\`.
+  Never retry exit 7 (rate limited), 4 (insufficient balance) or 20 (declined).
+${spending.length
+        ? `- ${spending.map((c) => `\`${manifest.name} ${c.name}\``).join(', ')} ${spending.length === 1 ? 'spends' : 'spend'} money. ${spending.length === 1 ? 'It exits' : 'They exit'} **10**
+  with \`status: "checkpoint"\`. Print \`.display\` verbatim, ask the user, and only then
+  run \`.next.approve\`. Never pass \`--yes\`.`
+        : ''}`;
+}
+/**
+ * Cursor's legacy rule format. `alwaysApply: false` with a description makes it
+ * agent-requested: Cursor pulls it in when the description matches the task,
+ * rather than taxing every request.
+ */
+export function renderMdc(manifest, description, skillPath) {
+    return `---
+description: ${JSON.stringify(description)}
+alwaysApply: false
+---
+
+${renderSection(manifest, skillPath)}
+`;
+}
+//# sourceMappingURL=targets.js.map

package/dist/targets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"targets.js","sourceRoot":"","sources":["../src/targets.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@invokable/skills",
+  "version": "0.1.0",
+  "description": "Generates portable Agent Skills (SKILL.md) and agent instruction files from an invokable tool schema.",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@invokable/core": "^0.1.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/beinvokable/invokable.git",
+    "directory": "packages/skills"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  }
+}