install-agent-skill 1.2.3

package/bin/add-skill.js

@@ -0,0 +1,889 @@
+#!/usr/bin/env node
+/**
+ * @dataguruin/add-skill
+ * Vercel-Style CLI - Exact Match with @clack/prompts
+ */
+
+import fs from "fs";
+import path from "path";
+import os from "os";
+import { execSync } from "child_process";
+import crypto from "crypto";
+import * as p from "@clack/prompts";
+import chalk from "chalk";
+import { createRequire } from "module";
+
+const require = createRequire(import.meta.url);
+const pkg = (() => {
+    try { return require("../package.json"); } catch { return { version: "4.1.0" }; }
+})();
+
+// --- CONFIG & CONSTANTS ---
+const cwd = process.cwd();
+const WORKSPACE = path.join(cwd, ".agent", "skills");
+const GLOBAL_DIR = path.join(os.homedir(), ".gemini", "antigravity", "skills");
+const CACHE_ROOT = process.env.ADD_SKILL_CACHE_DIR || path.join(os.homedir(), ".cache", "add-skill");
+const BACKUP_DIR = path.join(CACHE_ROOT, "backups");
+
+// Args
+const args = process.argv.slice(2);
+const command = args[0] || "help";
+const flags = new Set(args.filter((a) => a.startsWith("--")));
+const params = args.filter((a) => !a.startsWith("--")).slice(1);
+
+const GLOBAL = flags.has("--global") || flags.has("-g");
+const VERBOSE = flags.has("--verbose") || flags.has("-v");
+const JSON_OUTPUT = flags.has("--json");
+const FORCE = flags.has("--force") || flags.has("-f");
+const DRY = flags.has("--dry-run");
+const STRICT = flags.has("--strict");
+const FIX = flags.has("--fix");
+const YES = flags.has("--yes") || flags.has("-y");
+
+// --- Helper Functions ---
+function resolveScope() {
+    if (GLOBAL) return GLOBAL_DIR;
+    if (fs.existsSync(path.join(cwd, ".agent"))) return WORKSPACE;
+    return GLOBAL_DIR;
+}
+
+function getDirSize(dir) {
+    let size = 0;
+    try {
+        const walk = (p) => {
+            for (const f of fs.readdirSync(p)) {
+                const full = path.join(p, f);
+                const stat = fs.statSync(full);
+                if (stat.isDirectory()) walk(full);
+                else size += stat.size;
+            }
+        };
+        walk(dir);
+    } catch { }
+    return size;
+}
+
+function formatBytes(bytes) {
+    if (bytes < 1024) return bytes + " B";
+    if (bytes < 1024 * 1024) return (bytes / 1024).toFixed(1) + " KB";
+    return (bytes / 1024 / 1024).toFixed(1) + " MB";
+}
+
+function formatDate(iso) { return iso ? new Date(iso).toLocaleDateString() : "unknown"; }
+
+function shortenPath(fullPath, fromCwd = cwd) {
+    const home = os.homedir();
+    if (fullPath.startsWith(home)) return fullPath.replace(home, "~");
+    if (fullPath.startsWith(fromCwd)) return "." + fullPath.slice(fromCwd.length);
+    return fullPath;
+}
+
+function parseSkillMdFrontmatter(filePath) {
+    try {
+        const content = fs.readFileSync(filePath, "utf-8");
+        const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+        if (!match) return {};
+        const meta = {};
+        for (const line of match[1].split(/\r?\n/)) {
+            const i = line.indexOf(":");
+            if (i === -1) continue;
+            const key = line.substring(0, i).trim();
+            const val = line.substring(i + 1).trim();
+            if (key === "tags") meta[key] = val.split(",").map(t => t.trim()).filter(Boolean);
+            else if (key && val) meta[key] = val;
+        }
+        return meta;
+    } catch { return {}; }
+}
+
+function detectSkillStructure(dir) {
+    const s = { hasResources: false, hasExamples: false, hasScripts: false, hasConstitution: false, hasDoctrines: false, hasEnforcement: false, hasProposals: false, directories: [], files: [] };
+    try {
+        for (const item of fs.readdirSync(dir)) {
+            const full = path.join(dir, item);
+            if (fs.statSync(full).isDirectory()) {
+                s.directories.push(item);
+                const l = item.toLowerCase();
+                if (l === "resources") s.hasResources = true;
+                if (l === "examples") s.hasExamples = true;
+                if (l === "scripts") s.hasScripts = true;
+                if (l === "constitution") s.hasConstitution = true;
+                if (l === "doctrines") s.hasDoctrines = true;
+                if (l === "enforcement") s.hasEnforcement = true;
+                if (l === "proposals") s.hasProposals = true;
+            } else s.files.push(item);
+        }
+    } catch { }
+    return s;
+}
+
+function getInstalledSkills() {
+    const scope = resolveScope();
+    const skills = [];
+    if (!fs.existsSync(scope)) return skills;
+    for (const name of fs.readdirSync(scope)) {
+        const dir = path.join(scope, name);
+        if (!fs.statSync(dir).isDirectory()) continue;
+        const metaFile = path.join(dir, ".skill-source.json");
+        const skillFile = path.join(dir, "SKILL.md");
+        if (fs.existsSync(metaFile) || fs.existsSync(skillFile)) {
+            const meta = fs.existsSync(metaFile) ? JSON.parse(fs.readFileSync(metaFile, "utf-8")) : {};
+            const hasSkillMd = fs.existsSync(skillFile);
+            const skillMeta = hasSkillMd ? parseSkillMdFrontmatter(skillFile) : {};
+            skills.push({ name, path: dir, ...meta, hasSkillMd, description: skillMeta.description || meta.description || "", tags: skillMeta.tags || [], author: skillMeta.author || meta.publisher || "", version: skillMeta.version || meta.ref || "unknown", structure: detectSkillStructure(dir), size: getDirSize(dir) });
+        }
+    }
+    return skills;
+}
+
+function merkleHash(dir) {
+    const files = [];
+    const walk = (p) => {
+        for (const f of fs.readdirSync(p)) {
+            if (f === ".skill-source.json") continue;
+            const full = path.join(p, f);
+            const stat = fs.statSync(full);
+            if (stat.isDirectory()) walk(full);
+            else { const h = crypto.createHash("sha256").update(fs.readFileSync(full)).digest("hex"); files.push(`${path.relative(dir, full)}:${h}`); }
+        }
+    };
+    walk(dir);
+    files.sort();
+    return crypto.createHash("sha256").update(files.join("|")).digest("hex");
+}
+
+function parseSkillSpec(spec) {
+    const [repoPart, skillPart] = spec.split("#");
+    const [org, repo] = repoPart.split("/");
+    const [skill, ref] = (skillPart || "").split("@");
+    return { org, repo, skill, ref };
+}
+
+function createBackup(skillDir, skillName) {
+    if (DRY) return null;
+    const ts = new Date().toISOString().replace(/[:.]/g, "-");
+    const bp = path.join(BACKUP_DIR, `${skillName}_${ts}`);
+    fs.mkdirSync(BACKUP_DIR, { recursive: true });
+    fs.cpSync(skillDir, bp, { recursive: true });
+    return bp;
+}
+
+function listBackups(skillName = null) {
+    if (!fs.existsSync(BACKUP_DIR)) return [];
+    const backups = [];
+    for (const name of fs.readdirSync(BACKUP_DIR)) {
+        if (skillName && !name.startsWith(skillName + "_")) continue;
+        const bp = path.join(BACKUP_DIR, name);
+        backups.push({ name, path: bp, createdAt: fs.statSync(bp).mtime, size: getDirSize(bp) });
+    }
+    return backups.sort((a, b) => b.createdAt - a.createdAt);
+}
+
+// --- COMMANDS ---
+
+async function runInit() {
+    console.log();
+    p.intro(chalk.bgCyan.black(" add-skill "));
+
+    const targetDir = GLOBAL ? GLOBAL_DIR : WORKSPACE;
+    if (fs.existsSync(targetDir)) {
+        p.log.success(`Skills directory already exists: ${shortenPath(targetDir)}`);
+        p.outro(chalk.green("Done!"));
+        return;
+    }
+
+    if (DRY) {
+        p.log.info(`Would create: ${shortenPath(targetDir)}`);
+        p.outro(chalk.dim("Dry run complete"));
+        return;
+    }
+
+    fs.mkdirSync(targetDir, { recursive: true });
+    if (!GLOBAL) {
+        const gi = path.join(cwd, ".agent", ".gitignore");
+        if (!fs.existsSync(gi)) fs.writeFileSync(gi, "# Skill caches\nskills/*/.skill-source.json\n");
+    }
+
+    p.log.success(`Initialized skills directory: ${shortenPath(targetDir)}`);
+    p.outro(chalk.green("Done!"));
+}
+
+async function runList() {
+    console.log();
+    p.intro(chalk.bgCyan.black(" add-skill "));
+
+    const skills = getInstalledSkills();
+    const scope = resolveScope();
+
+    p.log.info(`Location: ${chalk.dim(shortenPath(scope))}`);
+
+    if (skills.length === 0) {
+        p.log.message(chalk.dim("No skills installed."));
+        p.outro(chalk.dim("Run add-skill <org/repo> to install skills"));
+        return;
+    }
+
+    if (JSON_OUTPUT) {
+        console.log(JSON.stringify({ skills }, null, 2));
+        return;
+    }
+
+    const lines = [];
+    for (const s of skills) {
+        const icon = s.hasSkillMd ? chalk.green("✓") : chalk.yellow("○");
+        lines.push(`${icon} ${chalk.bold(s.name)} ${chalk.dim("v" + s.version)} ${chalk.dim("(" + formatBytes(s.size) + ")")}`);
+        if (s.description && VERBOSE) {
+            lines.push(`  ${chalk.dim(s.description.substring(0, 60))}`);
+        }
+    }
+
+    p.note(lines.join("\n"), `Installed Skills (${skills.length})`);
+    p.outro(chalk.green("Done!"));
+}
+
+async function runInstall(spec) {
+    console.log();
+    p.intro(chalk.bgCyan.black(" skills "));
+
+    if (!spec) {
+        p.log.error("Missing skill spec. Usage: add-skill <org/repo>");
+        p.outro(chalk.red("Installation failed"));
+        process.exit(1);
+    }
+
+    const { org, repo, skill: singleSkill, ref } = parseSkillSpec(spec);
+    if (!org || !repo) {
+        p.log.error("Invalid spec. Format: org/repo or org/repo#skill");
+        p.outro(chalk.red("Installation failed"));
+        process.exit(1);
+    }
+
+    const url = `https://github.com/${org}/${repo}.git`;
+    const spinner = p.spinner();
+
+    spinner.start("Cloning repository");
+
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "add-skill-"));
+    try {
+        execSync(`git clone --depth=1 ${url} "${tmp}"`, { stdio: "pipe" });
+        if (ref) execSync(`git -C "${tmp}" checkout ${ref}`, { stdio: "pipe" });
+    } catch {
+        spinner.stop(chalk.red("Failed to clone repository"));
+        p.outro(chalk.red("Installation failed"));
+        fs.rmSync(tmp, { recursive: true, force: true });
+        process.exit(1);
+    }
+
+    spinner.stop(`Source: ${chalk.cyan(url)}`);
+
+    // Find skills in repo
+    const skillsInRepo = [];
+    for (const e of fs.readdirSync(tmp)) {
+        const sp = path.join(tmp, e);
+        if (fs.statSync(sp).isDirectory() && fs.existsSync(path.join(sp, "SKILL.md"))) {
+            const m = parseSkillMdFrontmatter(path.join(sp, "SKILL.md"));
+            skillsInRepo.push({
+                value: e,
+                label: e,
+                hint: m.description ? m.description.substring(0, 50) + "..." : undefined
+            });
+        }
+    }
+
+    if (skillsInRepo.length === 0) {
+        p.log.warn("No valid skills found in repository");
+        p.outro(chalk.yellow("No skills to install"));
+        fs.rmSync(tmp, { recursive: true, force: true });
+        return;
+    }
+
+    p.log.success(`Repository cloned`);
+    p.log.info(`Found ${skillsInRepo.length} skills`);
+
+    // Select skills
+    let selectedSkills;
+    if (singleSkill) {
+        selectedSkills = [singleSkill];
+    } else if (YES) {
+        selectedSkills = skillsInRepo.map(s => s.value);
+    } else {
+        const selected = await p.multiselect({
+            message: "Select skills to install",
+            options: skillsInRepo,
+            required: true,
+            initialValues: skillsInRepo.map(s => s.value)
+        });
+
+        if (p.isCancel(selected)) {
+            p.cancel("Installation cancelled");
+            fs.rmSync(tmp, { recursive: true, force: true });
+            process.exit(0);
+        }
+        selectedSkills = selected;
+    }
+
+    // Select scope
+    let installGlobally = GLOBAL;
+    if (!GLOBAL && !YES) {
+        const scope = await p.select({
+            message: "Installation scope",
+            options: [
+                { value: false, label: "Project", hint: "Install in current directory" },
+                { value: true, label: "Global", hint: "Install in home directory" }
+            ]
+        });
+
+        if (p.isCancel(scope)) {
+            p.cancel("Installation cancelled");
+            fs.rmSync(tmp, { recursive: true, force: true });
+            process.exit(0);
+        }
+        installGlobally = scope;
+    }
+
+    const targetScope = installGlobally ? GLOBAL_DIR : WORKSPACE;
+
+    // Show summary
+    const summaryLines = [];
+    for (const sn of selectedSkills) {
+        const shortPath = shortenPath(path.join(targetScope, sn));
+        summaryLines.push(`${chalk.cyan(sn)}`);
+        summaryLines.push(`  ${chalk.dim("→")} ${shortPath}`);
+    }
+
+    p.note(summaryLines.join("\n"), "Installation Summary");
+
+    // Confirm
+    if (!YES) {
+        const confirmed = await p.confirm({
+            message: "Proceed with installation?"
+        });
+
+        if (p.isCancel(confirmed) || !confirmed) {
+            p.cancel("Installation cancelled");
+            fs.rmSync(tmp, { recursive: true, force: true });
+            process.exit(0);
+        }
+    }
+
+    // Install
+    spinner.start("Installing skills...");
+    fs.mkdirSync(targetScope, { recursive: true });
+
+    const installed = [];
+    for (const sn of selectedSkills) {
+        const src = path.join(tmp, sn);
+        const dest = path.join(targetScope, sn);
+        if (fs.existsSync(dest)) fs.rmSync(dest, { recursive: true, force: true });
+        fs.cpSync(src, dest, { recursive: true });
+        const hash = merkleHash(dest);
+        fs.writeFileSync(path.join(dest, ".skill-source.json"), JSON.stringify({ repo: `${org}/${repo}`, skill: sn, ref: ref || null, checksum: hash, installedAt: new Date().toISOString() }, null, 2));
+        installed.push(sn);
+    }
+
+    spinner.stop("Installation complete");
+    fs.rmSync(tmp, { recursive: true, force: true });
+
+    // Show result
+    const resultLines = installed.map(s => `${chalk.green("✓")} ${s}`);
+    p.note(resultLines.join("\n"), chalk.green(`Installed ${installed.length} skill${installed.length !== 1 ? "s" : ""}`));
+
+    console.log();
+    p.outro(chalk.green("Done!"));
+}
+
+async function runUninstall(skillName) {
+    console.log();
+    p.intro(chalk.bgCyan.black(" add-skill "));
+
+    if (!skillName) {
+        p.log.error("Missing skill name");
+        p.outro(chalk.red("Uninstall failed"));
+        process.exit(1);
+    }
+
+    const scope = resolveScope();
+    const targetDir = path.join(scope, skillName);
+
+    if (!fs.existsSync(targetDir)) {
+        p.log.error(`Skill not found: ${skillName}`);
+        p.outro(chalk.red("Uninstall failed"));
+        process.exit(1);
+    }
+
+    if (!YES) {
+        const confirmed = await p.confirm({
+            message: `Remove skill "${skillName}"?`,
+            initialValue: false
+        });
+
+        if (p.isCancel(confirmed) || !confirmed) {
+            p.cancel("Uninstall cancelled");
+            process.exit(0);
+        }
+    }
+
+    if (DRY) {
+        p.log.info(`Would remove: ${shortenPath(targetDir)}`);
+        p.outro(chalk.dim("Dry run complete"));
+        return;
+    }
+
+    createBackup(targetDir, skillName);
+    fs.rmSync(targetDir, { recursive: true, force: true });
+
+    p.log.success(`Removed: ${skillName}`);
+    p.outro(chalk.green("Done!"));
+}
+
+async function runUpdate(skillName) {
+    console.log();
+    p.intro(chalk.bgCyan.black(" add-skill "));
+
+    if (!skillName) {
+        p.log.error("Missing skill name");
+        p.outro(chalk.red("Update failed"));
+        process.exit(1);
+    }
+
+    const scope = resolveScope();
+    const targetDir = path.join(scope, skillName);
+
+    if (!fs.existsSync(targetDir)) {
+        p.log.error(`Skill not found: ${skillName}`);
+        p.outro(chalk.red("Update failed"));
+        process.exit(1);
+    }
+
+    const metaFile = path.join(targetDir, ".skill-source.json");
+    if (!fs.existsSync(metaFile)) {
+        p.log.error("Skill metadata not found");
+        p.outro(chalk.red("Update failed"));
+        process.exit(1);
+    }
+
+    const meta = JSON.parse(fs.readFileSync(metaFile, "utf-8"));
+    if (!meta.repo || meta.repo === "local") {
+        p.log.error("Cannot update local skill");
+        p.outro(chalk.red("Update failed"));
+        process.exit(1);
+    }
+
+    const spinner = p.spinner();
+    spinner.start(`Updating ${skillName}...`);
+
+    try {
+        if (!DRY) {
+            createBackup(targetDir, skillName);
+            fs.rmSync(targetDir, { recursive: true, force: true });
+        }
+        const spec = `${meta.repo}#${meta.skill}${meta.ref ? "@" + meta.ref : ""}`;
+        spinner.stop(`Updated: ${skillName}`);
+        if (!DRY) await runInstall(spec);
+    } catch (err) {
+        spinner.stop(chalk.red(`Failed: ${err.message}`));
+        p.outro(chalk.red("Update failed"));
+    }
+}
+
+function runLock() {
+    console.log();
+    p.intro(chalk.bgCyan.black(" add-skill "));
+
+    if (!fs.existsSync(WORKSPACE)) {
+        p.log.error("No .agent/skills directory");
+        p.outro(chalk.red("Lock failed"));
+        process.exit(1);
+    }
+
+    const skills = {};
+    for (const name of fs.readdirSync(WORKSPACE)) {
+        const dir = path.join(WORKSPACE, name);
+        if (!fs.statSync(dir).isDirectory()) continue;
+        const mf = path.join(dir, ".skill-source.json");
+        if (!fs.existsSync(mf)) continue;
+        const m = JSON.parse(fs.readFileSync(mf, "utf-8"));
+        skills[name] = { repo: m.repo, skill: m.skill, ref: m.ref, checksum: `sha256:${m.checksum}`, publisher: m.publisher || null };
+    }
+
+    const lock = { lockVersion: 1, generatedAt: new Date().toISOString(), generator: `@dataguruin/add-skill@${pkg.version}`, skills };
+
+    if (DRY) {
+        p.log.info("Would generate skill-lock.json");
+        console.log(JSON.stringify(lock, null, 2));
+        p.outro(chalk.dim("Dry run complete"));
+        return;
+    }
+
+    fs.mkdirSync(path.join(cwd, ".agent"), { recursive: true });
+    fs.writeFileSync(path.join(cwd, ".agent", "skill-lock.json"), JSON.stringify(lock, null, 2));
+
+    p.log.success("Generated skill-lock.json");
+    p.outro(chalk.green("Done!"));
+}
+
+function runVerify() {
+    console.log();
+    p.intro(chalk.bgCyan.black(" add-skill "));
+
+    const scope = resolveScope();
+    if (!fs.existsSync(scope)) {
+        p.log.warn("No skills directory found");
+        p.outro(chalk.dim("Nothing to verify"));
+        return;
+    }
+
+    p.log.step("Verifying skills...");
+
+    let issues = 0;
+    const results = [];
+
+    for (const name of fs.readdirSync(scope)) {
+        const dir = path.join(scope, name);
+        if (!fs.statSync(dir).isDirectory()) continue;
+        const mf = path.join(dir, ".skill-source.json");
+        if (!fs.existsSync(mf)) {
+            results.push(`${chalk.red("✗")} ${name}: ${chalk.red("missing metadata")}`);
+            issues++;
+            continue;
+        }
+        const m = JSON.parse(fs.readFileSync(mf, "utf-8"));
+        const actual = merkleHash(dir);
+        if (actual !== m.checksum) {
+            results.push(`${chalk.red("✗")} ${name}: ${chalk.red("checksum mismatch")}`);
+            issues++;
+        } else {
+            results.push(`${chalk.green("✓")} ${name}: ${chalk.green("OK")}`);
+        }
+    }
+
+    p.note(results.join("\n"), "Verification Results");
+
+    if (issues > 0) {
+        p.log.error(`${issues} issue(s) found`);
+        if (STRICT) process.exit(1);
+    } else {
+        p.log.success("All skills verified");
+    }
+
+    p.outro(chalk.green("Done!"));
+}
+
+function runDoctor() {
+    console.log();
+    p.intro(chalk.bgCyan.black(" add-skill "));
+
+    const scope = resolveScope();
+    if (!fs.existsSync(scope)) {
+        p.log.warn("No skills directory found");
+        p.outro(chalk.dim("Nothing to check"));
+        return;
+    }
+
+    p.log.step("Running health check...");
+
+    let errors = 0, warnings = 0;
+    const results = [];
+    const lockFile = path.join(cwd, ".agent", "skill-lock.json");
+    const lock = fs.existsSync(lockFile) ? JSON.parse(fs.readFileSync(lockFile, "utf-8")) : null;
+
+    for (const name of fs.readdirSync(scope)) {
+        const dir = path.join(scope, name);
+        if (!fs.statSync(dir).isDirectory()) continue;
+
+        if (!fs.existsSync(path.join(dir, "SKILL.md"))) {
+            results.push(`${chalk.red("✗")} ${name}: ${chalk.red("missing SKILL.md")}`);
+            errors++;
+            continue;
+        }
+
+        const mf = path.join(dir, ".skill-source.json");
+        if (!fs.existsSync(mf)) {
+            results.push(`${chalk.red("✗")} ${name}: ${chalk.red("missing metadata")}`);
+            errors++;
+            continue;
+        }
+
+        const m = JSON.parse(fs.readFileSync(mf, "utf-8"));
+        const actual = merkleHash(dir);
+
+        if (actual !== m.checksum) {
+            if (FIX && !DRY) {
+                m.checksum = actual;
+                fs.writeFileSync(mf, JSON.stringify(m, null, 2));
+                results.push(`${chalk.yellow("○")} ${name}: ${chalk.yellow("checksum fixed")}`);
+            } else {
+                results.push(`${chalk.yellow("○")} ${name}: ${chalk.yellow("checksum drift")}`);
+                STRICT ? errors++ : warnings++;
+            }
+        } else if (lock && !lock.skills[name]) {
+            results.push(`${chalk.yellow("○")} ${name}: ${chalk.yellow("not in lock")}`);
+            STRICT ? errors++ : warnings++;
+        } else {
+            results.push(`${chalk.green("✓")} ${name}: ${chalk.green("healthy")}`);
+        }
+    }
+
+    p.note(results.join("\n"), "Health Check Results");
+    p.log.info(`Errors: ${errors}, Warnings: ${warnings}`);
+
+    if (STRICT && errors) process.exit(1);
+    p.outro(chalk.green("Done!"));
+}
+
+function runCache(sub) {
+    console.log();
+    p.intro(chalk.bgCyan.black(" add-skill "));
+
+    if (sub === "clear") {
+        if (DRY) {
+            p.log.info(`Would clear: ${shortenPath(CACHE_ROOT)}`);
+            p.outro(chalk.dim("Dry run complete"));
+            return;
+        }
+        if (fs.existsSync(CACHE_ROOT)) {
+            const size = getDirSize(CACHE_ROOT);
+            fs.rmSync(CACHE_ROOT, { recursive: true, force: true });
+            p.log.success(`Cache cleared (${formatBytes(size)})`);
+        } else {
+            p.log.info("Cache already empty");
+        }
+        p.outro(chalk.green("Done!"));
+        return;
+    }
+
+    if (sub === "info" || !sub) {
+        if (!fs.existsSync(CACHE_ROOT)) {
+            p.log.info("Cache is empty");
+            p.outro(chalk.dim("Nothing cached"));
+            return;
+        }
+        const bs = fs.existsSync(BACKUP_DIR) ? getDirSize(BACKUP_DIR) : 0;
+        const lines = [
+            `Location: ${shortenPath(CACHE_ROOT)}`,
+            `Backups: ${formatBytes(bs)}`,
+            `Total: ${formatBytes(getDirSize(CACHE_ROOT))}`
+        ];
+        p.note(lines.join("\n"), "Cache Info");
+        p.outro(chalk.green("Done!"));
+        return;
+    }
+
+    if (sub === "backups") {
+        const backups = listBackups();
+        if (backups.length === 0) {
+            p.log.info("No backups found");
+            p.outro(chalk.dim("Nothing backed up"));
+            return;
+        }
+        const lines = backups.map(b => `${b.name} (${formatBytes(b.size)})`);
+        p.note(lines.join("\n"), `Backups (${backups.length})`);
+        p.outro(chalk.green("Done!"));
+        return;
+    }
+
+    p.log.error(`Unknown cache subcommand: ${sub}`);
+    p.outro(chalk.red("Failed"));
+    process.exit(1);
+}
+
+function runValidate(skillName) {
+    console.log();
+    p.intro(chalk.bgCyan.black(" add-skill "));
+
+    const scope = resolveScope();
+    let skillsToValidate = [];
+
+    if (skillName) {
+        const sd = path.join(scope, skillName);
+        if (!fs.existsSync(sd)) {
+            p.log.error(`Skill not found: ${skillName}`);
+            p.outro(chalk.red("Validation failed"));
+            process.exit(1);
+        }
+        skillsToValidate = [{ name: skillName, path: sd }];
+    } else {
+        skillsToValidate = getInstalledSkills();
+    }
+
+    if (skillsToValidate.length === 0) {
+        p.log.warn("No skills to validate");
+        p.outro(chalk.dim("Nothing to validate"));
+        return;
+    }
+
+    p.log.step("Running Antigravity validation...");
+
+    let totalErrors = 0, totalWarnings = 0;
+    const results = [];
+
+    for (const skill of skillsToValidate) {
+        const errors = [], warnings = [];
+        const smp = path.join(skill.path, "SKILL.md");
+
+        if (!fs.existsSync(smp)) {
+            errors.push("Missing SKILL.md");
+        } else {
+            const m = parseSkillMdFrontmatter(smp);
+            if (!m.description) errors.push("Missing description");
+            else if (m.description.length < 50) warnings.push("Description too short");
+        }
+
+        const status = errors.length > 0 ? chalk.red("FAIL") : warnings.length > 0 ? chalk.yellow("WARN") : chalk.green("PASS");
+        results.push(`${status} ${chalk.bold(skill.name)}`);
+
+        if (VERBOSE || errors.length || warnings.length) {
+            errors.forEach(e => results.push(`  ${chalk.red("ERROR: " + e)}`));
+            warnings.forEach(w => results.push(`  ${chalk.yellow("WARN: " + w)}`));
+        }
+
+        totalErrors += errors.length;
+        totalWarnings += warnings.length;
+    }
+
+    p.note(results.join("\n"), "Validation Results");
+    p.log.info(`Total: ${skillsToValidate.length}, Errors: ${totalErrors}, Warnings: ${totalWarnings}`);
+
+    if (STRICT && totalErrors > 0) process.exit(1);
+    p.outro(chalk.green("Done!"));
+}
+
+function runAnalyze(skillName) {
+    console.log();
+    p.intro(chalk.bgCyan.black(" add-skill "));
+
+    if (!skillName) {
+        p.log.error("Missing skill name");
+        p.outro(chalk.red("Analysis failed"));
+        process.exit(1);
+    }
+
+    const scope = resolveScope();
+    const skillDir = path.join(scope, skillName);
+
+    if (!fs.existsSync(skillDir)) {
+        p.log.error(`Skill not found: ${skillName}`);
+        p.outro(chalk.red("Analysis failed"));
+        process.exit(1);
+    }
+
+    p.log.info(`Path: ${chalk.dim(shortenPath(skillDir))}`);
+
+    const smp = path.join(skillDir, "SKILL.md");
+    const lines = [];
+
+    if (fs.existsSync(smp)) {
+        const m = parseSkillMdFrontmatter(smp);
+        lines.push(chalk.cyan("SKILL.md Frontmatter:"));
+        lines.push(`  Name: ${m.name || chalk.dim("(not set)")}`);
+        lines.push(`  Description: ${m.description ? m.description.substring(0, 60) : chalk.red("(MISSING)")}`);
+        if (m.tags) lines.push(`  Tags: ${m.tags.join(", ")}`);
+        lines.push("");
+    }
+
+    const structure = detectSkillStructure(skillDir);
+    lines.push(chalk.cyan("Structure:"));
+    const items = [["resources", structure.hasResources], ["examples", structure.hasExamples], ["scripts", structure.hasScripts], ["constitution", structure.hasConstitution], ["doctrines", structure.hasDoctrines]];
+    items.forEach(([n, has]) => lines.push(`  ${has ? chalk.green("✓") : chalk.dim("○")} ${has ? chalk.bold(n) : chalk.dim(n)}`));
+    lines.push("");
+
+    let score = 0;
+    if (fs.existsSync(smp)) score += 20;
+    const m = parseSkillMdFrontmatter(smp);
+    if (m.description) score += 25;
+    if (m.tags && m.tags.length > 0) score += 10;
+    if (structure.hasResources || structure.hasExamples || structure.hasScripts) score += 20;
+    if (fs.existsSync(path.join(skillDir, ".skill-source.json"))) score += 10;
+    if (structure.hasConstitution || structure.hasDoctrines) score += 15;
+
+    const scoreColor = score >= 80 ? chalk.green : score >= 50 ? chalk.yellow : chalk.red;
+    lines.push(`${chalk.cyan("Antigravity Score:")} ${scoreColor(score + "/100")}`);
+
+    p.note(lines.join("\n"), `Skill Analysis: ${skillName}`);
+    p.outro(chalk.green("Done!"));
+}
+
+function runInfo(name) {
+    console.log();
+    p.intro(chalk.bgCyan.black(" add-skill "));
+
+    if (!name) {
+        p.log.error("Missing skill name");
+        p.outro(chalk.red("Info failed"));
+        process.exit(1);
+    }
+
+    const scope = resolveScope();
+    const localDir = path.join(scope, name);
+
+    if (fs.existsSync(localDir)) {
+        const lines = [`Path: ${shortenPath(localDir)}`];
+        const mf = path.join(localDir, ".skill-source.json");
+        if (fs.existsSync(mf)) {
+            const m = JSON.parse(fs.readFileSync(mf, "utf-8"));
+            lines.push(`Repo: ${m.repo || "local"}`);
+            lines.push(`Installed: ${formatDate(m.installedAt)}`);
+        }
+        p.note(lines.join("\n"), `${name} ${chalk.green("(installed)")}`);
+        p.outro(chalk.green("Done!"));
+        return;
+    }
+
+    p.log.warn(`Skill not installed: ${name}`);
+    p.outro(chalk.dim("Run add-skill <org/repo> to install"));
+}
+
+async function runHelp() {
+    console.log(`
+  ${chalk.bold("add-skill")} ${chalk.dim("v" + pkg.version)}
+
+  ${chalk.bold("Usage")}
+    $ add-skill <command> [options]
+
+  ${chalk.bold("Commands")}
+    <org/repo>          Install all skills from repository
+    <org/repo#skill>    Install specific skill
+    list                List installed skills
+    uninstall <skill>   Remove a skill
+    update <skill>      Update a skill
+    verify              Verify checksums
+    doctor              Check health
+    lock                Generate skill-lock.json
+    init                Initialize skills directory
+    validate [skill]    Validate against Antigravity spec
+    analyze <skill>     Analyze skill structure
+    cache [info|clear]  Manage cache
+
+  ${chalk.bold("Options")}
+    --global, -g        Use global scope
+    --force, -f         Force operation
+    --strict            Fail on violations
+    --fix               Auto-fix issues
+    --dry-run           Preview only
+    --verbose, -v       Detailed output
+    --json              JSON output
+    --yes, -y           Skip confirmation prompts
+`);
+}
+
+// --- MAIN ---
+async function main() {
+    if (command === "list" || command === "ls") await runList();
+    else if (command === "init") await runInit();
+    else if (command === "install" || command === "add" || command === "i") await runInstall(params[0]);
+    else if (command === "uninstall" || command === "remove" || command === "rm") await runUninstall(params[0]);
+    else if (command === "update") await runUpdate(params[0]);
+    else if (command === "lock") runLock();
+    else if (command === "verify") runVerify();
+    else if (command === "doctor") runDoctor();
+    else if (command === "cache") runCache(params[0]);
+    else if (command === "validate" || command === "check") runValidate(params[0]);
+    else if (command === "analyze") runAnalyze(params[0]);
+    else if (command === "info" || command === "show") runInfo(params[0]);
+    else if (command === "help" || command === "--help" || command === "-h") await runHelp();
+    else if (command === "--version" || command === "-V") console.log(pkg.version);
+    else if (command.includes("/")) await runInstall(command);
+    else { console.log(`Unknown command: ${command}`); await runHelp(); }
+}
+
+main().catch(err => { console.error(chalk.red("\nError: " + err.message)); process.exit(1); });