skills-doctor 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -8,6 +8,29 @@ 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
+
+- Kept the interactive review menu available after viewing grouped and/or error findings so users can still launch repair in the same session.
+- Added support for selecting a custom skills directory during interactive scans even when standard Claude/Codex roots are already detected.
+
+### Fixed
+
+- Ignored direct skill-root child directories that do not contain `SKILL.md` instead of reporting a blocking `missing-skill` finding.
+- Classified missing referenced assets under the `assets` finding category instead of falling back to another resource category.
+
 ## [0.2.0] - 2026-06-16
 
 ### Added

package/README.md

@@ -57,9 +57,10 @@ It also detects these global user-level roots:
 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.
+Codex/agents, or both. If you already have standard roots detected, it also lets
+you add a custom skills directory path in the same interactive flow. Non-interactive
+runs use conservative defaults and fail with a clear user error when a required
+choice cannot be made.
 
 ## What It Checks
 

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/commands/scan.d.ts.map

@@ -1 +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,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAC5B,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,CA6FpB,CAAC"}
+{"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,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAC5B,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,CAsGpB,CAAC"}

package/dist/cli/commands/scan.js

@@ -39,17 +39,26 @@ export const scanAction = async (directory, flags, options = {}) => {
         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({
+        roots = await selectCustomRoot({
             cwd,
             homeDir: options.homeDir,
-            customRoots: [{ rootPath: customRoot, ecosystem: "custom" }],
+            prompts,
+            roots,
         });
-        roots = custom.roots;
     }
     else if (!skipPrompts) {
-        roots = await selectRootScopes(roots, prompts);
-        roots = await selectRoots(roots, prompts);
+        roots = await selectRootScopes({
+            roots,
+            prompts,
+            cwd,
+            homeDir: options.homeDir,
+        });
+        roots = await selectRoots({
+            roots,
+            prompts,
+            cwd,
+            homeDir: options.homeDir,
+        });
     }
     if (roots.length === 0) {
         throw new CliInputError("No readable skills root was selected.");
@@ -96,57 +105,126 @@ export const scanAction = async (directory, flags, options = {}) => {
     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");
+const selectRoots = async (input) => {
+    const { prompts, cwd, homeDir, roots } = input;
+    const customRoots = roots.filter((root) => root.source === "custom");
+    const standardRoots = roots.filter((root) => root.source !== "custom");
+    const hasClaude = standardRoots.some((root) => root.ecosystem === "claude");
+    const hasCodex = standardRoots.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" },
+        { name: "Add custom skills path", value: "custom" },
     ]);
     if (selection === "all")
         return roots;
-    return roots.filter((root) => root.ecosystem === selection);
+    if (selection === "custom") {
+        return selectCustomRoot({
+            cwd,
+            homeDir,
+            prompts,
+            roots,
+        });
+    }
+    return [...standardRoots.filter((root) => root.ecosystem === selection), ...customRoots];
 };
-const selectRootScopes = async (roots, prompts) => {
+const selectRootScopes = async (input) => {
+    const { prompts, cwd, homeDir, roots } = input;
     const hasLocal = roots.some((root) => root.source === "local");
     const hasGlobal = roots.some((root) => root.source === "global");
-    if (!hasLocal || !hasGlobal)
+    const hasBothScopes = hasLocal && hasGlobal;
+    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" },
-    ]);
+    const allLabel = hasBothScopes
+        ? "Both local project and global/root skills"
+        : "Detected skills root";
+    const choices = [
+        { name: allLabel, value: "all" },
+    ];
+    if (hasBothScopes) {
+        choices.push({
+            name: "Local project skills (./.claude/skills, ./.agents/skills)",
+            value: "local",
+        });
+        choices.push({
+            name: "Global/root skills (~/.claude/skills, ~/.agents/skills)",
+            value: "global",
+        });
+    }
+    choices.push({ name: "Add custom skills path", value: "custom" });
+    if (choices.length <= 1) {
+        return roots;
+    }
+    const selection = await prompts.select("Choose skills scope to scan", choices);
+    if (selection === "custom") {
+        return selectCustomRoot({
+            cwd,
+            homeDir,
+            prompts,
+            roots,
+        });
+    }
     if (selection === "all")
         return roots;
-    return roots.filter((root) => root.source === selection);
+    if (selection === "claude") {
+        return roots.filter((root) => root.ecosystem === "claude");
+    }
+    if (selection === "codex") {
+        return roots.filter((root) => root.ecosystem === "codex");
+    }
+    if (selection === "local" || selection === "global") {
+        return roots.filter((root) => root.source === selection);
+    }
+    return roots;
+};
+const selectCustomRoot = async (input) => {
+    const customRoot = await input.prompts.input("Skills directory path", ".");
+    const custom = await discoverSkillRoots({
+        cwd: input.cwd,
+        homeDir: input.homeDir,
+        customRoots: [{ rootPath: customRoot, ecosystem: "custom" }],
+    });
+    return mergeRoots(input.roots, custom.roots);
+};
+const mergeRoots = (existingRoots, additionalRoots) => {
+    const merged = new Map();
+    for (const root of existingRoots) {
+        merged.set(root.rootPath, root);
+    }
+    for (const root of additionalRoots) {
+        if (!merged.has(root.rootPath)) {
+            merged.set(root.rootPath, root);
+        }
+    }
+    return [...merged.values()];
 };
 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: "View findings by skill", value: "by-skill" },
-        { 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;
+    while (true) {
+        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: "View findings by skill", value: "by-skill" },
+            { 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));
+            continue;
+        }
+        write(renderFindings(selectedFindings));
+    }
 };
 const runRepairAgentFlow = async (report, input) => {
     try {

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) => {
@@ -303,7 +346,7 @@ const resourceCategory = (referencePath) => {
         return "references";
     if (referencePath.startsWith("scripts/"))
         return "scripts";
-    return "progressive-disclosure";
+    return "assets";
 };
 const isNonTrivialSkill = (body) => body.length > 500 || WORKFLOW_STEP_PATTERN.test(body) || RESOURCE_REFERENCE_PATTERN.test(body);
 const hasParentTraversal = (referencePath) => referencePath.split(/[\\/]+/).includes("..");

package/dist/domain/scan-skills.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scan-skills.d.ts","sourceRoot":"","sources":["../../src/domain/scan-skills.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAuB,UAAU,EAAe,SAAS,EAAE,MAAM,YAAY,CAAC;AAE1F,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,CAAC;CACtC,CAAC;AAEF,eAAO,MAAM,cAAc,GAAU,OAAO,mBAAmB,KAAG,OAAO,CAAC,UAAU,CAmDnF,CAAC"}
+{"version":3,"file":"scan-skills.d.ts","sourceRoot":"","sources":["../../src/domain/scan-skills.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAuB,UAAU,EAAe,SAAS,EAAE,MAAM,YAAY,CAAC;AAE1F,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,CAAC;CACtC,CAAC;AAEF,eAAO,MAAM,cAAc,GAAU,OAAO,mBAAmB,KAAG,OAAO,CAAC,UAAU,CAkDnF,CAAC"}

package/dist/domain/scan-skills.js

@@ -2,7 +2,7 @@ import { readdir, readFile } from "node:fs/promises";
 import path from "node:path";
 import { parseSkillContent } from "./parse-skill.js";
 import { validateQualityRules } from "./rules/quality.js";
-import { buildMissingSkillFinding, validateStructuralRules } from "./rules/structural.js";
+import { validateStructuralRules } from "./rules/structural.js";
 export const scanSkillRoots = async (input) => {
     const skills = [];
     const diagnostics = [];
@@ -24,7 +24,6 @@ export const scanSkillRoots = async (input) => {
             const skillPath = path.join(skillDir, "SKILL.md");
             const content = await readFile(skillPath, "utf8").catch(() => null);
             if (content === null) {
-                findings.push(buildMissingSkillFinding({ root, skillDir }));
                 continue;
             }
             skills.push({

package/dist/domain/types.d.ts

@@ -21,7 +21,7 @@ export type ParseFailure = {
     readonly message: string;
 };
 export type FindingSeverity = "error" | "warning" | "advice";
-export type FindingCategory = "frontmatter" | "description" | "body-quality" | "progressive-disclosure" | "references" | "scripts" | "evals" | "portability" | "cross-ecosystem";
+export type FindingCategory = "frontmatter" | "description" | "body-quality" | "progressive-disclosure" | "references" | "assets" | "scripts" | "evals" | "portability" | "cross-ecosystem";
 export type Finding = {
     readonly ruleId: string;
     readonly severity: FindingSeverity;

package/dist/domain/types.d.ts.map

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

package/package.json

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