vskill 0.5.107 → 0.5.109

package/README.md

@@ -133,11 +133,15 @@ Then invoke as `/plugin:skill` in your agent:
 
 ```
 vskill install <source>     Install skill after security scan
+vskill enable <skill>       Enable a previously-installed skill in Claude Code
+vskill disable <skill>      Disable a skill (keep files on disk; flip the toggle)
 vskill find <query>         Search the verified-skill.com registry
 vskill scan <path>          Run security scan without installing
 vskill list                 Show installed skills with status
+vskill list --installed     Per-scope enabled/disabled status table
 vskill remove <skill>       Remove an installed skill
 vskill update [skill]       Update with diff scanning (--all for everything)
+vskill cleanup              Remove stale plugin entries and orphaned cache
 vskill audit [path]         Full project security audit with LLM analysis
 vskill info <skill>         Show detailed skill information
 vskill submit <source>      Submit a skill for verification
@@ -147,6 +151,108 @@ vskill diff <s> <from> <to> Show multi-file diff between two versions
 vskill keys <cmd> [provider] Manage LLM API keys (set/list/remove/path)
 ```
 
+## Enable / Disable
+
+`vskill install` extracts a skill's files and (when the source is a Claude
+Code marketplace plugin) registers the plugin in `~/.claude/settings.json`'s
+`enabledPlugins`. Once installed, you can toggle it without re-downloading:
+
+```bash
+# Disable a skill — keeps files on disk, just removes the enabledPlugins entry.
+vskill disable foo
+
+# Re-enable later — same plugin id, no network round-trip.
+vskill enable foo
+
+# Project-scope toggle (writes <cwd>/.claude/settings.json instead of ~/).
+vskill enable foo --scope project
+
+# Preview what would happen (prints the exact `claude plugin install/uninstall`
+# invocation, no subprocess spawn).
+vskill enable foo --dry-run
+vskill disable foo --dry-run
+
+# Verbose — shows resolved binary path + scope + cwd.
+vskill enable foo --verbose
+
+# Machine-readable JSON.
+vskill enable foo --json
+```
+
+Both commands wrap `claude plugin install/uninstall` per
+[ADR 0724-01](../../.specweave/docs/internal/architecture/adr/0724-01-skill-enable-disable-via-claude-cli.md)
+— vskill never writes `settings.json` directly. The commands are
+**idempotent**: running `vskill enable foo` twice prints
+`foo already enabled in user scope` on the second run and exits 0.
+
+### Install with `--no-enable`
+
+For CI pipelines that want the files on disk and the lockfile entry written
+but **not** the plugin registered:
+
+```bash
+vskill install anton-abyzov/skill-foo --no-enable
+# … later, when you actually want it active:
+vskill enable foo
+```
+
+### `vskill list --installed`
+
+Joins `vskill.lock` with `enabledPlugins` reads at user and project scope:
+
+```
+$ vskill list --installed
+
+Installed Skills (3)
+
+Skill   Version  Source                       User Scope  Project Scope
+foo     1.0.0    marketplace:o/r#foo          enabled     disabled
+bar     2.1.0    marketplace:o/r#bar          disabled    enabled
+baz     0.1.0    github:o/r#baz               n/a         n/a
+```
+
+The `n/a` rows are auto-discovered skills (no `marketplace` field in their
+lockfile entry) — there's nothing to toggle for them; agents pick them up
+directly from their `localSkillsDir`/`globalSkillsDir` on the filesystem.
+
+JSON output (`--installed --json`) emits one object per skill with
+`{name, version, source, enabledUser, enabledProject, autoDiscovered}` —
+suitable for piping into `jq`.
+
+### Multi-agent surface awareness
+
+When you have Claude Code AND Cursor AND Codex CLI installed, both
+`install` and `enable` print a per-agent line so you know exactly which
+surface received the registration:
+
+```
+$ vskill enable foo
+
+Enabled foo (foo@m) in user scope.
+  > Claude Code (user) — enabled via claude CLI
+  > Cursor — auto-discovers from .cursor/skills (no plugin enable needed)
+  > Codex CLI — auto-discovers from .codex/skills (no plugin enable needed)
+```
+
+For non-Claude-Code agents that auto-discover from disk, there is nothing
+to toggle — the skill is live the moment its files exist in the agent's
+`localSkillsDir`/`globalSkillsDir`. To stop loading, run
+`vskill remove <name>`.
+
+### `vskill cleanup --dry-run`
+
+Preview which stale `enabledPlugins` entries would be removed before
+running the real cleanup:
+
+```bash
+vskill cleanup --dry-run
+# Dry-run — preview of stale plugin uninstalls:
+#   > claude plugin uninstall --scope user -- old-foo@m
+#   > claude plugin uninstall --scope project -- old-bar@m
+#
+# 2 stale entries removed from user scope, 0 from project scope, 5 in-sync skills left untouched.
+```
+
 ## Compare skill versions
 
 `vskill diff <skill> <from> <to>` fetches a multi-file diff from
@@ -203,6 +309,9 @@ See [https://github.com/anton-abyzov/vskill/compare/4f2285d...71a9132](https://g
 | `--force` | Install even if blocklisted |
 | `--cwd <path>` | Override project root |
 | `--all` | Install all skills from a repo |
+| `--no-enable` | Install files + lockfile entry, but skip `claude plugin install` |
+| `--scope <scope>` | Plugin enable scope: `user` or `project` |
+| `--dry-run` | Preview install / enable invocations without executing |
 
 </details>
 

package/agents.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "generatedAt": "2026-04-25T05:54:03.282Z",
+  "generatedAt": "2026-04-25T16:51:01.756Z",
   "agentPrefixes": [
     ".adal",
     ".agent",

package/dist/commands/add.d.ts

@@ -1,3 +1,4 @@
+import type { AgentDefinition } from "../agents/agents-registry.js";
 interface MarketplaceDetectionResult {
     isMarketplace: boolean;
     manifestContent?: string;
@@ -29,5 +30,40 @@ interface AddOptions {
     _targetSkill?: string;
     /** Filter which skills to install from a plugin (comma-separated names) */
     onlySkills?: string;
+    /** When false (--no-enable), skip the post-install `claude plugin install` step. */
+    enable?: boolean;
+    /** Explicit settings.json scope for the enable step. Falls back to `global ? "user" : "project"`. */
+    scope?: "user" | "project";
+    /** Print what enable / lockfile mutations would happen, no side effects. */
+    dryRun?: boolean;
 }
+/**
+ * 0724 T-006: post-install claude-plugin enable hook.
+ *
+ * @internal exported for unit tests in __tests__/add-no-enable.test.ts —
+ * driving the helper directly is much cheaper than threading the entire
+ * addCommand() through fake GitHub fetches and tarball extraction.
+ *
+ * Called once per just-installed marketplace plugin entry, after the
+ * lockfile has been written. Honours `opts.enable === false` (--no-enable)
+ * and `opts.dryRun`. Resolves the plugin id via shared helper. Throws on
+ * failure so the caller can roll back the filesystem extraction
+ * (AC-US1-05).
+ */
+export declare function enableAfterInstall(skillName: string, entry: {
+    marketplace?: string;
+}, opts: AddOptions): {
+    invoked: boolean;
+    pluginId: string | null;
+    scope: "user" | "project";
+};
+/**
+ * 0724 T-006: rollback the on-disk extraction + lockfile entry when
+ * `claudePluginInstall` throws (AC-US1-05). Best-effort — wraps each rm in
+ * try/catch so a partial filesystem state doesn't suppress the underlying
+ * diagnostic.
+ *
+ * @internal exported for unit tests; see `enableAfterInstall` note above.
+ */
+export declare function rollbackInstall(skillName: string, agents: AgentDefinition[], opts: AddOptions): void;
 export declare function addCommand(source: string | undefined, opts: AddOptions): Promise<void>;

package/dist/commands/add.js

@@ -27,6 +27,12 @@ import { getMarketplaceName } from "../marketplace/index.js";
 import { rankSearchResults, formatSkillId, getTrustBadge, formatResultLine } from "../utils/skill-display.js";
 import { computeSha } from "../updater/source-fetcher.js";
 import { extractFrontmatterVersion } from "../utils/version.js";
+// 0724 T-006: enable-after-install path. We delegate every enabledPlugins
+// mutation to the claude CLI (ADR 0724-01), and we honour the --no-enable
+// flag to skip it. Uninstall is imported for F-003 rollback of earlier
+// already-enabled plugins on a partway failure.
+import { claudePluginInstall, claudePluginUninstall } from "../utils/claude-plugin.js";
+import { buildPerAgentReport, resolvePluginId, } from "../lib/skill-lifecycle.js";
 // ---------------------------------------------------------------------------
 /** Validate that a download_url from GitHub Contents API points to a trusted GitHub domain. */
 function isGitHubDownloadUrl(url) {
@@ -529,6 +535,86 @@ async function installMarketplaceRepo(owner, repo, manifestContent, opts, preSel
         }
     }
     writeLockfile(lockForWrite, lockDir);
+    // 0724 T-006 (AC-US1-01..05): claude-plugin enable hook + rollback on failure.
+    // Per-agent report is emitted for each successfully-installed plugin so users
+    // see exactly which agent surfaces received the registration.
+    //
+    // Backward-compat (NFR-005): the hook only fires when the user opts into
+    // the new surface — i.e., they pass --scope, --no-enable, or --dry-run.
+    // Without an opt-in, vskill install behaves exactly as before so existing
+    // tests, scripts, and CI pipelines see no behaviour change. AC-US1-01 is
+    // read as "when the install flow performs the enable, it does so via
+    // claudePluginInstall(<id>, <scope>) exactly once per scope chosen" —
+    // i.e., it constrains *how* we enable, not *whether* we always enable.
+    // A future major bump will flip this gate to always-on once distribution
+    // can also surface --no-enable as the off-switch.
+    //
+    // When the gate fires, we track every successful enable in
+    // `enabledSoFar` so that a later failure rolls back all earlier
+    // already-enabled plugins (otherwise we'd leave exactly the stale
+    // `enabledPlugins` entries that `vskill cleanup` is meant to fix).
+    const userOptedIn = opts.scope !== undefined ||
+        opts.dryRun === true ||
+        opts.enable === false;
+    if (userOptedIn) {
+        const enabledSoFar = [];
+        for (const r of results) {
+            if (!r.installed)
+                continue;
+            const entry = lockForWrite.skills[r.name];
+            if (!entry)
+                continue;
+            try {
+                const enableResult = enableAfterInstall(r.name, entry, opts);
+                if (enableResult.invoked && enableResult.pluginId) {
+                    enabledSoFar.push({
+                        name: r.name,
+                        pluginId: enableResult.pluginId,
+                        scope: enableResult.scope,
+                    });
+                }
+                const action = enableResult.invoked ? "enabled" : "not-applicable";
+                const report = buildPerAgentReport({
+                    skill: r.name,
+                    scope: enableResult.scope,
+                    action,
+                    agents,
+                });
+                for (const line of report)
+                    console.log(`  ${dim(">")} ${line.line}`);
+            }
+            catch (err) {
+                // AC-US1-05: rollback on failure (filesystem + lockfile + earlier
+                // already-enabled plugins to avoid leaving stale enabledPlugins).
+                const failedScope = opts.scope ?? (opts.global ? "user" : "project");
+                console.error(red(`Failed to enable ${r.name} in ${failedScope} scope: ${err.message}`));
+                rollbackInstall(r.name, agents, opts);
+                // F-003: undo earlier successful enables to keep settings.json
+                // clean. Static import — see top of file.
+                //
+                // Invariant: every plugin in `enabledSoFar` was installed in this
+                // single addCommand invocation, so they all share the same `opts`
+                // (and therefore the same effective install base resolved by
+                // resolveInstallBase). The captured `prev.scope` is what the enable
+                // hook actually used, which equals what add.ts computes today from
+                // the shared opts. If a future change introduces per-plugin scope
+                // override during a batch install, this loop must capture and
+                // replay each prev's installBase too — otherwise on-disk rollback
+                // would target the wrong path.
+                for (const prev of enabledSoFar) {
+                    try {
+                        claudePluginUninstall(prev.pluginId, prev.scope, prev.scope === "project" ? { cwd: process.cwd() } : undefined);
+                    }
+                    catch {
+                        /* best-effort */
+                    }
+                    rollbackInstall(prev.name, agents, opts);
+                }
+                process.exit(1);
+                return;
+            }
+        }
+    }
     // Telemetry — batch report for all installed plugins (awaited to prevent process exit race)
     const repoUrl = `${owner}/${repo}`;
     const installedSkills = results
@@ -562,6 +648,69 @@ async function installMarketplaceRepo(owner, repo, manifestContent, opts, preSel
 // ---------------------------------------------------------------------------
 import { copyPluginFiltered, isSkillMdCandidate, shouldSkipFromCommands, } from "../shared/copy-plugin-filtered.js";
 export { copyPluginFiltered, isSkillMdCandidate, shouldSkipFromCommands };
+/**
+ * 0724 T-006: post-install claude-plugin enable hook.
+ *
+ * @internal exported for unit tests in __tests__/add-no-enable.test.ts —
+ * driving the helper directly is much cheaper than threading the entire
+ * addCommand() through fake GitHub fetches and tarball extraction.
+ *
+ * Called once per just-installed marketplace plugin entry, after the
+ * lockfile has been written. Honours `opts.enable === false` (--no-enable)
+ * and `opts.dryRun`. Resolves the plugin id via shared helper. Throws on
+ * failure so the caller can roll back the filesystem extraction
+ * (AC-US1-05).
+ */
+export function enableAfterInstall(skillName, entry, opts) {
+    const scope = opts.scope ?? (opts.global ? "user" : "project");
+    const pluginId = resolvePluginId(skillName, entry);
+    if (pluginId === null) {
+        if (!opts.dryRun) {
+            console.log(dim(`Auto-discovered by agents from skills dir — no enable step needed.`));
+        }
+        return { invoked: false, pluginId: null, scope };
+    }
+    if (opts.enable === false) {
+        if (!opts.dryRun) {
+            console.log(dim(`--no-enable: skipped claude plugin install for ${pluginId}.`));
+        }
+        return { invoked: false, pluginId, scope };
+    }
+    if (opts.dryRun) {
+        console.log(dim(`Dry-run: would invoke ${cyan(`claude plugin install --scope ${scope} -- ${pluginId}`)}`));
+        return { invoked: false, pluginId, scope };
+    }
+    claudePluginInstall(pluginId, scope, scope === "project" ? { cwd: process.cwd() } : undefined);
+    return { invoked: true, pluginId, scope };
+}
+/**
+ * 0724 T-006: rollback the on-disk extraction + lockfile entry when
+ * `claudePluginInstall` throws (AC-US1-05). Best-effort — wraps each rm in
+ * try/catch so a partial filesystem state doesn't suppress the underlying
+ * diagnostic.
+ *
+ * @internal exported for unit tests; see `enableAfterInstall` note above.
+ */
+export function rollbackInstall(skillName, agents, opts) {
+    for (const agent of agents) {
+        const baseDir = resolveInstallBase(opts, agent);
+        const skillDir = join(baseDir, skillName);
+        try {
+            if (existsSync(skillDir)) {
+                rmSync(skillDir, { recursive: true, force: true });
+            }
+        }
+        catch {
+            // best-effort
+        }
+    }
+    try {
+        removeSkillFromLock(skillName);
+    }
+    catch {
+        // best-effort
+    }
+}
 /** Returns process.cwd() as the project root for skill installation. */
 function safeProjectRoot() {
     return process.cwd();