poe-code 3.0.382 → 3.0.383

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "poe-code",
-  "version": "3.0.382",
+  "version": "3.0.383",
   "description": "CLI tool to configure Poe API for developer workflows.",
   "type": "module",
   "main": "./dist/index.js",

package/packages/toolcraft-openapi/dist/bin/generate.js

@@ -10,7 +10,7 @@ import { withOutputFormat } from "toolcraft-design";
 import { readToolcraftConfig } from "../config.js";
 import { diagnose } from "../diagnose.js";
 import { formatDiagnostics } from "../diagnostics.js";
-import { generate } from "../generate.js";
+import { generate, generateSkill } from "../generate.js";
 import { inspectOpenApiSource } from "../inspect-source.js";
 import { renderOpenApiInspection } from "../render-inspection.js";
 import { parseOpenApiDocument, readOpenApiSourceText } from "../spec-source.js";
@@ -113,31 +113,50 @@ export async function syncGeneratedClient(options, services) {
         ? configResult.diagnostics
         : [...configResult.diagnostics, ...diagnose(configResult.config, document)];
     const effectiveConfig = hasErrorDiagnostics(diagnostics) ? undefined : configResult.config;
-    const generatedFiles = generate(document, { specSha, config: effectiveConfig });
+    const generatedFiles = generate(document, {
+        specSha,
+        config: effectiveConfig
+    });
+    const generatedSkill = generateSkill(document, {
+        config: effectiveConfig,
+        commandName: await inferPackageCommandName(services)
+    });
     const outputDir = path.resolve(services.cwd, options.outputDir);
     const lockPath = path.resolve(services.cwd, options.lockPath);
+    const skillFile = createGeneratedSkillFile(generatedSkill, services.cwd);
     const currentLockContents = await readOpenApiLockText(services.fs, lockPath);
     const desiredLockContents = stringifyOpenApiLock({ specSha });
     const currentFiles = await readGeneratedFiles(services.fs, outputDir);
+    const currentSkillContents = await readOptionalFile(services.fs, skillFile.path);
     const desiredFiles = new Map([
         ...generatedFiles.map((file) => [path.resolve(outputDir, file.path), file.contents]),
         ...createDownloadedSpecFiles(options.input, sourceText).map((file) => [path.resolve(outputDir, file.path), file.contents])
     ]);
+    const currentSkillFiles = currentSkillContents === undefined
+        ? new Map()
+        : new Map([[skillFile.path, currentSkillContents]]);
+    const desiredSkillFiles = new Map([[skillFile.path, skillFile.contents]]);
     const updatedFiles = collectUpdatedFiles(currentFiles, desiredFiles);
+    const updatedSkillFiles = collectUpdatedFiles(currentSkillFiles, desiredSkillFiles);
     const updatedLockFile = currentLockContents === desiredLockContents
         ? undefined
         : { path: lockPath, contents: desiredLockContents, previousContents: currentLockContents };
     const deletedFiles = collectDeletedFiles(currentFiles, desiredFiles);
-    const drifted = updatedFiles.length > 0 || updatedLockFile !== undefined || deletedFiles.length > 0;
+    const drifted = updatedFiles.length > 0 ||
+        updatedSkillFiles.length > 0 ||
+        updatedLockFile !== undefined ||
+        deletedFiles.length > 0;
     if (!options.check && !options.diff && drifted && !hasErrorDiagnostics(diagnostics)) {
         try {
             await writeGeneratedFiles(services.fs, outputDir, updatedFiles);
+            await writeGeneratedSkillFiles(services.fs, services.cwd, updatedSkillFiles);
             await deleteGeneratedFiles(services.fs, outputDir, deletedFiles);
             if (updatedLockFile !== undefined) {
                 await writeOpenApiLock(services.fs, lockPath, { specSha });
             }
         }
         catch (error) {
+            await restoreGeneratedSkillFiles(services.fs, services.cwd, currentSkillFiles, updatedSkillFiles);
             await restoreGeneratedFiles(services.fs, outputDir, currentFiles, updatedFiles, deletedFiles);
             throw error;
         }
@@ -148,8 +167,10 @@ export async function syncGeneratedClient(options, services) {
         diagnostics,
         drifted,
         specSha,
-        updatedFiles: updatedLockFile === undefined ? updatedFiles : [...updatedFiles, updatedLockFile],
-        updatedFileCount: updatedFiles.length + (updatedLockFile === undefined ? 0 : 1)
+        updatedFiles: updatedLockFile === undefined
+            ? [...updatedFiles, ...updatedSkillFiles]
+            : [...updatedFiles, ...updatedSkillFiles, updatedLockFile],
+        updatedFileCount: updatedFiles.length + updatedSkillFiles.length + (updatedLockFile === undefined ? 0 : 1)
     };
 }
 async function readAdjacentToolcraftConfig(input, services) {
@@ -177,6 +198,51 @@ function resolveAdjacentConfigPath(input, cwd) {
 function hasErrorDiagnostics(diagnostics) {
     return diagnostics.some((diagnostic) => diagnostic.severity === "error");
 }
+async function inferPackageCommandName(services) {
+    const packageJsonPath = path.resolve(services.cwd, "package.json");
+    const source = await readOptionalFile(services.fs, packageJsonPath);
+    if (source === undefined) {
+        return undefined;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(source);
+    }
+    catch (error) {
+        throw new UserError(`Failed to parse package.json for generated skill command name: ${getErrorMessage(error)}`, { cause: error });
+    }
+    if (!isPlainObject(parsed)) {
+        return undefined;
+    }
+    const packageName = typeof parsed.name === "string" ? normalizePackageCommandName(parsed.name) : undefined;
+    const bin = parsed.bin;
+    if (typeof bin === "string") {
+        return packageName;
+    }
+    if (!isPlainObject(bin)) {
+        return undefined;
+    }
+    const binNames = Object.keys(bin);
+    if (packageName !== undefined && binNames.includes(packageName)) {
+        return packageName;
+    }
+    return binNames.find((name) => !isMcpBinaryName(name)) ?? binNames[0];
+}
+function normalizePackageCommandName(packageName) {
+    const parts = packageName.split("/");
+    const name = parts[parts.length - 1]?.trim();
+    return name === undefined || name.length === 0 ? undefined : name;
+}
+function isMcpBinaryName(name) {
+    const words = name.toLowerCase().split("-");
+    return words.includes("mcp");
+}
+function createGeneratedSkillFile(skill, cwd) {
+    return {
+        path: path.resolve(cwd, ".claude", "skills", skill.name, "SKILL.md"),
+        contents: skill.contents
+    };
+}
 function renderGeneratedDiff(result, outputDir) {
     const sections = [];
     for (const file of result.updatedFiles) {
@@ -320,6 +386,17 @@ async function readOpenApiLockText(fs, lockPath) {
         throw error;
     }
 }
+async function readOptionalFile(fs, filePath) {
+    try {
+        return await fs.readFile(filePath, "utf8");
+    }
+    catch (error) {
+        if (isNotFoundError(error)) {
+            return undefined;
+        }
+        throw error;
+    }
+}
 function parseOpenApiLock(contents, lockPath) {
     let parsed;
     try {
@@ -440,6 +517,13 @@ async function writeGeneratedFiles(fs, outputDir, filesToWrite) {
         await atomicWriteGeneratedFile(fs, outputDir, file.path, file.contents);
     }
 }
+async function writeGeneratedSkillFiles(fs, cwd, filesToWrite) {
+    for (const file of filesToWrite) {
+        await fs.mkdir(path.dirname(file.path), { recursive: true });
+        await assertSafeProjectPath(fs, cwd, file.path);
+        await atomicWriteProjectFile(fs, cwd, file.path, file.contents);
+    }
+}
 async function assertSafeOutputPath(fs, outputDir, filePath) {
     const canonicalOutputDir = await fs.realpath(outputDir);
     const canonicalFileParent = await fs.realpath(path.dirname(filePath));
@@ -461,6 +545,31 @@ async function assertSafeOutputPath(fs, outputDir, filePath) {
         }
     }
 }
+async function assertSafeProjectPath(fs, cwd, filePath) {
+    const rootPath = path.resolve(cwd);
+    const resolvedFilePath = path.resolve(filePath);
+    const relativePath = path.relative(rootPath, resolvedFilePath);
+    if (relativePath === ".." ||
+        relativePath.startsWith(`..${path.sep}`) ||
+        path.isAbsolute(relativePath)) {
+        throw new Error("Generated skill output must remain inside the project directory.");
+    }
+    const parentOfRoot = path.dirname(rootPath);
+    let currentPath = resolvedFilePath;
+    while (currentPath !== parentOfRoot) {
+        try {
+            if ((await fs.lstat(currentPath)).isSymbolicLink()) {
+                throw new Error("Generated skill output must remain inside the project directory.");
+            }
+        }
+        catch (error) {
+            if (!isNotFoundError(error)) {
+                throw error;
+            }
+        }
+        currentPath = path.dirname(currentPath);
+    }
+}
 async function atomicWriteGeneratedFile(fs, outputDir, filePath, contents) {
     const tempPath = path.join(path.dirname(filePath), `.${path.basename(filePath)}.${randomUUID()}.tmp`);
     let tempCreated = false;
@@ -479,12 +588,43 @@ async function atomicWriteGeneratedFile(fs, outputDir, filePath, contents) {
         throw error;
     }
 }
+async function atomicWriteProjectFile(fs, cwd, filePath, contents) {
+    const tempPath = path.join(path.dirname(filePath), `.${path.basename(filePath)}.${randomUUID()}.tmp`);
+    let tempCreated = false;
+    try {
+        await assertSafeProjectPath(fs, cwd, tempPath);
+        await fs.writeFile(tempPath, contents, { encoding: "utf8", flag: "wx" });
+        tempCreated = true;
+        await assertSafeProjectPath(fs, cwd, filePath);
+        await fs.rename(tempPath, filePath);
+        tempCreated = false;
+    }
+    catch (error) {
+        if (tempCreated || !isAlreadyExistsError(error)) {
+            await fs.unlink(tempPath).catch(() => undefined);
+        }
+        throw error;
+    }
+}
 async function deleteGeneratedFiles(fs, outputDir, filePaths) {
     for (const filePath of filePaths) {
         await assertSafeOutputPath(fs, outputDir, filePath);
         await fs.rm(filePath, { force: true });
     }
 }
+async function restoreGeneratedSkillFiles(fs, cwd, currentFiles, updatedFiles) {
+    for (const file of updatedFiles) {
+        const previousContents = currentFiles.get(file.path);
+        if (previousContents === undefined) {
+            await assertSafeProjectPath(fs, cwd, file.path);
+            await fs.rm(file.path, { force: true });
+            continue;
+        }
+        await fs.mkdir(path.dirname(file.path), { recursive: true });
+        await assertSafeProjectPath(fs, cwd, file.path);
+        await atomicWriteProjectFile(fs, cwd, file.path, previousContents);
+    }
+}
 async function restoreGeneratedFiles(fs, outputDir, currentFiles, updatedFiles, deletedFiles) {
     for (const file of updatedFiles) {
         const previousContents = currentFiles.get(file.path);
@@ -522,6 +662,9 @@ function getErrorCode(error) {
 function getErrorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 function isDirectExecution(moduleUrl, argv) {
     const entryPoint = argv[1];
     if (entryPoint === undefined) {

package/packages/toolcraft-openapi/dist/generate.d.ts

@@ -106,6 +106,10 @@ export interface GeneratedFile {
     path: string;
     contents: string;
 }
+export interface GeneratedSkill {
+    name: string;
+    contents: string;
+}
 export interface GeneratedCommand {
     noun: string;
     verb: string;
@@ -252,6 +256,10 @@ interface SchemaOptionEntry {
 }
 type QueryArraySerialization = "repeat" | "brackets" | "comma" | "pipe";
 export declare function generate(document: OpenApiDocument, options: GenerateOptions): GeneratedFile[];
+export declare function generateSkill(document: OpenApiDocument, options?: {
+    commandName?: string | undefined;
+    config?: ToolcraftConfig | undefined;
+}): GeneratedSkill;
 export declare function collectGeneratedCommands(document: OpenApiDocument, config?: ToolcraftConfig): GeneratedCommand[];
 export declare function collectGeneratedCommand(document: OpenApiDocument, path: string, method: HttpMethod): GeneratedCommand;
 export declare function collectSchemaOptionEntries(param: RenderSchemaOptionsInput): SchemaOptionEntry[];

package/packages/toolcraft-openapi/dist/generate.js

@@ -1,5 +1,5 @@
 import { ToolcraftBugError, UserError } from "toolcraft";
-import { METHOD_DEFAULTS, deriveDisambiguatedVerb, deriveNoun, derivePathDisambiguatedVerb, deriveVerb, isIdentifierName, normalizeNoun, normalizeParamName, toCamelCase, toPascalCase } from "./naming.js";
+import { METHOD_DEFAULTS, deriveDisambiguatedVerb, deriveNoun, derivePathDisambiguatedVerb, deriveVerb, isIdentifierName, normalizeNoun, normalizeParamName, toCliFlag, toCamelCase, toPascalCase } from "./naming.js";
 import { groupByNoun } from "./group-by-noun.js";
 import { renderPreflightBlock, renderRequestShape } from "./interpreter.js";
 import { normalizeOpenApiDocument } from "./normalize-swagger.js";
@@ -132,6 +132,16 @@ export function generate(document, options) {
         createMcpFile()
     ];
 }
+export function generateSkill(document, options = {}) {
+    const normalizedDocument = normalizeOpenApiDocument(document);
+    const commands = collectGeneratedCommands(normalizedDocument, options.config);
+    const label = normalizedDocument.info?.title ?? "Toolcraft";
+    return createSkill({
+        commands,
+        commandName: options.commandName,
+        label
+    });
+}
 export function collectGeneratedCommands(document, config) {
     const normalizedDocument = normalizeOpenApiDocument(document);
     const paths = normalizedDocument.paths;
@@ -150,7 +160,8 @@ function applyConfiguredCommandShape(commands, config) {
         return;
     }
     for (const command of commands) {
-        const match = configured.find((candidate) => candidate.method.method.toUpperCase() === command.method && candidate.method.path === command.path);
+        const match = configured.find((candidate) => candidate.method.method.toUpperCase() === command.method &&
+            candidate.method.path === command.path);
         if (match === undefined) {
             continue;
         }
@@ -340,7 +351,11 @@ function collectParams(document, entry, operation, operationId, auth, responseMo
     const operationParams = collectOperationParameters(document, entry.path, entry.pathItem.parameters ?? [], operation.parameters ?? [], operationId, auth);
     const requestBodyParams = collectRequestBodyParams(document, operation, operationId, entry.method);
     const qualifiedRequestBodyParams = qualifyBodyParamCollisions(requestBodyParams, new Set([...operationParams.params, ...transportParams].map((param) => param.paramName)));
-    const params = [...operationParams.params, ...qualifiedRequestBodyParams.params, ...transportParams];
+    const params = [
+        ...operationParams.params,
+        ...qualifiedRequestBodyParams.params,
+        ...transportParams
+    ];
     const deduped = new Map();
     for (const param of params) {
         const existing = deduped.get(param.paramName);
@@ -352,9 +367,15 @@ function collectParams(document, entry, operation, operationId, auth, responseMo
     return {
         params: [...deduped.values()],
         paramsSchemaOptions: qualifiedRequestBodyParams.paramsSchemaOptions,
-        preflightBlocks: [...operationParams.preflightBlocks, ...qualifiedRequestBodyParams.preflightBlocks],
+        preflightBlocks: [
+            ...operationParams.preflightBlocks,
+            ...qualifiedRequestBodyParams.preflightBlocks
+        ],
         requestFields: [...operationParams.requestFields, ...qualifiedRequestBodyParams.requestFields],
-        sectionRenders: { ...operationParams.sectionRenders, ...qualifiedRequestBodyParams.sectionRenders },
+        sectionRenders: {
+            ...operationParams.sectionRenders,
+            ...qualifiedRequestBodyParams.sectionRenders
+        },
         optionalSections: new Set([
             ...operationParams.optionalSections,
             ...qualifiedRequestBodyParams.optionalSections
@@ -495,7 +516,12 @@ function collectRequestBodyParams(document, operation, operationId, method) {
     }
     const requestBody = expectRequestBody(document, operation.requestBody, operationId, "requestBody");
     const contentEntries = Object.entries(requestBody.content ?? {});
-    const contentEntry = contentEntries.find(([mediaType, mediaTypeObject]) => mediaTypeObject !== undefined && isJsonMediaType(mediaType)) ?? contentEntries.find(([mediaType, mediaTypeObject]) => mediaTypeObject !== undefined && mediaType.toLowerCase() === "application/x-www-form-urlencoded") ?? contentEntries.find(([mediaType, mediaTypeObject]) => mediaTypeObject !== undefined && isTextMediaType(mediaType)) ?? contentEntries.find(([mediaType, mediaTypeObject]) => mediaTypeObject !== undefined && isBinaryMediaType(mediaType)) ?? contentEntries.find(([mediaType, mediaTypeObject]) => mediaTypeObject !== undefined && mediaType.toLowerCase() === "multipart/form-data");
+    const contentEntry = contentEntries.find(([mediaType, mediaTypeObject]) => mediaTypeObject !== undefined && isJsonMediaType(mediaType)) ??
+        contentEntries.find(([mediaType, mediaTypeObject]) => mediaTypeObject !== undefined &&
+            mediaType.toLowerCase() === "application/x-www-form-urlencoded") ??
+        contentEntries.find(([mediaType, mediaTypeObject]) => mediaTypeObject !== undefined && isTextMediaType(mediaType)) ??
+        contentEntries.find(([mediaType, mediaTypeObject]) => mediaTypeObject !== undefined && isBinaryMediaType(mediaType)) ??
+        contentEntries.find(([mediaType, mediaTypeObject]) => mediaTypeObject !== undefined && mediaType.toLowerCase() === "multipart/form-data");
     const content = contentEntry?.[1];
     const requestMediaType = contentEntry?.[0];
     const bodyMode = requestMediaType?.toLowerCase() === "application/x-www-form-urlencoded"
@@ -537,7 +563,8 @@ function collectRequestBodyParams(document, operation, operationId, method) {
     }
     if ((schema.additionalProperties !== undefined && schema.additionalProperties !== false) ||
         schema.properties === undefined) {
-        return createCollectedRequestBodyParams([createJsonBodyField({
+        return createCollectedRequestBodyParams([
+            createJsonBodyField({
                 document,
                 name: "body",
                 description: schema.description ?? requestBody.description,
@@ -546,7 +573,8 @@ function collectRequestBodyParams(document, operation, operationId, method) {
                 operationId,
                 context: "requestBody",
                 location: "body"
-            })], bodyOptional, requestBody.description, "inline", undefined, bodyMode, multipartBinaryFields);
+            })
+        ], bodyOptional, requestBody.description, "inline", undefined, bodyMode, multipartBinaryFields);
     }
     const required = new Set(schema.required ?? []);
     const assemblies = [];
@@ -565,12 +593,14 @@ function collectRequestBodyParams(document, operation, operationId, method) {
                 params: [],
                 paramsSchemaOptions: schema.additionalProperties === false ? { additionalProperties: false } : undefined,
                 preflightBlocks: [],
-                requestFields: [{
+                requestFields: [
+                    {
                         location: "body",
                         wireName: "body",
                         value: { kind: "emptyObject" },
                         omitWhenUndefinedReference: { kind: "resolved", resolvedName: "emptyBody" }
-                    }],
+                    }
+                ],
                 sectionRenders: { body: "inline" },
                 optionalSections: new Set(),
                 requestBodyDescription: requestBody.description,
@@ -633,7 +663,9 @@ function createGeneratedParameter(document, parameter, operationId, auth) {
     if (parameter.in === "query" &&
         parameter.style === "deepObject" &&
         (getCompositionKeyword(schema) !== undefined ||
-            (schema.type === "array" && schema.items !== undefined && isComplexJsonBodySchema(document, schema.items, operationId, `${context} items`)))) {
+            (schema.type === "array" &&
+                schema.items !== undefined &&
+                isComplexJsonBodySchema(document, schema.items, operationId, `${context} items`)))) {
         return createJsonQueryField({
             document,
             name: parameter.name,
@@ -973,19 +1005,25 @@ function createPathArrayParam(options) {
     const definition = createParamDefinition(options.document, options.schema, options.operationId, options.context);
     const paramName = options.name;
     return {
-        params: [{
+        params: [
+            {
                 paramName,
                 sourceName: options.name,
                 location: "path",
                 description: options.description,
                 optional: false,
                 definition
-            }],
+            }
+        ],
         preflightBlocks: [],
         requestField: {
             location: "path",
             wireName: options.name,
-            value: { kind: "queryArray", reference: { kind: "param", paramName }, serialization: "comma" },
+            value: {
+                kind: "queryArray",
+                reference: { kind: "param", paramName },
+                serialization: "comma"
+            },
             omitWhenUndefinedReference: { kind: "param", paramName }
         }
     };
@@ -1137,11 +1175,16 @@ function isAsciiDigit(character) {
 }
 function isJsonMediaType(mediaType) {
     const normalized = mediaType.toLowerCase();
-    return normalized === "*/*" || normalized === "text/json" || normalized.includes("application/json") || normalized.includes("+json");
+    return (normalized === "*/*" ||
+        normalized === "text/json" ||
+        normalized.includes("application/json") ||
+        normalized.includes("+json"));
 }
 function isTextMediaType(mediaType) {
     const normalized = mediaType.toLowerCase();
-    return normalized.startsWith("text/") || normalized === "plain/text" || normalized === "application/jwt";
+    return (normalized.startsWith("text/") ||
+        normalized === "plain/text" ||
+        normalized === "application/jwt");
 }
 function isBinaryMediaType(mediaType) {
     const normalized = mediaType.toLowerCase();
@@ -1354,8 +1397,7 @@ function normalizeNullableTypeArray(schema) {
 }
 function getCompositionKeyword(schema) {
     for (const keyword of ["allOf", "anyOf", "oneOf"]) {
-        if (Object.prototype.hasOwnProperty.call(schema, keyword) &&
-            schema[keyword] !== undefined) {
+        if (Object.prototype.hasOwnProperty.call(schema, keyword) && schema[keyword] !== undefined) {
             return keyword;
         }
     }
@@ -1702,7 +1744,9 @@ function renderObjectKey(name) {
 }
 function createSafeGeneratedNoun(noun) {
     const normalized = normalizeNoun(noun);
-    return isTypeScriptIdentifier(toCamelCase(normalized)) ? normalized : `api-${normalized || "operation"}`;
+    return isTypeScriptIdentifier(toCamelCase(normalized))
+        ? normalized
+        : `api-${normalized || "operation"}`;
 }
 export function collectSchemaOptionEntries(param) {
     return SCHEMA_OPTION_SOURCES.flatMap(({ key, get }) => {
@@ -1916,6 +1960,181 @@ function createMcpFile() {
         ].join("\n")
     };
 }
+function createSkill(options) {
+    const commandName = options.commandName ?? "<cli>";
+    const groups = groupByNoun(options.commands);
+    const skillName = createSkillName(options.commandName ?? options.label);
+    const description = createSkillDescription(options.label, groups.map((group) => group.noun));
+    const quickStartCommands = collectQuickStartCommands(commandName, options.commands);
+    const lines = [
+        "---",
+        `name: ${skillName}`,
+        `description: ${JSON.stringify(description)}`,
+        "---",
+        "",
+        `# ${options.label}`,
+        "",
+        `Use \`${commandName}\` for CLI examples. If MCP tools from this package are registered, prefer them for structured calls; their names mirror the command groups and verbs below.`,
+        "",
+        "## Quick Start",
+        "",
+        "```sh",
+        `${commandName} --help`,
+        ...quickStartCommands,
+        "```",
+        "",
+        "## Command Groups",
+        ""
+    ];
+    if (groups.length === 0) {
+        lines.push("No OpenAPI operations were generated.", "");
+    }
+    else {
+        for (const group of groups) {
+            lines.push(`- \`${group.noun}\`: ${group.commands.map((command) => `\`${command.verb}\``).join(", ")}`);
+        }
+        lines.push("");
+    }
+    const catalogCommands = options.commands.slice(0, 80);
+    if (catalogCommands.length > 0) {
+        lines.push("## Commands", "");
+        for (const command of catalogCommands) {
+            lines.push(renderSkillCommandCatalogLine(commandName, command));
+        }
+        const omittedCount = options.commands.length - catalogCommands.length;
+        if (omittedCount > 0) {
+            lines.push(`- ${omittedCount} more commands omitted. Run \`${commandName} --help\` and group help for the full surface.`);
+        }
+        lines.push("");
+    }
+    const exampleBlocks = options.commands.flatMap((command) => (command.examples ?? []).map((example) => ({ command, example })));
+    if (exampleBlocks.length > 0) {
+        lines.push("## Examples", "");
+        for (const { command, example } of exampleBlocks.slice(0, 5)) {
+            lines.push(`### ${oneLine(example.title)}`, "");
+            lines.push("```sh", renderSkillCommandLine(commandName, command), "```", "");
+            lines.push("Params:");
+            lines.push("```json", `${JSON.stringify(example.params, null, 2)}`, "```", "");
+        }
+    }
+    lines.push("## Output", "", "Commands return structured output. Use command or group `--help` to inspect the full generated option list before calling commands with complex request bodies.", "");
+    return {
+        name: skillName,
+        contents: lines.join("\n")
+    };
+}
+function createSkillName(label) {
+    const normalized = normalizeNoun(label);
+    const fallback = normalized.length === 0 ? "openapi-tools" : normalized;
+    if (fallback.length <= 63) {
+        return fallback;
+    }
+    return trimTrailingHyphens(fallback.slice(0, 63));
+}
+function createSkillDescription(label, groupNames) {
+    const groupSummary = groupNames.length === 0
+        ? ""
+        : ` Includes command groups: ${groupNames.slice(0, 12).join(", ")}${groupNames.length > 12 ? ", and more" : ""}.`;
+    return `Use ${label} generated OpenAPI CLI or MCP tools. Use when Codex needs to call this API, inspect available commands, or run generated operations from the OpenAPI specification.${groupSummary}`;
+}
+function collectQuickStartCommands(commandName, commands) {
+    const lines = [];
+    const firstGroup = groupByNoun(commands)[0];
+    if (firstGroup !== undefined) {
+        lines.push(`${commandName} ${firstGroup.noun} --help`);
+    }
+    for (const command of commands) {
+        if (lines.length >= 4) {
+            break;
+        }
+        if (!isReadCommand(command)) {
+            continue;
+        }
+        const requiredNamedParams = command.params.filter((param) => !param.optional &&
+            param.global !== true &&
+            param.location !== "transport" &&
+            !command.positional.includes(param.paramName));
+        if (requiredNamedParams.length === 0) {
+            lines.push(renderSkillCommandLine(commandName, command));
+        }
+    }
+    return lines;
+}
+function isReadCommand(command) {
+    return command.method === "GET" || command.method === "HEAD" || command.method === "OPTIONS";
+}
+function renderSkillCommandCatalogLine(commandName, command) {
+    const description = command.description === undefined ? "" : ` - ${truncate(oneLine(command.description), 140)}`;
+    return `- \`${renderSkillCommandLine(commandName, command)}\`${description} (\`${command.method} ${command.path}\`)`;
+}
+function renderSkillCommandLine(commandName, command) {
+    const parts = [
+        commandName,
+        command.noun,
+        command.verb,
+        ...command.positional.map((paramName) => `<${paramName}>`)
+    ];
+    const requiredFlags = command.params.filter((param) => !param.optional &&
+        param.global !== true &&
+        param.location !== "transport" &&
+        !command.positional.includes(param.paramName));
+    const renderedFlags = requiredFlags
+        .filter((param) => param.definition.kind !== "object")
+        .slice(0, 4)
+        .map(renderRequiredSkillFlag);
+    parts.push(...renderedFlags);
+    if (requiredFlags.length > renderedFlags.length) {
+        parts.push("[required options...]");
+    }
+    return parts.join(" ");
+}
+function renderRequiredSkillFlag(param) {
+    const flag = `--${toCliFlag(param.paramName)}`;
+    if (param.definition.kind === "boolean") {
+        return flag;
+    }
+    if (param.definition.kind === "array") {
+        return `${flag} <value...>`;
+    }
+    if (param.definition.kind === "enum") {
+        return `${flag} <${param.definition.enumValues.map((value) => String(value)).join("|")}>`;
+    }
+    return `${flag} <value>`;
+}
+function oneLine(value) {
+    const words = [];
+    let current = "";
+    for (const character of value) {
+        if (isWhitespace(character)) {
+            if (current.length > 0) {
+                words.push(current);
+                current = "";
+            }
+            continue;
+        }
+        current += character;
+    }
+    if (current.length > 0) {
+        words.push(current);
+    }
+    return words.join(" ");
+}
+function truncate(value, maxLength) {
+    if (value.length <= maxLength) {
+        return value;
+    }
+    return `${value.slice(0, Math.max(0, maxLength - 1)).trimEnd()}...`;
+}
+function trimTrailingHyphens(value) {
+    let endIndex = value.length;
+    while (endIndex > 0 && value[endIndex - 1] === "-") {
+        endIndex -= 1;
+    }
+    return value.slice(0, endIndex);
+}
+function isWhitespace(value) {
+    return value === " " || value === "\n" || value === "\r" || value === "\t" || value === "\f";
+}
 function createGeneratedTypeScriptFile(bodyLines, metadataLines = []) {
     return [...createGeneratedTypeScriptFileLines(metadataLines), ...bodyLines].join("\n");
 }

package/packages/toolcraft-openapi/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { defineApiCommand } from "./api-command.js";
 export { defineClient } from "./define-client.js";
-export { generate } from "./generate.js";
-export type { GenerateOptions, GeneratedFile, OpenApiDocument } from "./generate.js";
+export { generate, generateSkill } from "./generate.js";
+export type { GeneratedFile, GeneratedSkill, GenerateOptions, OpenApiDocument } from "./generate.js";
 export { SUPPORTED_TOOLCRAFT_EDITION, mergeToolcraftConfig, readToolcraftConfig, validateToolcraftConfig } from "./config.js";
 export type { ToolcraftConfig, ToolcraftMethodConfig, ToolcraftResourceConfig } from "./config.js";
 export { diagnose } from "./diagnose.js";

package/packages/toolcraft-openapi/dist/index.js

@@ -1,6 +1,6 @@
 export { defineApiCommand } from "./api-command.js";
 export { defineClient } from "./define-client.js";
-export { generate } from "./generate.js";
+export { generate, generateSkill } from "./generate.js";
 export { SUPPORTED_TOOLCRAFT_EDITION, mergeToolcraftConfig, readToolcraftConfig, validateToolcraftConfig } from "./config.js";
 export { diagnose } from "./diagnose.js";
 export { DIAGNOSTIC_CODES, formatDiagnostic, formatDiagnostics } from "./diagnostics.js";