vskill 0.5.138 → 0.5.140

package/README.md

@@ -18,8 +18,8 @@
 <br/>
 
 ```bash
-npx vskill studio        # open the local IDE for AI skills
-npx vskill install remotion-best-practices
+npx vskill@latest studio        # open the local IDE for AI skills
+npx vskill@latest install remotion-best-practices
 ```
 
 <br/>
@@ -40,7 +40,7 @@ vskill is built around three problems:
 ## Skill Studio — the local IDE for skills
 
 ```bash
-npx vskill studio
+npx vskill@latest studio
 ```
 
 A localhost workbench opens at a deterministic per-project port. You can:
@@ -77,13 +77,13 @@ Every install runs the full pipeline. SARIF v2.1.0 output is available for CI (`
 
 ```bash
 # Install one skill
-npx vskill install remotion-dev/skills/remotion-best-practices
+npx vskill@latest install remotion-dev/skills/remotion-best-practices
 
 # Browse a repo, pick interactively
-npx vskill install remotion-dev/skills
+npx vskill@latest install remotion-dev/skills
 
 # Install a Claude Code plugin (full domain bundle)
-npx vskill install --repo anton-abyzov/vskill --plugin frontend
+npx vskill@latest install --repo anton-abyzov/vskill --plugin frontend
 ```
 
 Install globally for repeat use: `npm i -g vskill`
@@ -115,7 +115,7 @@ Install globally for repeat use: `npm i -g vskill`
 | **easychamp** | tournament-manager |
 | **productivity** | survey-passing |
 
-Install all eight: `npx vskill install --repo anton-abyzov/vskill --all`
+Install all eight: `npx vskill@latest install --repo anton-abyzov/vskill --all`
 
 Browse the full catalog → [verified-skill.com/docs/plugins](https://verified-skill.com/docs/plugins)
 
@@ -124,15 +124,15 @@ Browse the full catalog → [verified-skill.com/docs/plugins](https://verified-s
 ## Commands you'll actually use
 
 ```bash
-vskill studio                          # open local IDE
-vskill install <skill-or-plugin>       # install with full security scan
-vskill find <query>                    # search verified-skill.com registry
-vskill list --installed                # what's installed where
-vskill diff <skill> v1 v2              # compare versions before upgrading
-vskill skill new                       # create a new skill (AI-assisted)
-vskill eval sweep <skill>              # benchmark across models
-vskill audit --ci                      # SARIF v2.1.0 for CI
-vskill keys set anthropic              # store API keys in ~/.vskill/keys.env
+npx vskill@latest studio               # open local IDE
+npx vskill@latest install <skill>      # install with full security scan
+npx vskill@latest find <query>         # search verified-skill.com registry
+npx vskill@latest list --installed     # what's installed where
+npx vskill@latest diff <skill> v1 v2   # compare versions before upgrading
+npx vskill@latest skill new            # create a new skill (AI-assisted)
+npx vskill@latest eval sweep <skill>   # benchmark across models
+npx vskill@latest audit --ci           # SARIF v2.1.0 for CI
+npx vskill@latest keys set anthropic   # store API keys in ~/.vskill/keys.env
 ```
 
 Full reference → [verified-skill.com/docs/cli-reference](https://verified-skill.com/docs/cli-reference)

package/agents.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "generatedAt": "2026-04-26T17:43:52.006Z",
+  "generatedAt": "2026-04-26T18:39:18.872Z",
   "agentPrefixes": [
     ".adal",
     ".agent",

package/dist/commands/stamp-versions.d.ts

@@ -0,0 +1,25 @@
+interface StampOptions {
+    /** Roots to walk. When omitted, defaults to ~/.claude/skills + ~/.claude/plugins/cache. */
+    root?: string[];
+    /** Default version to stamp when missing. */
+    version?: string;
+    /** When true, write changes to disk; otherwise dry-run (just report). */
+    write?: boolean;
+    /** When true, emit one path per line instead of human report. */
+    json?: boolean;
+}
+interface FileResult {
+    path: string;
+    action: "stamped" | "skipped-has-version" | "skipped-no-frontmatter" | "error";
+    current?: string | null;
+    next?: string;
+    error?: string;
+}
+export declare function stampVersionsCommand(opts?: StampOptions): Promise<{
+    scanned: number;
+    stamped: number;
+    alreadyHadVersion: number;
+    errors: number;
+    results: FileResult[];
+}>;
+export {};

package/dist/commands/stamp-versions.js

@@ -0,0 +1,153 @@
+// ---------------------------------------------------------------------------
+// 0759 Phase 7 (B1) — `vskill stamp-versions` command.
+//
+// Walks local skill installation roots and injects `version: "1.0.0"` into the
+// frontmatter of any SKILL.md that is missing a version field. Opt-in only —
+// never runs automatically. Defaults to dry-run; pass `--write` to actually
+// modify files.
+//
+// Default scopes (when no --root passed):
+//   - ~/.claude/skills/                       (Claude Code personal skills)
+//   - ~/.claude/plugins/cache/*/skills/       (plugin-cached skills)
+//
+// Skips files whose frontmatter already declares a version (idempotent).
+// Skips files outside the user's home dir as a safety check.
+// ---------------------------------------------------------------------------
+import { promises as fs } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve, sep } from "node:path";
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---(?:\n|$)/;
+const VERSION_LINE_RE = /^version:\s*["']?([^"'\n]+?)["']?\s*$/m;
+async function findSkillMdFiles(roots) {
+    const found = [];
+    for (const root of roots) {
+        try {
+            await walk(root, found);
+        }
+        catch {
+            // Missing root — silently skip.
+        }
+    }
+    return found;
+}
+async function walk(dir, out) {
+    let entries;
+    try {
+        entries = await fs.readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const full = join(dir, entry.name);
+        if (entry.isSymbolicLink())
+            continue;
+        if (entry.isDirectory()) {
+            await walk(full, out);
+        }
+        else if (entry.isFile() && entry.name === "SKILL.md") {
+            out.push(full);
+        }
+    }
+}
+function injectVersion(content, version) {
+    const versionLine = `version: "${version}"`;
+    const fm = content.match(FRONTMATTER_RE);
+    if (!fm) {
+        // No frontmatter at all — prepend a minimal one.
+        return `---\n${versionLine}\n---\n${content}`;
+    }
+    if (VERSION_LINE_RE.test(fm[1])) {
+        return content; // already has version → no-op
+    }
+    const newBlock = `${versionLine}\n${fm[1]}`;
+    const closer = fm[0].endsWith("---\n") ? "---\n" : "---";
+    const before = content.slice(0, fm.index ?? 0);
+    const after = content.slice((fm.index ?? 0) + fm[0].length);
+    return `${before}---\n${newBlock}\n${closer}${after}`;
+}
+export async function stampVersionsCommand(opts = {}) {
+    const home = homedir();
+    const defaultRoots = [
+        join(home, ".claude", "skills"),
+        join(home, ".claude", "plugins", "cache"),
+    ];
+    const roots = (opts.root && opts.root.length > 0 ? opts.root : defaultRoots).map((r) => resolve(r));
+    const version = opts.version ?? "1.0.0";
+    const write = !!opts.write;
+    // Safety: refuse to walk a root that isn't under $HOME (prevents ./. or /).
+    const safeRoots = [];
+    for (const r of roots) {
+        if (r === home || r === resolve(home)) {
+            // Refuse a literal home root — would scan EVERYTHING.
+            console.error(`vskill stamp-versions: refusing to walk full home dir: ${r}`);
+            continue;
+        }
+        if (!r.startsWith(home + sep)) {
+            console.error(`vskill stamp-versions: refusing to walk outside home: ${r}`);
+            continue;
+        }
+        safeRoots.push(r);
+    }
+    const files = await findSkillMdFiles(safeRoots);
+    const results = [];
+    let stamped = 0;
+    let already = 0;
+    let errors = 0;
+    for (const path of files) {
+        try {
+            const content = await fs.readFile(path, "utf8");
+            const fm = content.match(FRONTMATTER_RE);
+            if (!fm) {
+                // No frontmatter — we'd be creating one. That's invasive; skip in dry-run
+                // by default and only act on existing-frontmatter cases for stamp-versions.
+                // The full publish flow stamps unconditionally; this CLI is conservative.
+                results.push({ path, action: "skipped-no-frontmatter" });
+                continue;
+            }
+            if (VERSION_LINE_RE.test(fm[1])) {
+                const m = fm[1].match(VERSION_LINE_RE);
+                results.push({ path, action: "skipped-has-version", current: m?.[1] ?? null });
+                already++;
+                continue;
+            }
+            const next = injectVersion(content, version);
+            if (write) {
+                await fs.writeFile(path, next, "utf8");
+            }
+            results.push({ path, action: "stamped", next: version });
+            stamped++;
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            results.push({ path, action: "error", error: msg });
+            errors++;
+        }
+    }
+    // Reporting
+    if (opts.json) {
+        process.stdout.write(JSON.stringify({ scanned: files.length, stamped, alreadyHadVersion: already, errors, results, dryRun: !write, version }, null, 2) + "\n");
+    }
+    else {
+        const dryNote = write ? "(applied)" : "(dry-run — pass --write to apply)";
+        process.stdout.write(`vskill stamp-versions ${dryNote}\n`);
+        process.stdout.write(`  scanned: ${files.length}\n`);
+        process.stdout.write(`  stamped: ${stamped} (with version "${version}")\n`);
+        process.stdout.write(`  already had version: ${already}\n`);
+        process.stdout.write(`  errors: ${errors}\n`);
+        if (stamped > 0) {
+            process.stdout.write(`\nFiles ${write ? "stamped" : "would stamp"}:\n`);
+            for (const r of results.filter((r) => r.action === "stamped")) {
+                process.stdout.write(`  + ${r.path}\n`);
+            }
+        }
+        if (errors > 0) {
+            process.stdout.write(`\nErrors:\n`);
+            for (const r of results.filter((r) => r.action === "error")) {
+                process.stdout.write(`  ! ${r.path}: ${r.error}\n`);
+            }
+        }
+    }
+    return { scanned: files.length, stamped, alreadyHadVersion: already, errors, results };
+}
+//# sourceMappingURL=stamp-versions.js.map

package/dist/commands/stamp-versions.js.map

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

package/dist/eval-server/api-routes.js

@@ -14,7 +14,7 @@ import { resolveSkillApiName as resolveSkillApiNameImpl } from "./skill-name-res
 import { runBenchmarkSSE, runSingleCaseSSE } from "./benchmark-runner.js";
 import { getSkillSemaphore } from "./concurrency.js";
 import { resolveSkillDir, resolveAllowedSkillDir } from "./skill-resolver.js";
-import { setSkillDirEntry } from "./skill-dir-registry.js";
+import { setSkillDirEntry, ensurePluginCacheEntry } from "./skill-dir-registry.js";
 import { pickInstalledVersion, readSkillMd, sha256Hex, } from "./installed-version.js";
 import { extractFrontmatterVersion } from "../utils/version.js";
 import { classifyOrigin, scanSkillsTriScope, dedupeByDir } from "../eval/skill-scanner.js";
@@ -1876,12 +1876,20 @@ export function registerRoutes(router, root, projectName) {
             join(home, ".claude/skills"),
         ];
     };
-    const resolveSkillDirForFsRoute = (plugin, skill) => resolveAllowedSkillDir(root, plugin, skill, skillFsAllowedRoots());
+    // 0769 F-002: cold-server deep links to /api/skills/:plugin/:skill/files (or
+    // /file) hit the route before the user has visited /api/skills, so the
+    // SkillDirRegistry hasn't been populated yet. Lazy-fill it on registry miss
+    // by running scanInstalledPluginSkills once. Subsequent calls hit the fast
+    // path via setSkillDirEntry inside ensurePluginCacheEntry.
+    const resolveSkillDirForFsRoute = async (plugin, skill) => {
+        await ensurePluginCacheEntry(plugin, skill);
+        return resolveAllowedSkillDir(root, plugin, skill, skillFsAllowedRoots());
+    };
     // Get skill detail
     router.get("/api/skills/:plugin/:skill", async (req, res, params) => {
         let skillDir;
         try {
-            skillDir = resolveSkillDirForFsRoute(params.plugin, params.skill);
+            skillDir = await resolveSkillDirForFsRoute(params.plugin, params.skill);
         }
         catch (err) {
             sendJson(res, { error: err.message }, 400, req);
@@ -1899,7 +1907,7 @@ export function registerRoutes(router, root, projectName) {
     router.get("/api/skills/:plugin/:skill/files", async (req, res, params) => {
         let skillDir;
         try {
-            skillDir = resolveSkillDirForFsRoute(params.plugin, params.skill);
+            skillDir = await resolveSkillDirForFsRoute(params.plugin, params.skill);
         }
         catch (err) {
             sendJson(res, { error: err.message }, 400, req);
@@ -1960,7 +1968,7 @@ export function registerRoutes(router, root, projectName) {
     router.get("/api/skills/:plugin/:skill/file", async (req, res, params) => {
         let skillDir;
         try {
-            skillDir = resolveSkillDirForFsRoute(params.plugin, params.skill);
+            skillDir = await resolveSkillDirForFsRoute(params.plugin, params.skill);
         }
         catch (err) {
             sendJson(res, { error: err.message }, 400, req);