@skillit/cli 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-present Pradeep Mouli
+
+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,44 @@
+# @skillit/cli
+
+> Extract CLI command structure from commander/yargs for AI agent skill generation.
+
+Part of the [skillit](https://github.com/pradeepmouli/skillit) ecosystem.
+
+## Features
+
+- **Commander introspection** — enumerate commands, options, arguments from a Program object
+- **`--help` fallback** — parse standard help text for any CLI framework
+- **Flag-to-property correlation** — merge JSDoc tags from typed options interfaces into CLI metadata
+- **Token-budgeted output** — generated skills fit LLM context windows
+
+## Install
+
+```bash
+pnpm add -D @skillit/cli
+```
+
+## Usage
+
+```typescript
+import { extractCliSkill, writeCliSkill } from '@skillit/cli';
+
+const skill = await extractCliSkill({
+  program, // commander Program object
+  metadata: { name: 'my-tool', keywords: ['build', 'deploy'] }
+});
+
+console.log(skill.audit); // structured C1-C8 findings with suggestions
+
+writeCliSkill(skill, {
+  outDir: 'skills',
+  installTargets: ['.claude/skills', '.agents/skills']
+});
+```
+
+`writeCliSkill()` writes the generated skill, installs it into any configured
+agent discovery directories, and adds the bundled `skillit-cli-docs` guidance
+skill to those install targets when install targets are enabled.
+
+## License
+
+MIT

package/dist/audit.d.ts

@@ -0,0 +1,14 @@
+import type { ExtractedSkill } from '@skillit/core';
+export interface CliAuditIssue {
+    readonly code: `C${number}`;
+    readonly severity: 'warning' | 'alert';
+    readonly message: string;
+    readonly suggestion: string;
+    readonly location?: {
+        readonly command?: string;
+        readonly option?: string;
+        readonly argument?: string;
+    };
+}
+export declare function runCliAudit(skill: ExtractedSkill): CliAuditIssue[];
+//# sourceMappingURL=audit.d.ts.map

package/dist/audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../src/audit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAIV,cAAc,EACf,MAAM,eAAe,CAAC;AAEvB,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,IAAI,MAAM,EAAE,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,SAAS,GAAG,OAAO,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE;QAClB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;KAC5B,CAAC;CACH;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,cAAc,GAAG,aAAa,EAAE,CASlE"}

package/dist/audit.js

@@ -0,0 +1,101 @@
+export function runCliAudit(skill) {
+    const issues = [];
+    for (const surface of skill.configSurfaces ?? []) {
+        if (surface.sourceType !== 'cli')
+            continue;
+        auditSurface(surface, issues, surface.name);
+    }
+    return issues;
+}
+function auditSurface(surface, issues, commandPath) {
+    if (!surface.description.trim()) {
+        issues.push({
+            code: 'C1',
+            severity: 'warning',
+            message: `Command "${commandPath}" has no description.`,
+            suggestion: `Add .description('[One sentence: what this command does and why]') to Commander command`,
+            location: { command: commandPath }
+        });
+    }
+    if (!surface.usage?.trim()) {
+        issues.push({
+            code: 'C3',
+            severity: 'alert',
+            message: `Command "${commandPath}" has no usage or examples.`,
+            suggestion: "Add .usage('[command] [options] <required-arg>') and .addHelpText('after', 'Examples:\\n  $ [command] [typical-args]')",
+            location: { command: commandPath }
+        });
+    }
+    if (!(surface.useWhen?.length ?? 0)) {
+        issues.push({
+            code: 'C8',
+            severity: 'warning',
+            message: `Command "${commandPath}" has no useWhen guidance.`,
+            suggestion: 'Add @useWhen to the config interface or .addHelpText() with scenario: when to prefer this command over alternatives',
+            location: { command: commandPath }
+        });
+    }
+    for (const option of surface.options) {
+        auditOption(commandPath, option, issues);
+    }
+    for (const argument of surface.arguments ?? []) {
+        auditArgument(commandPath, argument, issues);
+    }
+    for (const subcommand of surface.subcommands ?? []) {
+        const subcommandPath = `${commandPath} ${subcommand.name}`;
+        if (!subcommand.description.trim()) {
+            issues.push({
+                code: 'C5',
+                severity: 'warning',
+                message: `Subcommand "${subcommandPath}" has no description.`,
+                suggestion: `Add .description('[One sentence]') to subcommand '${subcommand.name}'`,
+                location: { command: subcommandPath }
+            });
+        }
+        auditSurface(subcommand, issues, subcommandPath);
+    }
+}
+function auditOption(commandName, option, issues) {
+    if (!option.description.trim()) {
+        issues.push({
+            code: 'C2',
+            severity: 'warning',
+            message: `Option "${option.cliFlag ?? option.name}" on "${commandName}" has no description.`,
+            suggestion: "Add description to .option(): .option('[flag]', '[What this option controls — effect on behavior, not the type]')",
+            location: { command: commandName, option: option.cliFlag ?? option.name }
+        });
+        issues.push({
+            code: 'C7',
+            severity: 'warning',
+            message: `Option "${option.cliFlag ?? option.name}" on "${commandName}" is undocumented after CLI/config correlation.`,
+            suggestion: `Neither --help text nor typed config interface has a description for '${option.name}'. Add JSDoc to the config interface property or .option() description.`,
+            location: { command: commandName, option: option.cliFlag ?? option.name }
+        });
+    }
+    if (option.envVar &&
+        !includesEnvVar(option.description, option.envVar) &&
+        !includesEnvVar(option.remarks, option.envVar)) {
+        issues.push({
+            code: 'C6',
+            severity: 'alert',
+            message: `Option "${option.cliFlag ?? option.name}" on "${commandName}" supports ${option.envVar} but does not document it.`,
+            suggestion: `Add .env('${option.envVar}') to option or document in help text: 'Also settable via ${option.envVar}'`,
+            location: { command: commandName, option: option.cliFlag ?? option.name }
+        });
+    }
+}
+function auditArgument(commandName, argument, issues) {
+    if (argument.description.trim())
+        return;
+    issues.push({
+        code: 'C4',
+        severity: 'warning',
+        message: `Argument "${argument.name}" on "${commandName}" has no description.`,
+        suggestion: `Add .argument('<${argument.name}>', '[What this argument represents — expected format/values]')`,
+        location: { command: commandName, argument: argument.name }
+    });
+}
+function includesEnvVar(text, envVar) {
+    return typeof text === 'string' && text.includes(envVar);
+}
+//# sourceMappingURL=audit.js.map

package/dist/audit.js.map

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

package/dist/correlator.d.ts

@@ -0,0 +1,21 @@
+import type { ExtractedConfigSurface } from '@skillit/core';
+/**
+ * Merges JSDoc tag metadata from a typed config interface surface into CLI
+ * option metadata extracted from commander/--help output.
+ *
+ * The CLI surface is treated as authoritative for structural fields (flags,
+ * description, required, defaultValue). The config surface contributes rich
+ * JSDoc metadata (remarks, useWhen, avoidWhen, pitfalls, category) that the
+ * CLI help text does not capture.
+ *
+ * @param cliSurface   - The surface extracted from CLI introspection/help parsing
+ * @param configSurface - The surface extracted from a typed config interface (optional)
+ * @returns A new ExtractedConfigSurface combining both sources
+ *
+ * @category Correlation
+ * @useWhen
+ * - You have both CLI surfaces (from introspection/help) and typed config interfaces (from TypeDoc)
+ * - You want JSDoc @useWhen/@avoidWhen/@never tags to appear on CLI options in the generated skill
+ */
+export declare function correlateFlags(cliSurface: ExtractedConfigSurface, configSurface: ExtractedConfigSurface | undefined): ExtractedConfigSurface;
+//# sourceMappingURL=correlator.d.ts.map

package/dist/correlator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"correlator.d.ts","sourceRoot":"","sources":["../src/correlator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAyB,MAAM,eAAe,CAAC;AAEnF;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAC5B,UAAU,EAAE,sBAAsB,EAClC,aAAa,EAAE,sBAAsB,GAAG,SAAS,GAChD,sBAAsB,CA0CxB"}

package/dist/correlator.js

@@ -0,0 +1,69 @@
+/**
+ * Merges JSDoc tag metadata from a typed config interface surface into CLI
+ * option metadata extracted from commander/--help output.
+ *
+ * The CLI surface is treated as authoritative for structural fields (flags,
+ * description, required, defaultValue). The config surface contributes rich
+ * JSDoc metadata (remarks, useWhen, avoidWhen, pitfalls, category) that the
+ * CLI help text does not capture.
+ *
+ * @param cliSurface   - The surface extracted from CLI introspection/help parsing
+ * @param configSurface - The surface extracted from a typed config interface (optional)
+ * @returns A new ExtractedConfigSurface combining both sources
+ *
+ * @category Correlation
+ * @useWhen
+ * - You have both CLI surfaces (from introspection/help) and typed config interfaces (from TypeDoc)
+ * - You want JSDoc @useWhen/@avoidWhen/@never tags to appear on CLI options in the generated skill
+ */
+export function correlateFlags(cliSurface, configSurface) {
+    if (!configSurface)
+        return cliSurface;
+    // Build lookup: lowercase property name → config option
+    const configLookup = new Map();
+    for (const opt of configSurface.options) {
+        configLookup.set(opt.name.toLowerCase(), opt);
+    }
+    // Merge each CLI option with matching config property
+    const mergedOptions = cliSurface.options.map((cliOpt) => {
+        const configOpt = configLookup.get(cliOpt.name.toLowerCase());
+        if (!configOpt)
+            return cliOpt;
+        return {
+            // CLI is authoritative for structural/presentation fields
+            ...cliOpt,
+            // Use config description as fallback when CLI description is empty
+            description: cliOpt.description || configOpt.description,
+            // Config provides JSDoc-enriched metadata
+            remarks: cliOpt.remarks ?? configOpt.remarks,
+            useWhen: cliOpt.useWhen ?? configOpt.useWhen,
+            avoidWhen: cliOpt.avoidWhen ?? configOpt.avoidWhen,
+            pitfalls: cliOpt.pitfalls ?? configOpt.pitfalls,
+            category: cliOpt.category ?? configOpt.category
+        };
+    });
+    // Merge command-level tags from config surface into CLI surface
+    return {
+        ...cliSurface,
+        options: mergedOptions,
+        useWhen: cliSurface.useWhen ?? configSurface.useWhen,
+        avoidWhen: cliSurface.avoidWhen ?? configSurface.avoidWhen,
+        pitfalls: cliSurface.pitfalls ?? configSurface.pitfalls,
+        remarks: cliSurface.remarks ?? configSurface.remarks,
+        // A config-provided usage example (e.g. from JSDoc @example) is preferred
+        // over commander's synthesized boilerplate (`[options]`, `[options] <args>`).
+        usage: isBoilerplateUsage(cliSurface.usage)
+            ? (configSurface.usage ?? cliSurface.usage)
+            : (cliSurface.usage ?? configSurface.usage)
+    };
+}
+/**
+ * Whether a usage string is commander's synthesized default (no authored
+ * example), e.g. `[options]`, `[options] [command]`, `[options] <file>`.
+ */
+function isBoilerplateUsage(usage) {
+    if (usage === undefined)
+        return true;
+    return usage.match(/^\[options\]([\s]+[<[].*)?$/) !== null;
+}
+//# sourceMappingURL=correlator.js.map

package/dist/correlator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"correlator.js","sourceRoot":"","sources":["../src/correlator.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,cAAc,CAC5B,UAAkC,EAClC,aAAiD;IAEjD,IAAI,CAAC,aAAa;QAAE,OAAO,UAAU,CAAC;IAEtC,wDAAwD;IACxD,MAAM,YAAY,GAAG,IAAI,GAAG,EAAiC,CAAC;IAC9D,KAAK,MAAM,GAAG,IAAI,aAAa,CAAC,OAAO,EAAE,CAAC;QACxC,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,GAAG,CAAC,CAAC;IAChD,CAAC;IAED,sDAAsD;IACtD,MAAM,aAAa,GAA4B,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE;QAC/E,MAAM,SAAS,GAAG,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;QAC9D,IAAI,CAAC,SAAS;YAAE,OAAO,MAAM,CAAC;QAE9B,OAAO;YACL,0DAA0D;YAC1D,GAAG,MAAM;YACT,mEAAmE;YACnE,WAAW,EAAE,MAAM,CAAC,WAAW,IAAI,SAAS,CAAC,WAAW;YACxD,0CAA0C;YAC1C,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,SAAS,CAAC,OAAO;YAC5C,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,SAAS,CAAC,OAAO;YAC5C,SAAS,EAAE,MAAM,CAAC,SAAS,IAAI,SAAS,CAAC,SAAS;YAClD,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,SAAS,CAAC,QAAQ;YAC/C,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,SAAS,CAAC,QAAQ;SAChD,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,gEAAgE;IAChE,OAAO;QACL,GAAG,UAAU;QACb,OAAO,EAAE,aAAa;QACtB,OAAO,EAAE,UAAU,CAAC,OAAO,IAAI,aAAa,CAAC,OAAO;QACpD,SAAS,EAAE,UAAU,CAAC,SAAS,IAAI,aAAa,CAAC,SAAS;QAC1D,QAAQ,EAAE,UAAU,CAAC,QAAQ,IAAI,aAAa,CAAC,QAAQ;QACvD,OAAO,EAAE,UAAU,CAAC,OAAO,IAAI,aAAa,CAAC,OAAO;QACpD,0EAA0E;QAC1E,8EAA8E;QAC9E,KAAK,EAAE,kBAAkB,CAAC,UAAU,CAAC,KAAK,CAAC;YACzC,CAAC,CAAC,CAAC,aAAa,CAAC,KAAK,IAAI,UAAU,CAAC,KAAK,CAAC;YAC3C,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,IAAI,aAAa,CAAC,KAAK,CAAC;KAC9C,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,SAAS,kBAAkB,CAAC,KAAyB;IACnD,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACrC,OAAO,KAAK,CAAC,KAAK,CAAC,6BAA6B,CAAC,KAAK,IAAI,CAAC;AAC7D,CAAC"}

package/dist/extract.d.ts

@@ -0,0 +1,37 @@
+import { type ExtractedSkill, type ExtractedConfigSurface, type SkillRenderOptions, type SkillWriteOptions } from '@skillit/core';
+export interface CliExtractionOptions {
+    /** Commander program object (preferred) */
+    program?: any;
+    /** Help text per command (fallback) */
+    helpTexts?: Record<string, string>;
+    /** Package metadata */
+    metadata?: {
+        name?: string;
+        description?: string;
+        keywords?: string[];
+        repository?: string;
+        author?: string;
+    };
+    /** Config surfaces from TypeDoc for JSDoc correlation */
+    configSurfaces?: ExtractedConfigSurface[];
+}
+export interface CliWriteOptions extends SkillWriteOptions, Partial<Pick<SkillRenderOptions, 'includeExamples' | 'includeSignatures' | 'maxTokens' | 'namePrefix' | 'license'>> {
+}
+/**
+ * Extract a structured skill from a CLI program.
+ *
+ * Runs the three-phase pipeline: introspect (or parse help) → correlate with typed interfaces → produce ExtractedSkill.
+ *
+ * @category Extraction
+ * @useWhen
+ * - You have a Commander program and want to generate a skill from its command structure
+ * - You have raw --help output and no runtime access to the program object
+ * @avoidWhen
+ * - Your CLI is built with a framework other than Commander — use parseHelpOutput directly instead
+ * @never
+ * - NEVER pass both `program` and `helpTexts` — program takes precedence and helpTexts is silently ignored
+ * - NEVER forget to pass configSurfaces when you have typed option interfaces — JSDoc metadata won't be correlated
+ */
+export declare function extractCliSkill(options: CliExtractionOptions): Promise<ExtractedSkill>;
+export declare function writeCliSkill(skill: ExtractedSkill, options: CliWriteOptions): import("@skillit/core").SkillWriteResult[];
+//# sourceMappingURL=extract.d.ts.map

package/dist/extract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract.d.ts","sourceRoot":"","sources":["../src/extract.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,sBAAsB,EAE3B,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACvB,MAAM,eAAe,CAAC;AAMvB,MAAM,WAAW,oBAAoB;IACnC,2CAA2C;IAC3C,OAAO,CAAC,EAAE,GAAG,CAAC;IACd,uCAAuC;IACvC,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,uBAAuB;IACvB,QAAQ,CAAC,EAAE;QACT,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;QACpB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,yDAAyD;IACzD,cAAc,CAAC,EAAE,sBAAsB,EAAE,CAAC;CAC3C;AAED,MAAM,WAAW,eACf,SACE,iBAAiB,EACjB,OAAO,CACL,IAAI,CACF,kBAAkB,EAClB,iBAAiB,GAAG,mBAAmB,GAAG,WAAW,GAAG,YAAY,GAAG,SAAS,CACjF,CACF;CAAG;AAER;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,cAAc,CAAC,CAsE5F;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,eAAe,8CA8B5E"}

package/dist/extract.js

@@ -0,0 +1,133 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { renderSkills, writeSkills } from '@skillit/core';
+import { introspectCommander } from './introspect-commander.js';
+import { parseHelpOutput } from './help-parser.js';
+import { correlateFlags } from './correlator.js';
+import { runCliAudit } from './audit.js';
+/**
+ * Extract a structured skill from a CLI program.
+ *
+ * Runs the three-phase pipeline: introspect (or parse help) → correlate with typed interfaces → produce ExtractedSkill.
+ *
+ * @category Extraction
+ * @useWhen
+ * - You have a Commander program and want to generate a skill from its command structure
+ * - You have raw --help output and no runtime access to the program object
+ * @avoidWhen
+ * - Your CLI is built with a framework other than Commander — use parseHelpOutput directly instead
+ * @never
+ * - NEVER pass both `program` and `helpTexts` — program takes precedence and helpTexts is silently ignored
+ * - NEVER forget to pass configSurfaces when you have typed option interfaces — JSDoc metadata won't be correlated
+ */
+export async function extractCliSkill(options) {
+    const { program, helpTexts, metadata = {}, configSurfaces = [] } = options;
+    // Extract command structure (introspection or help)
+    let cliSurfaces = [];
+    if (program !== undefined) {
+        cliSurfaces = introspectCommander(program);
+    }
+    else if (helpTexts !== undefined) {
+        cliSurfaces = Object.entries(helpTexts).map(([commandName, text]) => parseHelpOutput(text, commandName));
+    }
+    // Correlate with typed interfaces
+    // Build lookup from config surfaces by their name (case-insensitive)
+    const configSurfaceLookup = new Map();
+    for (const surface of configSurfaces) {
+        configSurfaceLookup.set(surface.name.toLowerCase(), surface);
+    }
+    // For each CLI surface, find a matching config surface by convention:
+    // command "generate" → look for "GenerateOptions" or "generateoptions" (case-insensitive)
+    const correlatedCliSurfaces = cliSurfaces.map((cliSurface) => {
+        const commandNameLower = cliSurface.name.toLowerCase();
+        // Try exact name match first
+        let matchingConfig = configSurfaceLookup.get(commandNameLower);
+        // If not found, try "<commandName>options" convention
+        if (!matchingConfig) {
+            matchingConfig = configSurfaceLookup.get(`${commandNameLower}options`);
+        }
+        // Call correlateFlags to merge JSDoc
+        return correlateFlags(cliSurface, matchingConfig);
+    });
+    // Collect non-CLI config surfaces (sourceType === 'config') from configSurfaces
+    const nonCliConfigSurfaces = configSurfaces.filter((s) => s.sourceType !== 'cli');
+    // Build the final configSurfaces array: correlated CLI surfaces + non-CLI config surfaces
+    const allConfigSurfaces = [
+        ...correlatedCliSurfaces,
+        ...nonCliConfigSurfaces
+    ];
+    // Build ExtractedSkill with empty functions/classes/types/enums/variables
+    // but populated configSurfaces
+    const skillWithoutAudit = {
+        name: metadata.name ?? '',
+        description: metadata.description ?? '',
+        keywords: metadata.keywords,
+        repository: metadata.repository,
+        author: metadata.author,
+        functions: [],
+        classes: [],
+        types: [],
+        enums: [],
+        variables: [],
+        examples: [],
+        ...(allConfigSurfaces.length > 0 ? { configSurfaces: allConfigSurfaces } : {})
+    };
+    const auditIssues = runCliAudit(skillWithoutAudit);
+    return {
+        ...skillWithoutAudit,
+        audit: { status: 'completed', issues: auditIssues },
+        auditIssues
+    };
+}
+export function writeCliSkill(skill, options) {
+    const renderedSkills = renderSkills([skill], {
+        outDir: options.outDir,
+        ...(options.includeExamples !== undefined ? { includeExamples: options.includeExamples } : {}),
+        ...(options.includeSignatures !== undefined
+            ? { includeSignatures: options.includeSignatures }
+            : {}),
+        ...(options.maxTokens !== undefined ? { maxTokens: options.maxTokens } : {}),
+        ...(options.namePrefix !== undefined ? { namePrefix: options.namePrefix } : {}),
+        ...(options.license !== undefined ? { license: options.license } : {})
+    });
+    const installTargets = options.installTargets ?? [];
+    const results = writeSkills(renderedSkills, {
+        outDir: options.outDir,
+        installTargets,
+        ...(options.includeOutDir !== undefined ? { includeOutDir: options.includeOutDir } : {})
+    });
+    if (installTargets.length === 0) {
+        return results;
+    }
+    return [
+        ...results,
+        ...writeSkills([loadBundledCliGuidanceSkill()], {
+            outDir: options.outDir,
+            installTargets,
+            includeOutDir: false
+        })
+    ];
+}
+function loadBundledCliGuidanceSkill() {
+    const skillPath = fileURLToPath(new URL('../skills/skillit-cli-docs/SKILL.md', import.meta.url));
+    let content;
+    try {
+        content = readFileSync(skillPath, 'utf-8');
+    }
+    catch (error) {
+        throw new Error(`Failed to read bundled CLI guidance from ${skillPath}: ${messageOf(error)}`, {
+            cause: error
+        });
+    }
+    return {
+        skill: {
+            filename: 'skillit-cli-docs/SKILL.md',
+            content
+        },
+        references: []
+    };
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=extract.js.map

package/dist/extract.js.map

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

package/dist/help-parser.d.ts

@@ -0,0 +1,17 @@
+import type { ExtractedConfigSurface } from '@skillit/core';
+/**
+ * Parse standard `--help` text output into an {@link ExtractedConfigSurface}.
+ *
+ * This is the framework-agnostic fallback used when runtime introspection of a
+ * commander/yargs program is not available.
+ *
+ * @param text        Raw text emitted by `program --help`
+ * @param commandName Canonical name for this surface (e.g. `"generate"`)
+ *
+ * @category Fallback
+ * @useWhen
+ * - Runtime introspection is unavailable (no access to the program object)
+ * - The CLI uses a framework other than Commander (yargs, oclif, custom)
+ */
+export declare function parseHelpOutput(text: string, commandName: string): ExtractedConfigSurface;
+//# sourceMappingURL=help-parser.d.ts.map

package/dist/help-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help-parser.d.ts","sourceRoot":"","sources":["../src/help-parser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,sBAAsB,EAGvB,MAAM,eAAe,CAAC;AAEvB;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,sBAAsB,CA6IzF"}