vskill 1.2.3 → 1.2.6

package/dist/commands/add.js

@@ -1,15 +1,17 @@
 // ---------------------------------------------------------------------------
 // vskill install -- install a skill from GitHub or local plugin directory
 // ---------------------------------------------------------------------------
-import { mkdirSync, writeFileSync, readFileSync, existsSync, statSync, chmodSync, readdirSync, rmSync, } from "node:fs";
+import { mkdirSync, writeFileSync, readFileSync, existsSync, statSync, chmodSync, readdirSync, rmSync, lstatSync, } from "node:fs";
 import { join, resolve, basename } from "node:path";
 import os from "node:os";
 import { resolveTilde } from "../utils/paths.js";
 import { reportInstall, reportInstallBatch, submitSkill } from "../api/client.js";
 import { filterAgents } from "../utils/agent-filter.js";
 import { detectInstalledAgents, AGENTS_REGISTRY } from "../agents/agents-registry.js";
+import { agentGlobalInstallDirs, resolveAgentGlobalSkillsDir } from "../agents/global-dirs.js";
 import { ensureLockfile, writeLockfile, readLockfile, removeSkillFromLock } from "../lockfile/index.js";
 import { buildGitHubInstallLockEntry } from "./add-lockfile.js";
+import { prepareGitHubSkillBundle } from "./add-github-bundle.js";
 import { runTier1Scan } from "../scanner/index.js";
 import { getAvailablePlugins, getPluginSource, getPluginVersion, hasPlugin, discoverUnregisteredPlugins } from "../marketplace/index.js";
 import { checkInstallSafety, checkLocalInstallSafety } from "../blocklist/blocklist.js";
@@ -36,30 +38,9 @@ import { extractFrontmatterVersion } from "../utils/version.js";
 import { claudePluginInstall, claudePluginUninstall, claudePluginMarketplaceAdd, claudePluginMarketplaceList, } from "../utils/claude-plugin.js";
 import { buildPerAgentReport, resolvePluginId, } from "../lib/skill-lifecycle.js";
 // ---------------------------------------------------------------------------
-/**
- * Subdirectories fetched alongside SKILL.md when installing a skill that lives
- * in a repo subdirectory. Must stay a subset of the prefixes the installer
- * accepts in installer/bundle-files.ts, or the write is rejected.
- */
-export const BUNDLE_SUBDIRS = ["agents", "references", "scripts", "assets", "tests"];
-/**
- * Extensions carried in a skill bundle. Bundle contents are transported as
- * UTF-8 strings, so this is a text-only allowlist — binaries would be corrupted.
- */
-const BUNDLE_TEXT_EXTENSIONS = [
-    ".md", ".txt", ".json", ".jsonc", ".yaml", ".yml", ".toml", ".csv",
-    ".py", ".sh", ".bash", ".zsh", ".js", ".mjs", ".cjs", ".ts", ".sql",
-    ".excalidraw", ".svg", ".css", ".html",
-];
-/** Per-file and per-skill ceilings, so one fat repo cannot stall an install. */
-const MAX_BUNDLE_FILE_BYTES = 512 * 1024;
-const MAX_BUNDLE_FILES = 100;
-export function isBundleTextFile(name) {
-    const lower = name.toLowerCase();
-    if (lower.startsWith("."))
-        return false; // .DS_Store, dotfiles
-    return BUNDLE_TEXT_EXTENSIONS.some((ext) => lower.endsWith(ext));
-}
+// 0894: a GitHub skill's complete folder is fetched by
+// prepareGitHubSkillBundle (./add-github-bundle.ts) — every nested file,
+// binaries as bytes, exec bits kept, limits that fail instead of truncating.
 /** Validate that a download_url from GitHub Contents API points to a trusted GitHub domain. */
 function isGitHubDownloadUrl(url) {
     try {
@@ -340,24 +321,45 @@ async function installMarketplaceRepo(owner, repo, manifestContent, opts, preSel
     const toUninstall = usedInteractiveCheckbox
         ? [...installedSet].filter((name) => !selectedNames.has(name))
         : [];
+    // 0894: --dry-run stops here, before the deselected-plugin uninstall, the
+    // registry submissions and every file or lockfile write below.
+    if (opts.dryRun) {
+        const dry = await promptInstallOptions(await detectInstalledAgents(), opts);
+        if (dry.global)
+            opts.global = true;
+        printDryRunPlan([...selectedNames], dry.agents, opts, toUninstall);
+        for (const p of selectedPlugins) {
+            enableAfterInstall(p.name, { marketplace: marketplaceName || undefined }, opts);
+        }
+        return;
+    }
     if (toUninstall.length > 0) {
         console.log(dim(`\nUninstalling ${toUninstall.length} deselected plugin${toUninstall.length === 1 ? "" : "s"}...\n`));
         const agents = await detectInstalledAgents();
         for (const skillName of toUninstall) {
             // Remove skill directories from all agents
             let removedCount = 0;
+            const dirs = new Set();
             for (const agent of agents) {
-                const localDir = join(process.cwd(), agent.localSkillsDir, skillName);
-                const globalDir = resolveTilde(join(agent.globalSkillsDir, skillName));
-                for (const dir of [localDir, globalDir]) {
-                    if (existsSync(dir)) {
-                        try {
-                            rmSync(dir, { recursive: true, force: true });
-                            removedCount++;
-                        }
-                        catch (err) {
-                            console.warn(`[vskill] Could not remove ${dir}: ${err instanceof Error ? err.message : String(err)}`);
-                        }
+                dirs.add(join(process.cwd(), agent.localSkillsDir, skillName));
+                // 0894: every global dir vskill may have installed into
+                // (Antigravity's legacy ~/.gemini/antigravity/skills included).
+                for (const globalDir of agentGlobalInstallDirs(agent, resolveTilde)) {
+                    dirs.add(join(globalDir, skillName));
+                }
+            }
+            // 0894: shared readers are installed through the canonical
+            // .agents/skills folder alone, so the canonical copy for the scope this
+            // lockfile tracks goes too (symmetric with install).
+            dirs.add(join(lockDir, lockDir === join(os.homedir(), ".agents") ? "" : ".agents", "skills", skillName));
+            for (const dir of dirs) {
+                if (pathPresent(dir)) {
+                    try {
+                        rmSync(dir, { recursive: true, force: true });
+                        removedCount++;
+                    }
+                    catch (err) {
+                        console.warn(`[vskill] Could not remove ${dir}: ${err instanceof Error ? err.message : String(err)}`);
                     }
                 }
             }
@@ -518,8 +520,7 @@ async function installMarketplaceRepo(owner, repo, manifestContent, opts, preSel
                     // not mutate already-valid frontmatter (no-touch principle).
                     const isRenaming = sd.name !== plugin.name;
                     const processedContent = ensureFrontmatter(content, namespacedName, isRenaming);
-                    for (const agent of agents) {
-                        const baseDir = resolveInstallBase(opts, agent);
+                    for (const baseDir of uniqueInstallBases(opts, agents)) {
                         const skillDir = join(baseDir, sd.name);
                         mkdirSync(skillDir, { recursive: true });
                         writeFileSync(join(skillDir, "SKILL.md"), processedContent, "utf-8");
@@ -535,8 +536,7 @@ async function installMarketplaceRepo(owner, repo, manifestContent, opts, preSel
                 if (contentRes.ok) {
                     const content = await contentRes.text();
                     const processedContent = ensureFrontmatter(content, plugin.name);
-                    for (const agent of agents) {
-                        const baseDir = resolveInstallBase(opts, agent);
+                    for (const baseDir of uniqueInstallBases(opts, agents)) {
                         const skillDir = join(baseDir, plugin.name);
                         mkdirSync(skillDir, { recursive: true });
                         writeFileSync(join(skillDir, "SKILL.md"), processedContent, "utf-8");
@@ -613,9 +613,9 @@ async function installMarketplaceRepo(owner, repo, manifestContent, opts, preSel
     // unenabled. The user saw the skill on disk but Claude Code didn't load
     // it. Treat --global as opt-in to the enable hook (scope = user, since
     // --global is per-machine, not per-repo).
+    // (--dry-run, also an opt-in, returned earlier with its own preview.)
     const userOptedIn = opts.scope !== undefined ||
         opts.global === true ||
-        opts.dryRun === true ||
         opts.enable === false;
     if (userOptedIn) {
         const enabledSoFar = [];
@@ -861,15 +861,46 @@ function resolveSkillsPath(base, localSkillsDir) {
  * Resolve the base directory for local skill installation.
  *
  * Priority:
- * 1. `--global` -> agent's globalSkillsDir
- * 2. default   -> process.cwd() + agent's localSkillsDir
+ * 1. 0894: an agent that reads the shared `.agents/skills` in this scope ->
+ *    that shared folder (same rule as the canonical installer)
+ * 2. `--global` -> agent's global skills dir (Antigravity: legacy-aware)
+ * 3. default   -> process.cwd() + agent's localSkillsDir
  */
 function resolveInstallBase(opts, agent) {
-    if (opts.global) {
-        return resolveTilde(agent.globalSkillsDir);
+    const global = !!opts.global;
+    if (agent.readsSharedSkills?.[global ? "global" : "project"] === true) {
+        return global ? resolveTilde("~/.agents/skills") : join(safeProjectRoot(), ".agents", "skills");
+    }
+    if (global) {
+        return resolveAgentGlobalSkillsDir({ id: agent.id ?? "", globalSkillsDir: agent.globalSkillsDir }, resolveTilde);
     }
     return resolveSkillsPath(safeProjectRoot(), agent.localSkillsDir);
 }
+/** 0894: each distinct install base once — shared readers (Cursor, Codex,
+ *  ...) all resolve to `.agents/skills`, which must get one copy, not one
+ *  per agent. Keeps the first agent seen for each base, in order. */
+function uniqueInstallBases(opts, agents) {
+    return [...new Set(agents.map((a) => resolveInstallBase(opts, a)))];
+}
+/** 0894: true for anything at `p`, including a link whose target is gone. */
+function pathPresent(p) {
+    if (existsSync(p))
+        return true;
+    try {
+        return lstatSync(p).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+/** 0894: the --dry-run report every install path prints instead of writing. */
+function printDryRunPlan(names, agents, opts, uninstall = []) {
+    if (uninstall.length > 0) {
+        console.log(`\nDry run: would uninstall ${uninstall.map((n) => bold(n)).join(", ")}.`);
+    }
+    console.log(`\nDry run: would install ${names.map((n) => bold(n)).join(", ")} ` +
+        `(${opts.global ? "global" : "project"}) for ${agents.map((a) => a.id).join(", ")}. Nothing was written.`);
+}
 /**
  * Prompt the user for agent selection and install method.
  *
@@ -963,9 +994,8 @@ async function promptInstallOptions(agents, opts) {
     console.log(dim(`  Scope: ${bold(scopeLabel)}  |  Method: ${bold(methodLabel)}`));
     console.log(dim(`  Agents (${selectedAgents.length}):`));
     for (const agent of selectedAgents) {
-        const base = useGlobal
-            ? resolveTilde(agent.globalSkillsDir)
-            : resolveSkillsPath(safeProjectRoot(), agent.localSkillsDir);
+        // 0894: same resolver the installs use, so the preview cannot drift.
+        const base = resolveInstallBase({ ...opts, global: useGlobal }, agent);
         console.log(dim(`    ${agent.displayName}: ${base}/`));
     }
     console.log(dim("  ─────────────────────────────────────────────────"));
@@ -1220,11 +1250,23 @@ async function installPluginDir(basePath, pluginName, opts, repoUrl) {
     const version = existsSync(mktPath)
         ? getPluginVersion(pluginName, readFileSync(mktPath, "utf-8")) || "0.0.0"
         : "0.0.0";
+    if (opts.dryRun) {
+        printDryRunPlan([pluginName], selectedAgents, opts);
+        return;
+    }
     // Install: recursively copy plugin directory to each agent
     const sha = computeSha(content);
     const locations = [];
+    const doneBases = new Set();
     for (const agent of selectedAgents) {
-        const cacheDir = join(resolveInstallBase(opts, agent), pluginName);
+        const base = resolveInstallBase(opts, agent);
+        const cacheDir = join(base, pluginName);
+        // 0894: shared readers share one copy in .agents/skills.
+        if (doneBases.has(base)) {
+            locations.push(`${agent.displayName}: ${cacheDir}`);
+            continue;
+        }
+        doneBases.add(base);
         try {
             // Full clean before copy: removes stale files from older installs
             if (existsSync(cacheDir)) {
@@ -1294,7 +1336,17 @@ async function installOneGitHubSkill(owner, repo, skillName, rawUrl, opts, agent
  * through to the lockfile so the studio detail-header anchor resolves to
  * the actual file (not /blob/HEAD/SKILL.md at the repo root).
  */
-sourceSkillPath) {
+sourceSkillPath, 
+/**
+ * 0894: the ONE ref (commit SHA when known) that SKILL.md, the bundle and
+ * the lockfile all use, so they can never come from different commits.
+ */
+ref, 
+/** 0894: lockfile `files` of the previous install of this skill. */
+previousFiles) {
+    if (ref && sourceSkillPath) {
+        rawUrl = `https://raw.githubusercontent.com/${owner}/${repo}/${ref}/${sourceSkillPath}`;
+    }
     // Blocklist + rejection check BEFORE fetching (prevents misleading 404)
     const repoUrl = `https://github.com/${owner}/${repo}`;
     const safety = await checkRepoInstallSafety(skillName, owner, repo);
@@ -1360,9 +1412,29 @@ sourceSkillPath) {
         }
         return { skillName, installed: false, verdict: scanResult.verdict, score: scanResult.score };
     }
-    // Fetch agent files (agents/*.md) if discovered
+    // 0894: the complete skill folder (nested dirs, binaries, exec bits).
+    let bundleFiles;
+    let bundleExecutables;
+    let installedFiles;
+    if (sourceSkillPath) {
+        const prepared = await prepareGitHubSkillBundle({
+            owner,
+            repo,
+            ref: ref || (await getDefaultBranch(owner, repo)),
+            skillMdPath: sourceSkillPath,
+            force: !!opts.force,
+        });
+        if (!prepared.ok) {
+            console.log(red(`  ${prepared.message}`));
+            return { skillName, installed: false, verdict: prepared.verdict, score: scanResult.score };
+        }
+        bundleFiles = Object.keys(prepared.bundle.files).length > 0 ? prepared.bundle.files : undefined;
+        bundleExecutables = prepared.bundle.executables;
+        installedFiles = prepared.bundle.fileList;
+    }
+    // Fetch agent files (agents/*.md) if discovered and the path is unknown
     let agentFiles;
-    if (agentRawUrls && Object.keys(agentRawUrls).length > 0) {
+    if (!sourceSkillPath && agentRawUrls && Object.keys(agentRawUrls).length > 0) {
         agentFiles = {};
         const fetches = Object.entries(agentRawUrls).map(async ([relPath, url]) => {
             try {
@@ -1389,7 +1461,9 @@ sourceSkillPath) {
             scope: opts.global ? "user" : "project",
             projectRoot,
             copy: !!opts.copy,
-            bundleFiles: agentFiles,
+            bundleFiles: bundleFiles ?? agentFiles,
+            bundleExecutables,
+            previousFiles,
         });
     }
     catch (err) {
@@ -1397,7 +1471,7 @@ sourceSkillPath) {
         return { skillName, installed: false, verdict: "WRITE_ERROR", score: scanResult.score };
     }
     const skillVersion = extractFrontmatterVersion(content) || "1.0.0";
-    return { skillName, installed: true, verdict: scanResult.verdict, score: scanResult.score, sha, version: skillVersion, sourceSkillPath };
+    return { skillName, installed: true, verdict: scanResult.verdict, score: scanResult.score, sha, version: skillVersion, sourceSkillPath, files: installedFiles };
 }
 // ---------------------------------------------------------------------------
 // Bulk repo plugin installation: --repo with --all
@@ -1649,9 +1723,29 @@ async function installRepoPlugin(ownerRepo, pluginName, opts, overrideSource) {
     const sha = computeSha(combined);
     const skillFileNames = skills.map((s) => s.name === pluginName ? "SKILL.md" : `${s.name}/SKILL.md`).sort();
     const locations = [];
+    if (opts.dryRun) {
+        printDryRunPlan([pluginName], selectedAgents, opts);
+        const enableResult = enableAfterInstall(pluginName, {}, opts);
+        const report = buildPerAgentReport({
+            skill: pluginName,
+            scope: enableResult.scope,
+            action: "not-applicable",
+            agents: selectedAgents,
+        });
+        for (const line of report)
+            console.log(`  ${dim(">")} ${line.line}`);
+        return;
+    }
+    const doneBases = new Set();
     for (const agent of selectedAgents) {
         const baseDir = resolveInstallBase(opts, agent);
         const plugDir = basename(baseDir) === pluginName ? baseDir : join(baseDir, pluginName);
+        // 0894: shared readers share one copy in .agents/skills.
+        if (doneBases.has(baseDir)) {
+            locations.push(`${agent.displayName}: ${plugDir}`);
+            continue;
+        }
+        doneBases.add(baseDir);
         try {
             // Skills: {agent-dir}/{plugin-name}/{skill-name}/SKILL.md
             for (const skill of skills) {
@@ -1702,9 +1796,9 @@ async function installRepoPlugin(ownerRepo, pluginName, opts, overrideSource) {
     // hence no rollback wiring here) — the gate only surfaces the same
     // acknowledgement + per-agent report as the marketplace path. The identical
     // opt-in condition keeps the default flow unchanged (NFR-005).
+    // (--dry-run, also an opt-in, returned earlier with its own preview.)
     const userOptedIn = opts.scope !== undefined ||
         opts.global === true ||
-        opts.dryRun === true ||
         opts.enable === false;
     if (userOptedIn) {
         const enableResult = enableAfterInstall(pluginName, lock.skills[pluginName], opts);
@@ -1989,12 +2083,20 @@ async function addCommandInner(source, opts) {
             return process.exit(0);
         }
     }
+    if (opts.dryRun) {
+        printDryRunPlan(selectedSkills.map((s) => s.name), selectedAgents, opts);
+        return;
+    }
+    // 0894: resolve the commit ONCE; SKILL.md, bundle and lockfile all use it.
+    const sourceBranch = await getDefaultBranch(owner, repo);
+    const sourceCommitSha = await getBranchHeadSha(owner, repo, sourceBranch);
+    const priorSkills = readLockfile(lockfileRoot(opts))?.skills ?? {};
     // Install selected skills
     const results = [];
     for (const skill of selectedSkills) {
         console.log(dim(`\nInstalling skill: ${bold(skill.name)}...`));
         try {
-            const result = await installOneGitHubSkill(owner, repo, skill.name, skill.rawUrl, opts, selectedAgents, projectRoot, skill.agentRawUrls, skill.path);
+            const result = await installOneGitHubSkill(owner, repo, skill.name, skill.rawUrl, opts, selectedAgents, projectRoot, skill.agentRawUrls, skill.path, sourceCommitSha || sourceBranch, priorSkills[skill.name]?.files);
             results.push(result);
         }
         catch (err) {
@@ -2007,8 +2109,6 @@ async function addCommandInner(source, opts) {
     // `sourceSkillPath` are persisted alongside the legacy `source` string.
     const lockDir = lockfileRoot(opts);
     const lock = ensureLockfile(lockDir);
-    const sourceBranch = await getDefaultBranch(owner, repo);
-    const sourceCommitSha = await getBranchHeadSha(owner, repo, sourceBranch);
     for (const r of results) {
         if (r.installed && r.sha) {
             lock.skills[r.skillName] = buildGitHubInstallLockEntry({
@@ -2021,6 +2121,7 @@ async function addCommandInner(source, opts) {
                 commitSha: sourceCommitSha,
                 pluginName: pluginNameFromSkillPath(r.sourceSkillPath),
                 global: !!opts.global,
+                files: r.files,
             });
         }
     }
@@ -2384,10 +2485,21 @@ async function installFromRegistry(skillName, opts) {
     // Install to each agent
     const sha = computeSha(content);
     const locations = [];
+    if (opts.dryRun) {
+        printDryRunPlan([skillName], selectedAgents, opts);
+        return;
+    }
     const processedContent = ensureFrontmatter(content, skillName);
+    const doneBases = new Set();
     for (const agent of selectedAgents) {
         const baseDir = resolveInstallBase(opts, agent);
         const skillDir = join(baseDir, skillName);
+        // 0894: shared readers share one copy in .agents/skills.
+        if (doneBases.has(baseDir)) {
+            locations.push(`${agent.displayName}: ${skillDir}`);
+            continue;
+        }
+        doneBases.add(baseDir);
         try {
             mkdirSync(skillDir, { recursive: true });
             writeFileSync(join(skillDir, "SKILL.md"), processedContent, "utf-8");
@@ -2465,6 +2577,8 @@ async function installSingleSkillLegacy(owner, repo, skill, opts, skillSubpathOv
     }
     const branch = refOverride || (await getDefaultBranch(owner, repo));
     const sourceCommitSha = await getBranchHeadSha(owner, repo, branch);
+    // 0894: SKILL.md, the bundle and the lockfile all read this one commit.
+    const contentRef = sourceCommitSha || branch;
     // Candidate subpaths: explicit override wins; otherwise try the conventional
     // skills/{name}/ layout first, then root-level {name}/ (e.g. higgsfield-ai/skills).
     const subpathCandidates = skillSubpathOverride
@@ -2477,7 +2591,7 @@ async function installSingleSkillLegacy(owner, repo, skill, opts, skillSubpathOv
     let content;
     for (let i = 0; i < subpathCandidates.length; i++) {
         const candidate = subpathCandidates[i];
-        const candidateUrl = `https://raw.githubusercontent.com/${owner}/${repo}/${branch}/${candidate}`;
+        const candidateUrl = `https://raw.githubusercontent.com/${owner}/${repo}/${contentRef}/${candidate}`;
         const isLast = i === subpathCandidates.length - 1;
         if (isLast) {
             content = await fetchSkillContent(candidateUrl);
@@ -2493,53 +2607,6 @@ async function installSingleSkillLegacy(owner, repo, skill, opts, skillSubpathOv
     }
     if (content === undefined)
         return process.exit(1);
-    // Fetch the skill's bundled subdirectories when the skill lives in a
-    // subdirectory of the repo. These are the skill-authoring convention and the
-    // same prefixes the installer accepts (see installer/bundle-files.ts):
-    // agents/ holds sub-agent prompts, references/ the docs SKILL.md links to,
-    // scripts/ the executable tooling, assets/ static files, tests/ its tests.
-    // A skill whose SKILL.md says "run scripts/foo.py" and installs without
-    // scripts/ is not degraded — it is broken.
-    let legacyAgentFiles;
-    if (skill) {
-        let fetched = 0;
-        for (const subdir of BUNDLE_SUBDIRS) {
-            try {
-                const basePath = skillSubpath.replace(/\/SKILL\.md$/, `/${subdir}`);
-                // ?ref= keeps the listing on the same branch as SKILL.md
-                // (deep links may pin a non-default branch).
-                const dirUrl = `https://api.github.com/repos/${owner}/${repo}/contents/${basePath}?ref=${encodeURIComponent(branch)}`;
-                const dirRes = await githubFetch(dirUrl, { headers: { Accept: "application/vnd.github.v3+json" } });
-                if (!dirRes.ok)
-                    continue;
-                const entries = (await dirRes.json());
-                const wanted = entries.filter((e) => e.type !== "dir" &&
-                    isBundleTextFile(e.name) &&
-                    (e.size ?? 0) <= MAX_BUNDLE_FILE_BYTES &&
-                    e.download_url &&
-                    isGitHubDownloadUrl(e.download_url));
-                if (wanted.length === 0)
-                    continue;
-                legacyAgentFiles ??= {};
-                const budget = wanted.slice(0, Math.max(0, MAX_BUNDLE_FILES - fetched));
-                fetched += budget.length;
-                const fetches = budget.map(async (entry) => {
-                    try {
-                        const res = await githubFetch(entry.download_url);
-                        if (res.ok)
-                            legacyAgentFiles[`${subdir}/${entry.name}`] = await res.text();
-                    }
-                    catch { /* skip */ }
-                });
-                await Promise.allSettled(fetches);
-                if (fetched >= MAX_BUNDLE_FILES)
-                    break;
-            }
-            catch { /* subdir doesn't exist or API error — fine */ }
-        }
-        if (legacyAgentFiles && Object.keys(legacyAgentFiles).length === 0)
-            legacyAgentFiles = undefined;
-    }
     // Platform security check (best-effort, non-blocking on network error).
     // Skipped for private repos: the registry looks skills up by name, so it
     // would leak the name and could match an unrelated public skill.
@@ -2624,6 +2691,26 @@ async function installSingleSkillLegacy(owner, repo, skill, opts, skillSubpathOv
         opts.global = true;
     if (!selections.symlink)
         opts.copy = true;
+    if (opts.dryRun) {
+        printDryRunPlan([skillName], selectedAgents, opts);
+        return;
+    }
+    // 0894: the complete skill folder — every nested file, binaries as bytes,
+    // exec bits kept — read from the same commit, scanned, never truncated; not
+    // downloaded for --dry-run.
+    const prepared = await prepareGitHubSkillBundle({
+        owner,
+        repo,
+        ref: contentRef,
+        skillMdPath: skillSubpath,
+        force: !!opts.force,
+    });
+    if (!prepared.ok) {
+        console.error(red(`\n${prepared.message}`));
+        return process.exit(1);
+    }
+    const bundle = prepared.bundle;
+    const previousFiles = readLockfile(lockfileRoot(opts))?.skills[skillName]?.files;
     // Install to each agent using canonical installer (flat directory, namespaced frontmatter name)
     const namespacedName = pluginNamespace && skillName !== pluginNamespace
         ? `${pluginNamespace}/${skillName}`
@@ -2648,7 +2735,9 @@ async function installSingleSkillLegacy(owner, repo, skill, opts, skillSubpathOv
         scope: opts.global ? "user" : "project",
         projectRoot,
         copy: !!opts.copy,
-        bundleFiles: legacyAgentFiles,
+        bundleFiles: Object.keys(bundle.files).length > 0 ? bundle.files : undefined,
+        bundleExecutables: bundle.executables,
+        previousFiles,
     });
     // Update lockfile (global → ~/.agents/, project → project root).
     // 0743: persist `sourceSkillPath` from the locally-derived `skillSubpath`
@@ -2667,6 +2756,7 @@ async function installSingleSkillLegacy(owner, repo, skill, opts, skillSubpathOv
         commitSha: sourceCommitSha,
         pluginName: pluginNamespace ?? pluginNameFromSkillPath(skillSubpath),
         global: !!opts.global,
+        files: bundle.fileList,
     });
     lock.agents = [...new Set([...(lock.agents || []), ...selectedAgents.map((a) => a.id)])];
     writeLockfile(lock, lockDir);