@yogiadhik/skillcheck 0.1.3 → 0.2.1

package/README.md

@@ -53,8 +53,9 @@ case, no re-run — and `--budget 2.50` stops the run once the cap is
 crossed. The check happens between cases, so one long case can still
 overshoot on its own: pair a budget with `--model haiku` to keep
 single cases cheap. skillcheck tells you when no model is set, and
-warns at the end if a run blew past its budget. Lint never spends
-anything.
+warns at the end if a run blew past its budget. `run --dry-run` shows
+which cases would execute and which would replay from cache before
+anything spends a cent. Lint never spends anything.
 
 ## CI
 
@@ -93,11 +94,12 @@ because the point is the pattern, and the pattern repeats:
   official and community both. Quality is achievable; it's just not
   the default.
 
-Two honest footnotes. First: twice, the loudest "errors" in an audit
-turned out to be this linter's own false positives — links inside
-example code blocks, and templated {baseDir} targets that resolve at
-runtime. Both fixed (0.1.1, 0.1.3), both caught by checking findings
-against the accused code before believing them. Do the same with
+Two honest footnotes. First: three times now, the loudest "errors" in
+an audit turned out to be this linter's own false positives — links
+inside example code blocks, templated {baseDir} targets that resolve
+at runtime, and placeholder links in quoted prose like
+"[Team roster](its link)". All fixed (0.1.1, 0.1.3, 0.2.1), all caught
+by checking findings against the accused code before believing them. Do the same with
 anything this tool tells you. Second: these audits are how skillcheck
 gets tested — every rule here has drawn blood on real files or been
 fixed for crying wolf.

package/dist/cli.js

@@ -3,13 +3,13 @@ import { Command } from 'commander';
 import { initTestFile } from './init.js';
 import { lintPath } from './lint/lint.js';
 import { printGithubAnnotations } from './reporters/github.js';
-import { printFindings, printReports } from './reporters/terminal.js';
-import { discoverTestFiles, reportsPass, runTests } from './runner.js';
+import { printFindings, printPlan, printReports } from './reporters/terminal.js';
+import { discoverTestFiles, planTests, reportsPass, runTests } from './runner.js';
 const program = new Command();
 program
     .name('skillcheck')
     .description('lint and behavioral tests for agent skills')
-    .version('0.1.3');
+    .version('0.2.0');
 program
     .command('lint')
     .argument('[path]', 'skill file or directory', '.')
@@ -39,9 +39,18 @@ program
     .option('--budget <usd>', 'stop once this much has been spent')
     .option('--timeout <seconds>', 'per-case timeout', '300')
     .option('--no-cache', 'ignore and do not write cached results')
+    .option('--dry-run', 'show what would run and what would replay from cache, spending nothing')
     .option('--json', 'machine-readable output')
     .action(async (path, opts) => {
     try {
+        if (opts.dryRun) {
+            const plans = planTests(path, { model: opts.model });
+            if (opts.json)
+                console.log(JSON.stringify(plans, null, 2));
+            else
+                printPlan(plans);
+            return;
+        }
         const files = discoverTestFiles(path);
         if (!opts.json) {
             console.log(`${files.length} test file(s); live agent runs cost money — cap with --budget`);

package/dist/lint/rules.js

@@ -18,8 +18,10 @@ export const descriptionQuality = (s) => {
     const out = [];
     if (d.length < 20)
         out.push(finding(s, 'description-quality', 'warning', 'description under 20 chars; unlikely to trigger reliably'));
-    if (d.length > 1000)
-        out.push(finding(s, 'description-quality', 'warning', 'description over 1000 chars; gets truncated in listings'));
+    // claude code truncates description + when_to_use at 1536 chars combined
+    const whenToUse = typeof s.frontmatter.when_to_use === 'string' ? s.frontmatter.when_to_use : '';
+    if (d.length + whenToUse.length > 1536)
+        out.push(finding(s, 'description-quality', 'warning', 'description over 1536 chars (counting when_to_use); gets truncated in listings'));
     if (!/\b(use|when|for|trigger)\b/i.test(d))
         out.push(finding(s, 'description-quality', 'warning', 'description has no trigger language ("use when ...") — the agent decides from this text alone'));
     return out;
@@ -53,6 +55,9 @@ export const relativeLinks = (s) => {
         // templated targets like {baseDir}/x.md resolve at runtime; can't judge them
         if (target.includes('{'))
             continue;
+        // a destination with a raw space never parses as a markdown link; it's placeholder prose
+        if (/\s/.test(target))
+            continue;
         if (!existsSync(resolve(s.dir, target.split('#')[0])))
             out.push(finding(s, 'relative-links', 'error', `broken relative link: ${target}`));
     }

package/dist/reporters/terminal.js

@@ -7,6 +7,25 @@ export function printFindings(findings) {
     const errors = findings.filter((f) => f.severity === 'error').length;
     console.log(`\n${findings.length} finding(s), ${errors} error(s)`);
 }
+export function printPlan(plans) {
+    let live = 0;
+    let knownCost = 0;
+    for (const p of plans) {
+        if (p.cached) {
+            knownCost += p.lastCostUsd ?? 0;
+            console.log(`${pc.dim('cached   ')} ${p.case} ($${(p.lastCostUsd ?? 0).toFixed(4)} last time, replays free)`);
+        }
+        else {
+            live++;
+            console.log(`${pc.yellow('would run')} ${p.case}`);
+        }
+    }
+    console.log(`\n${plans.length} case(s): ${live} would run live, ${plans.length - live} would replay from cache`);
+    if (live > 0)
+        console.log(pc.yellow(`live cases cost real money and their price is unknown until they run — pair --model haiku with --budget`));
+    else if (plans.length > 0)
+        console.log(pc.dim(`nothing to spend — a real run would replay entirely from cache ($${knownCost.toFixed(4)} when first run)`));
+}
 export function printReports(reports, budgetUsd) {
     let cost = 0;
     for (const r of reports) {

package/dist/runner.js

@@ -29,6 +29,22 @@ export function loadTestFile(path) {
         throw new Error(`${path}: needs a "skill" path and a "cases" list`);
     return { path, skill: doc.skill, cases: doc.cases };
 }
+function caseKey(skillDir, fileDir, c, model) {
+    return hashInputs(c.setup ? [skillDir, resolve(fileDir, c.setup)] : skillDir, YAML.stringify(c) + '\0' + (model ?? ''));
+}
+export function planTests(root, opts = {}) {
+    const cache = new ResultCache(join(process.cwd(), '.skillcheck', 'cache.json'));
+    const plans = [];
+    for (const file of discoverTestFiles(root)) {
+        const testFile = loadTestFile(file);
+        const skillDir = resolve(dirname(file), testFile.skill);
+        for (const c of testFile.cases) {
+            const hit = cache.get(caseKey(skillDir, dirname(file), c, opts.model));
+            plans.push({ file, case: c.name, cached: !!hit, lastCostUsd: hit?.costUsd });
+        }
+    }
+    return plans;
+}
 export async function runTests(root, opts = {}) {
     const adapter = opts.adapter ?? claudeCode;
     const cache = new ResultCache(join(process.cwd(), '.skillcheck', 'cache.json'));
@@ -49,7 +65,7 @@ export async function runTests(root, opts = {}) {
                 });
                 continue;
             }
-            const key = hashInputs(c.setup ? [skillDir, resolve(dirname(file), c.setup)] : skillDir, YAML.stringify(c) + '\0' + (opts.model ?? ''));
+            const key = caseKey(skillDir, dirname(file), c, opts.model);
             if (opts.cache !== false) {
                 const hit = cache.get(key);
                 if (hit) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yogiadhik/skillcheck",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "description": "lint and behavioral tests for agent skills",
   "license": "MIT",
   "author": "Yogesh Adhikari",
@@ -29,6 +29,6 @@
     "@types/cross-spawn": "^6.0.6",
     "@types/node": "^26.1.1",
     "typescript": "^7.0.2",
-    "vitest": "^4.1.10"
+    "vitest": "^5.0.2"
   }
 }