skills-doctor 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -8,6 +8,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 *No changes yet.*
 
+## [0.3.1] - 2026-06-16
+
+### Added
+
+- Added line numbers to quality-rule findings where a specific source line can be resolved.
+
+### Fixed
+
+- Hid repair handoff subset options that do not match any findings (for warning-only and advice-only scans).
+- Made CLI module import safe by removing side-effect execution and routing runtime entry through `bin/skills-doctor.js`.
+
 ## [0.3.0] - 2026-06-16
 
 ### Added

package/bin/skills-doctor.js

@@ -10,4 +10,5 @@ if (module.enableCompileCache && !process.env.NODE_DISABLE_COMPILE_CACHE) {
   }
 }
 
-await import("../dist/cli/index.js");
+const { runCli } = await import("../dist/cli/index.js");
+await runCli();

package/dist/cli/index.d.ts

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

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

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

package/dist/cli/index.js

@@ -30,4 +30,6 @@ export const main = async (argv = process.argv) => {
         process.stdin.unref?.();
     }
 };
-main().catch(handleCliError);
+export const runCli = async (argv = process.argv) => {
+    await main(argv).catch(handleCliError);
+};

package/dist/cli/utils/handoff-to-agent.js

@@ -34,12 +34,20 @@ export const prepareRepairHandoff = async (input) => {
     };
 };
 const chooseRepairFindings = async (report, prompts) => {
-    const subset = await prompts.select("Choose findings to repair", [
-        { name: "Blocking errors only", value: "errors" },
-        { name: "Blocking errors and warnings", value: "errors-and-warnings" },
-        { name: "All findings", value: "all" },
-        { name: "Selected skills", value: "selected-skills" },
-    ]);
+    const choices = [];
+    if (report.errorCount > 0) {
+        choices.push({ name: "Blocking errors only", value: "errors" });
+    }
+    if (report.errorCount + report.warningCount > 0) {
+        choices.push({ name: "Blocking errors and warnings", value: "errors-and-warnings" });
+    }
+    if (report.findingCount > 0) {
+        choices.push({ name: "All findings", value: "all" });
+    }
+    if (report.skills.some((skill) => skill.findingCount > 0)) {
+        choices.push({ name: "Selected skills", value: "selected-skills" });
+    }
+    const subset = await prompts.select("Choose findings to repair", choices);
     if (subset === "errors") {
         return report.findings.filter((finding) => finding.severity === "error");
     }

package/dist/domain/rules/quality.js

@@ -23,17 +23,19 @@ const validateSkillQuality = async (skill) => {
     const findings = [];
     const frontmatter = skill.parseResult.frontmatter;
     const description = readString(frontmatter.data.description) ?? "";
-    const body = frontmatter.body.trim();
+    const body = frontmatter.body;
+    const frontMatterLineCount = frontmatter.raw.split(/\r?\n/).length;
     findings.push(...validateDescription(skill, description));
-    findings.push(...validateBody(skill, body));
-    findings.push(...validateProgressiveDisclosure(skill));
-    findings.push(...(await validateResources(skill, body)));
+    findings.push(...validateBody(skill, body, frontMatterLineCount));
+    findings.push(...validateProgressiveDisclosure(skill, body, frontMatterLineCount));
+    findings.push(...(await validateResources(skill, body, frontMatterLineCount)));
     findings.push(...(await validateEvals(skill, body)));
     return findings;
 };
 const validateDescription = (skill, description) => {
     const findings = [];
     const normalized = description.trim();
+    const line = findContentLine(skill.content, /^\s*description\s*:/i);
     if (normalized.length > 0 && !TRIGGER_PATTERN.test(normalized)) {
         findings.push(createFinding(skill, {
             ruleId: "weak-description-trigger",
@@ -42,6 +44,7 @@ const validateDescription = (skill, description) => {
             title: "Description lacks a clear activation trigger",
             message: "The description should explain when an agent should use this skill.",
             suggestion: 'Use imperative phrasing such as "Use this skill when..." and include concrete task contexts.',
+            line,
         }));
     }
     if (VAGUE_DESCRIPTION_PATTERN.test(normalized)) {
@@ -52,6 +55,7 @@ const validateDescription = (skill, description) => {
             title: "Description is too vague",
             message: "A short generic description is unlikely to trigger reliably or explain the skill's scope.",
             suggestion: "Describe what the skill does, when to use it, and important adjacent cases.",
+            line,
         }));
     }
     if (IMPLEMENTATION_DESCRIPTION_PATTERN.test(normalized) &&
@@ -63,11 +67,12 @@ const validateDescription = (skill, description) => {
             title: "Description focuses on implementation",
             message: "Descriptions should match user intent rather than the skill's internal mechanics.",
             suggestion: "Rewrite the description around the task the user is trying to accomplish.",
+            line,
         }));
     }
     return findings;
 };
-const validateBody = (skill, body) => {
+const validateBody = (skill, body, frontMatterLineCount) => {
     const findings = [];
     if (PLACEHOLDER_PATTERN.test(body)) {
         findings.push(createFinding(skill, {
@@ -77,6 +82,7 @@ const validateBody = (skill, body) => {
             title: "Body contains placeholder text",
             message: "A skill body should contain complete reusable instructions, not placeholders.",
             suggestion: "Replace placeholders with concrete workflow steps, gotchas, examples, or validation guidance.",
+            line: findBodyLine(frontMatterLineCount, body, PLACEHOLDER_PATTERN),
         }));
     }
     if (GENERIC_BODY_PATTERN.test(body)) {
@@ -87,6 +93,7 @@ const validateBody = (skill, body) => {
             title: "Body appears generic",
             message: "The body uses generic advice that does not add skill-specific expertise.",
             suggestion: "Replace generic phrasing with concrete project or domain procedures the agent would not already know.",
+            line: findBodyLine(frontMatterLineCount, body, GENERIC_BODY_PATTERN),
         }));
     }
     if (!WORKFLOW_STEP_PATTERN.test(body)) {
@@ -97,6 +104,7 @@ const validateBody = (skill, body) => {
             title: "Body lacks concrete workflow structure",
             message: "The body does not appear to include headings, ordered steps, or checklist items.",
             suggestion: "Add a concise workflow, gotchas section, examples, or validation loop.",
+            line: findFirstBodyLine(body, frontMatterLineCount),
         }));
     }
     if (TOOL_MENU_PATTERN.test(body)) {
@@ -107,6 +115,7 @@ const validateBody = (skill, body) => {
             title: "Body presents a tool menu without a default",
             message: "Skills should provide defaults rather than long menus of equal options.",
             suggestion: "Pick a default tool and explain when to use a fallback.",
+            line: findBodyLine(frontMatterLineCount, body, TOOL_MENU_PATTERN),
         }));
     }
     if (DESTRUCTIVE_PATTERN.test(body) && !SAFETY_PATTERN.test(body)) {
@@ -117,11 +126,12 @@ const validateBody = (skill, body) => {
             title: "Destructive operation lacks safety guidance",
             message: "Destructive, release, migration, or deploy guidance should include validation, preview, backup, or confirmation steps.",
             suggestion: "Add a dry-run, validation, backup, or explicit confirmation requirement before the destructive action.",
+            line: findBodyLine(frontMatterLineCount, body, DESTRUCTIVE_PATTERN),
         }));
     }
     return findings;
 };
-const validateProgressiveDisclosure = (skill) => {
+const validateProgressiveDisclosure = (skill, body, frontMatterLineCount) => {
     const findings = [];
     const lineCount = skill.content.split(/\r?\n/).length;
     const tokenEstimate = estimateTokens(skill.content);
@@ -153,11 +163,12 @@ const validateProgressiveDisclosure = (skill) => {
             title: "Resource reference lacks a load trigger",
             message: "The skill references a resource directory generically instead of naming the file and when to load it.",
             suggestion: 'Use specific guidance such as "Read references/api-errors.md if the API returns a non-200 status."',
+            line: findBodyLine(frontMatterLineCount, body, GENERIC_REFERENCE_PATTERN),
         }));
     }
     return findings;
 };
-const validateResources = async (skill, body) => {
+const validateResources = async (skill, body, frontMatterLineCount) => {
     const findings = [];
     const referencedPaths = [...new Set(skill.content.match(RESOURCE_REFERENCE_PATTERN) ?? [])];
     for (const referencePath of referencedPaths) {
@@ -169,6 +180,7 @@ const validateResources = async (skill, body) => {
                 title: "Resource reference escapes the skill directory",
                 message: "The skill references a resource outside the skill directory. Resource references must remain inside scripts/, references/, or assets/ for this skill.",
                 suggestion: "Use a path rooted inside the skill (for example references/file.md) without '..' segments.",
+                line: findReferenceLine(skill.content, referencePath),
             }));
             continue;
         }
@@ -181,6 +193,7 @@ const validateResources = async (skill, body) => {
                 title: "Referenced resource does not exist",
                 message: `The skill references ${referencePath}, but that path does not exist inside the skill directory.`,
                 suggestion: "Create the referenced file or remove the stale reference.",
+                line: findReferenceLine(skill.content, referencePath),
             }));
             continue;
         }
@@ -192,6 +205,7 @@ const validateResources = async (skill, body) => {
                 title: "Script reference lacks help guidance",
                 message: "Script instructions should document usage or mention --help so agents can learn the interface.",
                 suggestion: "Add a short usage example and document that the script supports --help.",
+                line: findReferenceLine(skill.content, referencePath),
             }));
         }
     }
@@ -203,6 +217,7 @@ const validateResources = async (skill, body) => {
             title: "Script guidance appears interactive",
             message: "Agents need non-interactive scripts that accept flags, stdin, files, or environment variables.",
             suggestion: "Replace interactive prompts with command-line flags and clear errors for missing inputs.",
+            line: findBodyLine(frontMatterLineCount, body, INTERACTIVE_SCRIPT_PATTERN),
         }));
     }
     if (UNPINNED_RUNNER_PATTERN.test(body)) {
@@ -213,6 +228,7 @@ const validateResources = async (skill, body) => {
             title: "Package-runner command is not version-pinned",
             message: "One-off package-runner commands should pin versions when reproducibility matters.",
             suggestion: "Use a versioned command such as npx eslint@9 or uvx ruff@0.8.0.",
+            line: findBodyLine(frontMatterLineCount, body, UNPINNED_RUNNER_PATTERN),
         }));
     }
     return findings;
@@ -285,8 +301,35 @@ const createFinding = (skill, input) => ({
     skillName: skill.parseResult.ok
         ? readString(skill.parseResult.frontmatter.data.name)
         : skill.directoryName,
+    line: input.line,
     agentRepairable: true,
 });
+const findContentLine = (content, pattern) => {
+    const linePattern = typeof pattern === "string"
+        ? new RegExp(escapeRegExp(pattern))
+        : new RegExp(pattern.source, pattern.flags.replace(/g/g, ""));
+    const lines = content.split(/\r?\n/);
+    for (const [index, line] of lines.entries()) {
+        if (linePattern.test(line)) {
+            return index + 1;
+        }
+    }
+    return undefined;
+};
+const findBodyLine = (frontMatterLineCount, body, pattern) => {
+    const bodyLine = findContentLine(body, pattern);
+    if (bodyLine === undefined)
+        return undefined;
+    return frontMatterLineCount + 2 + bodyLine;
+};
+const findReferenceLine = (content, referencePath) => findContentLine(content, referencePath);
+const findFirstBodyLine = (body, frontMatterLineCount) => {
+    const lines = body.split(/\r?\n/);
+    if (lines.length === 0)
+        return undefined;
+    return frontMatterLineCount + 2 + 1;
+};
+const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 const readString = (value) => typeof value === "string" ? value : undefined;
 const estimateTokens = (content) => Math.ceil(content.split(/\s+/).filter(Boolean).length * 1.35);
 const exists = async (targetPath) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skills-doctor",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Interactive CLI that scans and repairs Agent Skills quality issues.",
   "type": "module",
   "packageManager": "bun@1.3.13",