skills-doctor 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-06-15
+
+### Added
+
+- Initial Skills Doctor product requirements, skill quality specification, reusable CLI architecture specification, and incremental implementation plan.
+- Bun-managed TypeScript CLI scaffold with Biome, Vitest, typecheck, build, verify, and package dry-run quality gates.
+- GitHub Actions CI and tag-driven Bun release workflow.
+- Release-note extraction from `CHANGELOG.md` for GitHub Releases created by CI.
+- Project-local Claude and Codex/agents skill root discovery, `SKILL.md` scanning, and YAML frontmatter parsing.
+- Structural Agent Skills validation for required frontmatter, naming, description length, optional fields, missing `SKILL.md`, and unsupported fields.
+- Deterministic quality rules for weak descriptions, generic bodies, progressive-disclosure issues, missing resources, script guidance, missing evals, and divergent cross-ecosystem skills.
+- Scan report construction, human summary rendering, JSON-mode helpers, and blocking-finding exit-code decisions.
+- Interactive scan CLI with Commander, root selection prompts, non-interactive prompt skipping, spinner adapter, and findings review output.
+- Claude and Codex repair-agent detection, prompt-based agent selection, command execution helpers, and launch preview construction.
+- Findings-driven repair handoff prompts with local report directories, subset selection, and prompt/report file output.
+- Local repair-agent launch flow with explicit confirmation, inherited-terminal launcher support, post-handoff re-scan, and fixed/remaining/new finding summaries.
+- Domain-focused public API facade plus fixture coverage for valid, malformed, weak, missing-resource, script, and cross-ecosystem skill scans.
+- README, MIT license, release checklist, and finalized initial release notes.
+- Local score calculation for scan reports using distinct violated rules, with React Doctor-style labels in human, JSON, and repair-report output.
+- React Doctor-style score header in human CLI output with a face, proportional bar, terminal-width clamping, score-threshold colors, and TTY animation.
+- Concise human scan summary and streamlined review menu focused on fixing skills first.
+
+### Fixed
+
+- Avoid Node unsettled top-level-await warnings while the interactive CLI is waiting for prompts.
+- Discover global `~/.claude/skills` and `~/.agents/skills` roots and prompt for local, global/root, or both when both scopes exist.
+- Run tests under `CI=true` during local verification and isolate interactive CLI tests from ambient CI environment variables.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Metelli
+
+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,141 @@
+# Skills Doctor
+
+Skills Doctor is a local-first CLI for auditing Agent Skills in project and
+user-level skill roots. It scans `.claude/skills/`, `.agents/skills/`, or both,
+checks each `SKILL.md` against the local skill quality specification derived
+from the Agent Skills standards at <https://agentskills.io/home>, and can hand a
+findings-specific repair prompt to `claude` or `codex`.
+
+## Install And Run
+
+From a repository that contains project-local skills, or from anywhere when you
+want to scan global user-level skills:
+
+```bash
+bunx skills-doctor@latest
+```
+
+For local development in this repo:
+
+```bash
+bun install --frozen-lockfile
+bun run verify
+bun run dev
+```
+
+You can also run the built binary through package managers after publishing:
+
+```bash
+skills-doctor
+```
+
+## What It Scans
+
+Skills Doctor detects these project-local roots relative to the directory you
+run it from:
+
+- `.claude/skills/`
+- `.agents/skills/`
+
+It also detects these global user-level roots:
+
+- `~/.claude/skills/`
+- `~/.agents/skills/`
+
+When local and global roots both exist, the interactive CLI first asks whether
+to scan local project skills, global/root skills, or both. When both Claude and
+Codex/agents roots exist in the selected scope, it asks whether to scan Claude,
+Codex/agents, or both. When no known root exists, it prompts for a custom skills
+directory. Non-interactive runs use conservative defaults and fail with a clear
+user error when a required choice cannot be made.
+
+## What It Checks
+
+The scanner validates skills against `docs/SKILLS_SPEC.md`, which consolidates
+the Agent Skills standards from <https://agentskills.io/home>, including:
+
+- required YAML frontmatter and valid `name`/`description` fields
+- trigger-oriented descriptions
+- non-generic skill bodies with concrete workflow structure
+- progressive disclosure for large or referenced material
+- referenced `references/`, `scripts/`, and `assets/` files
+- script guidance that is non-interactive and reproducible
+- eval guidance for non-trivial skills
+- divergent same-name skills across Claude and Codex/agents roots
+
+Findings are grouped as blocking errors, warnings, and advisory improvements.
+The human summary opens with a score header showing a face, `0` to `100` score,
+label, and proportional terminal bar. The score starts at 100 and deducts 1.5
+points for each distinct error rule and 0.75 points for each distinct warning
+rule; repeated findings from the same rule do not increase the penalty. Advisory
+findings are counted in the report but do not affect the score. Score labels are
+`Great` for 75 or higher, `Needs work` for 50 through 74, and `Critical` below
+50.
+
+## Interactive Repair Flow
+
+When findings exist, the CLI can:
+
+1. Show a concise score, skill count, and issue count.
+2. Let you choose a repair subset: errors, errors plus warnings, all findings,
+   or selected skills.
+3. Detect local `claude` and `codex` executables.
+4. Write a full report under `.skills-doctor/reports/<timestamp>/`.
+5. Generate a compact `handoff-prompt.md` tailored to the selected findings.
+6. Preview the launch command.
+7. Ask for explicit confirmation before handing the terminal to the selected
+   agent.
+8. Re-scan the same roots after the agent exits and report fixed, remaining,
+   and new findings.
+
+Launch mappings:
+
+- Claude: `claude --dangerously-skip-permissions <prompt>`
+- Codex: `codex --yolo <prompt>`
+
+Skills Doctor does not edit skill files during the scan phase. Repairs are made
+only by the local agent after you confirm the handoff.
+
+## JSON Mode
+
+Use JSON output for automation:
+
+```bash
+skills-doctor --json
+skills-doctor --json --json-compact
+skills-doctor --yes --json
+```
+
+JSON mode writes one machine-readable report to stdout and suppresses prompts
+and spinners. Human logs and expected errors stay out of stdout.
+
+## Exit Codes
+
+- `0`: no blocking errors remain in the final scan.
+- `1`: blocking errors remain, no readable skills root was available, or another
+  expected user error occurred.
+
+## Privacy
+
+Skills Doctor reads local skill files and writes local report files. It does not
+upload skill contents or call a hosted model. Content leaves the process only if
+you explicitly launch a local agent CLI such as `claude` or `codex`, and that
+agent then follows its own configuration.
+
+## Release Checklist
+
+Before tagging a release:
+
+```bash
+bun run verify
+bun run pack:dry-run
+node scripts/extract-release-notes.mjs 0.1.0
+```
+
+Then:
+
+1. Update `package.json` version.
+2. Move changelog entries from `Unreleased` into `## [x.y.z] - YYYY-MM-DD`.
+3. Commit the release prep.
+4. Tag `v<x.y.z>`.
+5. Push the tag to trigger the release workflow.

package/bin/skills-doctor.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+
+import module from "node:module";
+
+if (module.enableCompileCache && !process.env.NODE_DISABLE_COMPILE_CACHE) {
+  try {
+    module.enableCompileCache();
+  } catch {
+    // Compile cache is an optimization; startup must not depend on it.
+  }
+}
+
+await import("../dist/cli/index.js");

package/dist/cli/commands/scan.d.ts

@@ -0,0 +1,29 @@
+import type { ScanReport } from "../../domain/build-report.js";
+import type { AgentAvailabilityProbe, RepairAgentLauncher } from "../utils/launch-agent.js";
+import { type PromptAdapter } from "../utils/prompts.js";
+import { type SpinnerFactory } from "../utils/spinner.js";
+export type ScanFlags = {
+    readonly json?: boolean;
+    readonly jsonCompact?: boolean;
+    readonly yes?: boolean;
+};
+export type ScanActionOptions = {
+    readonly cwd?: string;
+    readonly homeDir?: string | undefined;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly stdinIsTty?: boolean;
+    readonly prompts?: PromptAdapter;
+    readonly writeStdout?: (message: string) => void;
+    readonly writeStderr?: (message: string) => void;
+    readonly stdoutIsTty?: boolean;
+    readonly terminalColumns?: number | undefined;
+    readonly animateScoreHeader?: boolean;
+    readonly spinner?: SpinnerFactory;
+    readonly version?: string;
+    readonly isRepairAgentAvailable?: AgentAvailabilityProbe;
+    readonly repairReportOutputRoot?: string;
+    readonly repairReportTimestamp?: string;
+    readonly launchAgent?: RepairAgentLauncher;
+};
+export declare const scanAction: (directory: string, flags: ScanFlags, options?: ScanActionOptions) => Promise<ScanReport>;
+//# sourceMappingURL=scan.d.ts.map

package/dist/cli/commands/scan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/scan.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAU/D,OAAO,KAAK,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAM5F,OAAO,EAAyB,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGhF,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAEzE,MAAM,MAAM,SAAS,GAAG;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACjC,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACjD,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACjD,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9C,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IACtC,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,sBAAsB,CAAC,EAAE,sBAAsB,CAAC;IACzD,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IACzC,QAAQ,CAAC,qBAAqB,CAAC,EAAE,MAAM,CAAC;IACxC,QAAQ,CAAC,WAAW,CAAC,EAAE,mBAAmB,CAAC;CAC5C,CAAC;AAMF,eAAO,MAAM,UAAU,GACrB,WAAW,MAAM,EACjB,OAAO,SAAS,EAChB,UAAS,iBAAsB,KAC9B,OAAO,CAAC,UAAU,CAyFpB,CAAC"}

package/dist/cli/commands/scan.js

@@ -0,0 +1,234 @@
+import path from "node:path";
+import { buildScanReport } from "../../domain/build-report.js";
+import { compareFindings, renderPostHandoffSummary } from "../../domain/compare-findings.js";
+import { discoverSkillRoots } from "../../domain/discover-skill-roots.js";
+import { scanSkillRoots } from "../../domain/scan-skills.js";
+import { renderHumanSummary, resolveScanExitCode } from "../../domain/summarize-findings.js";
+import { CliInputError } from "../utils/handle-error.js";
+import { prepareRepairHandoff } from "../utils/handoff-to-agent.js";
+import { enableJsonMode, writeJsonReport } from "../utils/json-mode.js";
+import { chooseRepairAgent, formatRepairAgentPreview, launchRepairAgent, } from "../utils/launch-agent.js";
+import { inquirerPromptAdapter } from "../utils/prompts.js";
+import { printScoreHeader } from "../utils/render-score-header.js";
+import { shouldSkipPrompts } from "../utils/should-skip-prompts.js";
+import { createSpinner } from "../utils/spinner.js";
+export const scanAction = async (directory, flags, options = {}) => {
+    const cwd = path.resolve(options.cwd ?? process.cwd(), directory);
+    const prompts = options.prompts ?? inquirerPromptAdapter;
+    const writeStdout = options.writeStdout ?? ((message) => process.stdout.write(message));
+    const writeStderr = options.writeStderr ?? ((message) => process.stderr.write(message));
+    const stdoutIsTty = options.stdoutIsTty ?? process.stdout.isTTY === true;
+    const skipPrompts = shouldSkipPrompts({
+        yes: Boolean(flags.yes),
+        json: Boolean(flags.json),
+        env: options.env,
+        stdinIsTty: options.stdinIsTty ?? process.stdin.isTTY,
+    });
+    const spinner = options.spinner ??
+        createSpinner({
+            enabled: !skipPrompts && !flags.json,
+            write: (message) => writeStderr(`${message}\n`),
+        });
+    if (flags.json) {
+        enableJsonMode({ compact: Boolean(flags.jsonCompact), directory: cwd });
+    }
+    const discovered = await spinner.run("Finding local skill roots...", () => discoverSkillRoots({ cwd, homeDir: options.homeDir }));
+    let roots = discovered.roots;
+    if (roots.length === 0) {
+        if (skipPrompts) {
+            throw new CliInputError("No .claude/skills or .agents/skills root was found. Re-run interactively or add a supported skills root.");
+        }
+        const customRoot = await prompts.input("Skills directory path", ".");
+        const custom = await discoverSkillRoots({
+            cwd,
+            homeDir: options.homeDir,
+            customRoots: [{ rootPath: customRoot, ecosystem: "custom" }],
+        });
+        roots = custom.roots;
+    }
+    else if (!skipPrompts) {
+        roots = await selectRootScopes(roots, prompts);
+        roots = await selectRoots(roots, prompts);
+    }
+    if (roots.length === 0) {
+        throw new CliInputError("No readable skills root was selected.");
+    }
+    const scan = await spinner.run("Scanning skills...", () => scanSkillRoots({ roots }));
+    const report = buildScanReport({
+        version: options.version ?? "0.0.0",
+        directory: cwd,
+        elapsedMilliseconds: 0,
+        scan,
+    });
+    let finalReport = report;
+    if (flags.json) {
+        writeJsonReport(report, writeStdout);
+    }
+    else {
+        await printScoreHeader({
+            score: report.score,
+            write: writeStdout,
+            color: stdoutIsTty,
+            columns: options.terminalColumns ?? process.stdout.columns,
+            animate: options.animateScoreHeader ?? (!skipPrompts && stdoutIsTty),
+        });
+        writeStdout(renderHumanSummary(report, { includeScore: false }));
+        if (!skipPrompts && report.findingCount > 0) {
+            finalReport =
+                (await reviewFindings(report, {
+                    cwd,
+                    roots,
+                    version: options.version ?? "0.0.0",
+                    spinner,
+                    prompts,
+                    write: writeStdout,
+                    isRepairAgentAvailable: options.isRepairAgentAvailable,
+                    repairReportOutputRoot: options.repairReportOutputRoot,
+                    repairReportTimestamp: options.repairReportTimestamp,
+                    launchAgent: options.launchAgent ?? launchRepairAgent,
+                })) ?? report;
+        }
+    }
+    process.exitCode = resolveScanExitCode(finalReport);
+    return finalReport;
+};
+const selectRoots = async (roots, prompts) => {
+    const hasClaude = roots.some((root) => root.ecosystem === "claude");
+    const hasCodex = roots.some((root) => root.ecosystem === "codex");
+    if (!hasClaude || !hasCodex)
+        return roots;
+    const selection = await prompts.select("Choose skills folder to scan", [
+        { name: "Both", value: "all" },
+        { name: "Claude (.claude/skills)", value: "claude" },
+        { name: "Codex/agents (.agents/skills)", value: "codex" },
+    ]);
+    if (selection === "all")
+        return roots;
+    return roots.filter((root) => root.ecosystem === selection);
+};
+const selectRootScopes = async (roots, prompts) => {
+    const hasLocal = roots.some((root) => root.source === "local");
+    const hasGlobal = roots.some((root) => root.source === "global");
+    if (!hasLocal || !hasGlobal)
+        return roots;
+    const selection = await prompts.select("Choose skills scope to scan", [
+        { name: "Both local project and global/root skills", value: "all" },
+        { name: "Local project skills (./.claude/skills, ./.agents/skills)", value: "local" },
+        { name: "Global/root skills (~/.claude/skills, ~/.agents/skills)", value: "global" },
+    ]);
+    if (selection === "all")
+        return roots;
+    return roots.filter((root) => root.source === selection);
+};
+const reviewFindings = async (report, input) => {
+    const { prompts, write } = input;
+    const action = await prompts.select("Next step", [
+        { name: "Fix skills with Claude or Codex", value: "repair" },
+        ...(report.errorCount > 0 ? [{ name: "View errors", value: "errors" }] : []),
+        { name: "View all findings", value: "all" },
+        { name: "Exit", value: "exit" },
+    ]);
+    if (action === "exit")
+        return;
+    if (action === "repair") {
+        return runRepairAgentFlow(report, input);
+    }
+    const selectedFindings = action === "errors"
+        ? report.findings.filter((finding) => finding.severity === "error")
+        : report.findings;
+    if (action === "by-skill") {
+        write(renderFindingsBySkill(selectedFindings));
+        return;
+    }
+    write(renderFindings(selectedFindings));
+    return undefined;
+};
+const runRepairAgentFlow = async (report, input) => {
+    try {
+        const agent = await chooseRepairAgent({
+            prompts: input.prompts,
+            isAvailable: input.isRepairAgentAvailable,
+        });
+        if (agent === undefined) {
+            input.write("Repair handoff cancelled.\n");
+            return undefined;
+        }
+        const handoff = await prepareRepairHandoff({
+            report,
+            prompts: input.prompts,
+            outputRoot: input.repairReportOutputRoot,
+            timestamp: input.repairReportTimestamp,
+        });
+        input.write(`Selected ${agent.displayName}.\n`);
+        input.write(`Launch preview: ${formatRepairAgentPreview(agent.id)}\n`);
+        if (handoff.reportDirectory !== undefined) {
+            input.write(`Report directory: ${handoff.reportDirectory}\n`);
+        }
+        if (handoff.promptPath !== undefined) {
+            input.write(`Repair prompt: ${handoff.promptPath}\n`);
+        }
+        else {
+            input.write(`Repair prompt:\n${handoff.prompt}\n`);
+        }
+        if (handoff.reportWriteError !== undefined) {
+            input.write(`Report write failed: ${handoff.reportWriteError.message}\n`);
+        }
+        const shouldLaunch = await input.prompts.confirm(`Launch ${agent.displayName} now?`, false);
+        if (!shouldLaunch) {
+            input.write("Agent launch cancelled.\n");
+            return undefined;
+        }
+        let exitCode;
+        try {
+            exitCode = await input.launchAgent(agent.id, handoff.prompt, input.cwd);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            input.write(`Agent launch failed: ${message}\n`);
+            return undefined;
+        }
+        if (exitCode !== 0) {
+            input.write(`Agent exited with code ${exitCode}.\n`);
+        }
+        const nextScan = await input.spinner.run("Re-scanning skills...", () => scanSkillRoots({ roots: input.roots }));
+        const nextReport = buildScanReport({
+            version: input.version,
+            directory: input.cwd,
+            elapsedMilliseconds: 0,
+            scan: nextScan,
+            handoffRequested: true,
+        });
+        const comparison = compareFindings(report.findings, nextReport.findings);
+        input.write(renderPostHandoffSummary(comparison, nextReport));
+        if (nextReport.findingCount > 0 &&
+            (await input.prompts.confirm("Run another repair pass?", false))) {
+            return (await reviewFindings(nextReport, input)) ?? nextReport;
+        }
+        return nextReport;
+    }
+    catch (error) {
+        if (error instanceof CliInputError) {
+            input.write(`${error.message}\n`);
+            return undefined;
+        }
+        throw error;
+    }
+};
+const renderFindings = (findings) => `${findings
+    .map((finding) => `[${finding.severity}] ${finding.ruleId} ${finding.skillName ?? finding.skillPath}\n${finding.message}\nSuggestion: ${finding.suggestion}`)
+    .join("\n\n")}\n`;
+const renderFindingsBySkill = (findings) => {
+    const groups = new Map();
+    for (const finding of findings) {
+        const key = finding.skillName ?? finding.skillPath;
+        groups.set(key, [...(groups.get(key) ?? []), finding]);
+    }
+    return [...groups.entries()]
+        .map(([skillName, skillFindings]) => {
+        const lines = [`${skillName}:`];
+        lines.push(...skillFindings.map((finding) => `- [${finding.severity}] ${finding.ruleId}`));
+        return lines.join("\n");
+    })
+        .join("\n\n")
+        .concat("\n");
+};

package/dist/cli/index.d.ts

@@ -0,0 +1,4 @@
+import { Command } from "commander";
+export declare const buildProgram: () => Command;
+export declare const main: (argv?: readonly string[]) => Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,eAAO,MAAM,YAAY,QAAO,OAmB/B,CAAC;AAEF,eAAO,MAAM,IAAI,GAAU,OAAM,SAAS,MAAM,EAAiB,KAAG,OAAO,CAAC,IAAI,CAY/E,CAAC"}

package/dist/cli/index.js

@@ -0,0 +1,32 @@
+import { Command } from "commander";
+import { scanAction } from "./commands/scan.js";
+import { handleCliError } from "./utils/handle-error.js";
+export const buildProgram = () => {
+    const program = new Command()
+        .name("skills-doctor")
+        .description("Scan Agent Skills and report quality issues.")
+        .version("0.0.0", "-v, --version", "display the version number")
+        .argument("[directory]", "directory to scan from", ".")
+        .option("--json", "output one machine-readable JSON report")
+        .option("--json-compact", "with --json, omit indentation")
+        .option("-y, --yes", "skip prompts and use conservative defaults")
+        .action(async (directory, flags) => {
+        await scanAction(directory, flags);
+    });
+    return program;
+};
+export const main = async (argv = process.argv) => {
+    process.on("SIGINT", () => process.exit(130));
+    process.on("SIGTERM", () => process.exit(143));
+    process.stdout.on("error", (error) => {
+        if (error.code === "EPIPE")
+            process.exit(0);
+    });
+    try {
+        await buildProgram().parseAsync([...argv]);
+    }
+    finally {
+        process.stdin.unref?.();
+    }
+};
+main().catch(handleCliError);

package/dist/cli/utils/cli-logger.d.ts

@@ -0,0 +1,8 @@
+export type CliLogger = {
+    readonly log: (message: string) => void;
+    readonly warn: (message: string) => void;
+    readonly error: (message: string) => void;
+    readonly break: () => void;
+};
+export declare const cliLogger: CliLogger;
+//# sourceMappingURL=cli-logger.d.ts.map

package/dist/cli/utils/cli-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-logger.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/cli-logger.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,GAAG;IACtB,QAAQ,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC,QAAQ,CAAC,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1C,QAAQ,CAAC,KAAK,EAAE,MAAM,IAAI,CAAC;CAC5B,CAAC;AAEF,eAAO,MAAM,SAAS,EAAE,SAavB,CAAC"}

package/dist/cli/utils/cli-logger.js

@@ -0,0 +1,14 @@
+export const cliLogger = {
+    log: (message) => {
+        process.stderr.write(`${message}\n`);
+    },
+    warn: (message) => {
+        process.stderr.write(`${message}\n`);
+    },
+    error: (message) => {
+        process.stderr.write(`${message}\n`);
+    },
+    break: () => {
+        process.stderr.write("\n");
+    },
+};

package/dist/cli/utils/handle-error.d.ts

@@ -0,0 +1,6 @@
+export declare class CliInputError extends Error {
+    constructor(message: string);
+}
+export declare const isExpectedUserError: (error: unknown) => error is CliInputError;
+export declare const handleCliError: (error: unknown) => void;
+//# sourceMappingURL=handle-error.d.ts.map

package/dist/cli/utils/handle-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handle-error.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/handle-error.ts"],"names":[],"mappings":"AAGA,qBAAa,aAAc,SAAQ,KAAK;gBAC1B,OAAO,EAAE,MAAM;CAI5B;AAED,eAAO,MAAM,mBAAmB,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,aAC9B,CAAC;AAEjC,eAAO,MAAM,cAAc,GAAI,OAAO,OAAO,KAAG,IAgB/C,CAAC"}

package/dist/cli/utils/handle-error.js

@@ -0,0 +1,24 @@
+import { cliLogger } from "./cli-logger.js";
+import { isJsonModeActive, writeJsonErrorReport } from "./json-mode.js";
+export class CliInputError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CliInputError";
+    }
+}
+export const isExpectedUserError = (error) => error instanceof CliInputError;
+export const handleCliError = (error) => {
+    if (isJsonModeActive()) {
+        writeJsonErrorReport(error);
+        process.exitCode = 1;
+        return;
+    }
+    if (isExpectedUserError(error)) {
+        cliLogger.error(error.message);
+        process.exitCode = 1;
+        return;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    cliLogger.error(`Unexpected error: ${message}`);
+    process.exitCode = 1;
+};

package/dist/cli/utils/handoff-to-agent.d.ts

@@ -0,0 +1,21 @@
+import type { ScanReport } from "../../domain/build-report.js";
+import type { Finding } from "../../domain/types.js";
+import { writeFindingsDirectory } from "../../domain/write-findings-directory.js";
+import type { PromptAdapter } from "./prompts.js";
+export type RepairFindingSubset = "errors" | "errors-and-warnings" | "all" | "selected-skills";
+export type PreparedRepairHandoff = {
+    readonly findings: readonly Finding[];
+    readonly prompt: string;
+    readonly reportDirectory?: string | undefined;
+    readonly promptPath?: string | undefined;
+    readonly reportWriteError?: Error | undefined;
+};
+export type PrepareRepairHandoffInput = {
+    readonly report: ScanReport;
+    readonly prompts: PromptAdapter;
+    readonly outputRoot?: string | undefined;
+    readonly timestamp?: string | undefined;
+    readonly writeDirectory?: typeof writeFindingsDirectory | undefined;
+};
+export declare const prepareRepairHandoff: (input: PrepareRepairHandoffInput) => Promise<PreparedRepairHandoff>;
+//# sourceMappingURL=handoff-to-agent.d.ts.map

package/dist/cli/utils/handoff-to-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handoff-to-agent.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/handoff-to-agent.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAC/D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAKrD,OAAO,EAAE,sBAAsB,EAAE,MAAM,0CAA0C,CAAC;AAElF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,qBAAqB,GAAG,KAAK,GAAG,iBAAiB,CAAC;AAE/F,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9C,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,KAAK,GAAG,SAAS,CAAC;CAC/C,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG;IACtC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,sBAAsB,GAAG,SAAS,CAAC;CACrE,CAAC;AAEF,eAAO,MAAM,oBAAoB,GAC/B,OAAO,yBAAyB,KAC/B,OAAO,CAAC,qBAAqB,CAgC/B,CAAC"}