install-agent-skill 1.2.3

package/bin/add-skill.v2.js

@@ -0,0 +1,512 @@
+#!/usr/bin/env node
+/**
+ * add-agent-skill
+ * Vercel-Style CLI - Full Port v2.0
+ */
+
+import fs from "fs";
+import path from "path";
+import os from "os";
+import { execSync } from "child_process";
+import crypto from "crypto";
+import prompts from "prompts";
+import kleur from "kleur";
+import ora from "ora";
+import boxen from "boxen";
+import { createRequire } from "module";
+
+const require = createRequire(import.meta.url);
+const pkg = (() => {
+    try { return require("../package.json"); } catch { return { version: "4.0.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 REGISTRY_CACHE = path.join(CACHE_ROOT, "registries");
+const REGISTRIES_FILE = path.join(CACHE_ROOT, "registries.json");
+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 LOCKED = flags.has("--locked");
+const OFFLINE = flags.has("--offline");
+
+// --- THEME & SYMBOLS ---
+const S = { branch: "│", diamond: "◇", diamondFilled: "◆", check: "✓", cross: "x", arrow: "→" };
+const c = { cyan: kleur.cyan, gray: kleur.gray, green: kleur.green, red: kleur.red, yellow: kleur.yellow, magenta: kleur.magenta, bold: kleur.bold, dim: kleur.dim };
+
+// --- UI Helpers ---
+function step(text, icon = S.diamond, color = "gray") {
+    console.log(` ${c.gray(S.branch)}  ${c[color](icon)}  ${text}`);
+}
+function stepLine() { console.log(` ${c.gray(S.branch)}`); }
+function fatal(msg) { console.log(` ${c.gray(S.branch)}  ${c.red(S.cross)}  ${c.red(msg)}`); process.exit(1); }
+function success(msg) { console.log(` ${c.gray(S.branch)}  ${c.green(S.check)}  ${c.green(msg)}`); }
+function outputJSON(data) { if (JSON_OUTPUT) console.log(JSON.stringify(data, null, 2)); }
+
+// --- Core Helpers ---
+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 parseSkillMdFrontmatter(p) {
+    try {
+        const content = fs.readFileSync(p, "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 loadRegistries() { try { return fs.existsSync(REGISTRIES_FILE) ? JSON.parse(fs.readFileSync(REGISTRIES_FILE, "utf-8")) : []; } catch { return []; } }
+function saveRegistries(regs) { fs.mkdirSync(path.dirname(REGISTRIES_FILE), { recursive: true }); fs.writeFileSync(REGISTRIES_FILE, JSON.stringify(regs, null, 2)); }
+function loadSkillLock() { const f = path.join(cwd, ".agent", "skill-lock.json"); if (!fs.existsSync(f)) fatal("skill-lock.json not found"); return JSON.parse(fs.readFileSync(f, "utf-8")); }
+
+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() {
+    stepLine();
+    const targetDir = GLOBAL ? GLOBAL_DIR : WORKSPACE;
+    if (fs.existsSync(targetDir)) { step(`Skills directory already exists: ${targetDir}`, S.check, "green"); return; }
+    if (DRY) { step(`Would create: ${targetDir}`, S.diamond); 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");
+    }
+    success(`Initialized: ${targetDir}`);
+}
+
+async function runList() {
+    stepLine();
+    step(c.bold("Installed Skills"), S.diamondFilled, "cyan");
+    console.log(` ${c.gray(S.branch)}  ${c.dim("Location: " + resolveScope())}`);
+    stepLine();
+    const skills = getInstalledSkills();
+    if (skills.length === 0) { step(c.dim("No skills installed."), S.diamond); stepLine(); return; }
+    if (JSON_OUTPUT) { outputJSON({ skills }); return; }
+    for (const s of skills) {
+        const icon = s.hasSkillMd ? c.green(S.check) : c.yellow(S.diamond);
+        console.log(` ${c.gray(S.branch)}  ${icon}  ${c.bold(s.name)} ${c.dim("v" + s.version)} ${c.dim("(" + formatBytes(s.size) + ")")}`);
+        if (s.description && VERBOSE) console.log(` ${c.gray(S.branch)}      ${c.dim(s.description.substring(0, 60))}`);
+    }
+    stepLine();
+    console.log(` ${c.gray(S.branch)}  ${c.dim("Total: " + skills.length + " skill(s)")}`);
+    stepLine();
+}
+
+async function runInstall(spec) {
+    if (!spec) { fatal("Missing skill spec. Usage: add-skill <org/repo>"); return; }
+    const { org, repo, skill: singleSkill, ref } = parseSkillSpec(spec);
+    if (!org || !repo) { fatal("Invalid spec. Format: org/repo or org/repo#skill"); return; }
+    const url = `https://github.com/${org}/${repo}.git`;
+    stepLine();
+    console.log(`  ${c.bgCyan().black(" skills ")}`);
+    console.log();
+    console.log(`  ${c.green(S.diamond)}  Source: ${c.cyan(url)}`);
+    console.log(`  ${c.gray(S.branch)}`);
+    const spinner = ora({ text: "Cloning repository", prefixText: `  ${c.gray(S.branch)}  ${c.cyan(S.diamondFilled)} `, color: "cyan" }).start();
+    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(); console.log(`  ${c.gray(S.branch)}  ${c.red(S.cross)}  ${c.red("Failed to clone")}`); fs.rmSync(tmp, { recursive: true, force: true }); return; }
+    spinner.stop(); console.log(`  ${c.gray(S.branch)}  ${c.green(S.check)}  Repository cloned`);
+    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({ title: e + (m.description ? c.dim(` (${m.description.substring(0, 40)}...)`) : ""), value: e, selected: singleSkill ? e === singleSkill : true }); } }
+    if (skillsInRepo.length === 0) { step(c.yellow("No valid skills found"), S.diamond, "yellow"); fs.rmSync(tmp, { recursive: true, force: true }); return; }
+    stepLine(); step(`Found ${skillsInRepo.length} skills`, S.diamond); stepLine();
+    const skillsR = await prompts({ type: "multiselect", name: "skills", message: "Select skills to install", choices: skillsInRepo, hint: "- Space to select. Return to submit", instructions: false });
+    if (!skillsR.skills || skillsR.skills.length === 0) { console.log(`\n ${c.yellow("Cancelled.")}`); fs.rmSync(tmp, { recursive: true, force: true }); return; }
+    stepLine();
+    const scopeR = await prompts({ type: "select", name: "scope", message: "Installation scope", choices: [{ title: "Project (current directory)", value: "project" }, { title: "Global", value: "global" }], initial: 0 });
+    const targetScope = scopeR.scope === "global" ? GLOBAL_DIR : WORKSPACE;
+    stepLine(); step("Installation Summary", S.diamond); stepLine();
+    let boxContent = ""; for (const sn of skillsR.skills) boxContent += `${c.cyan(sn)}\n  ${c.dim(targetScope)}\n\n`;
+    const box = boxen(boxContent.trim(), { padding: 1, borderStyle: "round", borderColor: "gray", dimBorder: true });
+    box.split("\n").forEach(l => console.log(`  ${c.gray(S.branch)}      ${l}`));
+
+    stepLine(); fs.mkdirSync(targetScope, { recursive: true });
+    for (const sn of skillsR.skills) {
+        const src = path.join(tmp, sn), 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));
+        console.log(`  ${c.gray(S.branch)}  ${c.green(S.check)}  Installed: ${c.bold(sn)}`);
+    }
+    fs.rmSync(tmp, { recursive: true, force: true });
+    stepLine(); console.log(` ${c.cyan("Done!")}`); console.log();
+}
+
+async function runUninstall(skillName) {
+    if (!skillName) fatal("Missing skill name");
+    const scope = resolveScope(), targetDir = path.join(scope, skillName);
+    if (!fs.existsSync(targetDir)) fatal(`Skill not found: ${skillName}`);
+    stepLine();
+    const confirm = await prompts({ type: "confirm", name: "value", message: `Remove skill "${skillName}"?`, initial: false });
+    if (!confirm.value) { step("Cancelled", S.diamond); return; }
+    if (DRY) { step(`Would remove: ${targetDir}`, S.diamond); return; }
+    createBackup(targetDir, skillName);
+    fs.rmSync(targetDir, { recursive: true, force: true });
+    success(`Removed: ${skillName}`); stepLine();
+}
+
+async function runUpdate(skillName) {
+    if (!skillName) fatal("Missing skill name");
+    const scope = resolveScope(), targetDir = path.join(scope, skillName);
+    if (!fs.existsSync(targetDir)) fatal(`Skill not found: ${skillName}`);
+    const metaFile = path.join(targetDir, ".skill-source.json");
+    if (!fs.existsSync(metaFile)) fatal("Skill metadata not found");
+    const meta = JSON.parse(fs.readFileSync(metaFile, "utf-8"));
+    if (!meta.repo || meta.repo === "local") fatal("Cannot update local skill");
+    stepLine();
+    const spinner = ora({ text: `Updating ${skillName}`, prefixText: ` ${c.gray(S.branch)}  ${c.cyan(S.diamondFilled)} `, color: "cyan" }).start();
+    try {
+        if (!DRY) { createBackup(targetDir, skillName); fs.rmSync(targetDir, { recursive: true, force: true }); }
+        const spec = `${meta.repo}#${meta.skill}${meta.ref ? "@" + meta.ref : ""}`;
+        if (DRY) { spinner.stop(); step(`Would update: ${skillName}`, S.diamond); } else { await runInstall(spec); }
+    } catch (err) { spinner.stop(); step(`Failed: ${err.message}`, S.cross, "red"); }
+}
+
+function runLock() {
+    if (!fs.existsSync(WORKSPACE)) fatal("No .agent/skills directory");
+    stepLine();
+    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: `add-agent-skill@${pkg.version}`, skills };
+    if (DRY) { step("Would generate skill-lock.json", S.diamond); outputJSON(lock); return; }
+    fs.mkdirSync(path.join(cwd, ".agent"), { recursive: true });
+    fs.writeFileSync(path.join(cwd, ".agent", "skill-lock.json"), JSON.stringify(lock, null, 2));
+    success("skill-lock.json generated"); stepLine();
+    outputJSON(lock);
+}
+
+function runVerify() {
+    const scope = resolveScope();
+    if (!fs.existsSync(scope)) { stepLine(); step("No skills directory found", S.diamond); return; }
+    stepLine(); step(c.bold("Verifying Skills"), S.diamondFilled, "cyan"); stepLine();
+    let issues = 0;
+    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)) { step(`${name}: ${c.red("missing metadata")}`, S.cross, "red"); issues++; continue; }
+        const m = JSON.parse(fs.readFileSync(mf, "utf-8")), actual = merkleHash(dir);
+        if (actual !== m.checksum) { step(`${name}: ${c.red("checksum mismatch")}`, S.cross, "red"); issues++; }
+        else step(`${name}: ${c.green("OK")}`, S.check, "green");
+    }
+    stepLine(); console.log(` ${c.gray(S.branch)}  ${issues ? c.red(issues + " issue(s)") : c.green("All verified")}`); stepLine();
+    if (issues && STRICT) process.exit(1);
+}
+
+function runDoctor() {
+    const scope = resolveScope();
+    if (!fs.existsSync(scope)) { stepLine(); step("No skills directory found", S.diamond); return; }
+    stepLine(); step(c.bold("Health Check"), S.diamondFilled, "cyan"); stepLine();
+    let errors = 0, warnings = 0;
+    const lock = fs.existsSync(path.join(cwd, ".agent", "skill-lock.json")) ? loadSkillLock() : 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"))) { step(`${name}: ${c.red("missing SKILL.md")}`, S.cross, "red"); errors++; continue; }
+        const mf = path.join(dir, ".skill-source.json");
+        if (!fs.existsSync(mf)) { step(`${name}: ${c.red("missing metadata")}`, S.cross, "red"); errors++; continue; }
+        const m = JSON.parse(fs.readFileSync(mf, "utf-8")), actual = merkleHash(dir);
+        if (actual !== m.checksum) {
+            if (FIX && !DRY) { m.checksum = actual; fs.writeFileSync(mf, JSON.stringify(m, null, 2)); step(`${name}: ${c.yellow("checksum fixed")}`, S.diamond, "yellow"); }
+            else { step(`${name}: ${c.yellow("checksum drift")}`, S.diamond, "yellow"); STRICT ? errors++ : warnings++; }
+        } else if (lock && !lock.skills[name]) { step(`${name}: ${c.yellow("not in lock")}`, S.diamond, "yellow"); STRICT ? errors++ : warnings++; }
+        else step(`${name}: ${c.green("healthy")}`, S.check, "green");
+    }
+    stepLine(); console.log(` ${c.gray(S.branch)}  Errors: ${errors}, Warnings: ${warnings}`); stepLine();
+    if (STRICT && errors) process.exit(1);
+}
+
+function runCache(sub) {
+    stepLine();
+    if (sub === "clear") {
+        if (DRY) { step(`Would clear: ${CACHE_ROOT}`, S.diamond); return; }
+        if (fs.existsSync(CACHE_ROOT)) { const size = getDirSize(CACHE_ROOT); fs.rmSync(CACHE_ROOT, { recursive: true, force: true }); success(`Cache cleared (${formatBytes(size)})`); }
+        else step("Cache already empty", S.diamond);
+        return;
+    }
+    if (sub === "info" || !sub) {
+        if (!fs.existsSync(CACHE_ROOT)) { step("Cache is empty", S.diamond); return; }
+        const rs = fs.existsSync(REGISTRY_CACHE) ? getDirSize(REGISTRY_CACHE) : 0;
+        const bs = fs.existsSync(BACKUP_DIR) ? getDirSize(BACKUP_DIR) : 0;
+        step(c.bold("Cache Info"), S.diamondFilled, "cyan");
+        console.log(` ${c.gray(S.branch)}  Location: ${CACHE_ROOT}`);
+        console.log(` ${c.gray(S.branch)}  Registries: ${formatBytes(rs)}`);
+        console.log(` ${c.gray(S.branch)}  Backups: ${formatBytes(bs)}`);
+        console.log(` ${c.gray(S.branch)}  Total: ${formatBytes(getDirSize(CACHE_ROOT))}`);
+        stepLine(); return;
+    }
+    if (sub === "backups") {
+        const backups = listBackups();
+        if (backups.length === 0) { step("No backups found", S.diamond); return; }
+        step(c.bold("Backups"), S.diamondFilled, "cyan"); stepLine();
+        backups.forEach(b => console.log(` ${c.gray(S.branch)}  ${b.name} (${formatBytes(b.size)})`));
+        stepLine(); return;
+    }
+    fatal(`Unknown cache subcommand: ${sub}`);
+}
+
+function runValidate(skillName) {
+    const scope = resolveScope();
+    let skillsToValidate = [];
+    if (skillName) { const sd = path.join(scope, skillName); if (!fs.existsSync(sd)) fatal(`Skill not found: ${skillName}`); skillsToValidate = [{ name: skillName, path: sd }]; }
+    else skillsToValidate = getInstalledSkills();
+    if (skillsToValidate.length === 0) { stepLine(); step("No skills to validate", S.diamond); return; }
+    stepLine(); step(c.bold("Antigravity Validation"), S.diamondFilled, "cyan"); stepLine();
+    let totalErrors = 0, totalWarnings = 0;
+    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 ? c.red("FAIL") : warnings.length > 0 ? c.yellow("WARN") : c.green("PASS");
+        console.log(` ${c.gray(S.branch)}  ${status}  ${c.bold(skill.name)}`);
+        if (VERBOSE || errors.length || warnings.length) { errors.forEach(e => console.log(` ${c.gray(S.branch)}      ${c.red("ERROR: " + e)}`)); warnings.forEach(w => console.log(` ${c.gray(S.branch)}      ${c.yellow("WARN: " + w)}`)); }
+        totalErrors += errors.length; totalWarnings += warnings.length;
+    }
+    stepLine(); console.log(` ${c.gray(S.branch)}  Total: ${skillsToValidate.length}, Errors: ${totalErrors}, Warnings: ${totalWarnings}`); stepLine();
+    if (STRICT && totalErrors > 0) process.exit(1);
+}
+
+function runAnalyze(skillName) {
+    if (!skillName) fatal("Missing skill name");
+    const scope = resolveScope(), skillDir = path.join(scope, skillName);
+    if (!fs.existsSync(skillDir)) fatal(`Skill not found: ${skillName}`);
+    stepLine(); step(c.bold(`Skill Analysis: ${skillName}`), S.diamondFilled, "cyan");
+    console.log(` ${c.gray(S.branch)}  ${c.dim("Path: " + skillDir)}`); stepLine();
+    const smp = path.join(skillDir, "SKILL.md");
+    if (fs.existsSync(smp)) {
+        const m = parseSkillMdFrontmatter(smp);
+        console.log(` ${c.gray(S.branch)}  ${c.cyan("SKILL.md Frontmatter:")}`);
+        console.log(` ${c.gray(S.branch)}    Name: ${m.name || c.dim("(not set)")}`);
+        console.log(` ${c.gray(S.branch)}    Description: ${m.description ? m.description.substring(0, 60) : c.red("(MISSING)")}`);
+        if (m.tags) console.log(` ${c.gray(S.branch)}    Tags: ${m.tags.join(", ")}`);
+        stepLine();
+    }
+    const structure = detectSkillStructure(skillDir);
+    console.log(` ${c.gray(S.branch)}  ${c.cyan("Structure:")}`);
+    const items = [["resources", structure.hasResources], ["examples", structure.hasExamples], ["scripts", structure.hasScripts], ["constitution", structure.hasConstitution], ["doctrines", structure.hasDoctrines]];
+    items.forEach(([n, has]) => console.log(` ${c.gray(S.branch)}    ${has ? c.green(S.check) : c.dim("○")} ${has ? c.bold(n) : c.dim(n)}`));
+    stepLine();
+    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 ? c.green : score >= 50 ? c.yellow : c.red;
+    console.log(` ${c.gray(S.branch)}  ${c.cyan("Antigravity Score:")} ${scoreColor(score + "/100")}`);
+    stepLine();
+}
+
+function runInfo(name) {
+    if (!name) fatal("Missing skill name");
+    const scope = resolveScope(), localDir = path.join(scope, name);
+    stepLine();
+    if (fs.existsSync(localDir)) {
+        step(`${c.bold(name)} ${c.green("(installed)")}`, S.diamondFilled, "cyan");
+        console.log(` ${c.gray(S.branch)}  ${c.dim("Path: " + localDir)}`);
+        const mf = path.join(localDir, ".skill-source.json");
+        if (fs.existsSync(mf)) { const m = JSON.parse(fs.readFileSync(mf, "utf-8")); console.log(` ${c.gray(S.branch)}  Repo: ${m.repo || "local"}`); console.log(` ${c.gray(S.branch)}  Installed: ${formatDate(m.installedAt)}`); }
+        stepLine(); return;
+    }
+    step(`Skill not installed: ${name}`, S.diamond, "yellow"); stepLine();
+}
+
+async function runHelp() {
+    console.log(`
+  ${c.bold("add-skill")} ${c.dim("v" + pkg.version)}
+
+  ${c.bold("Usage")}
+    $ add-skill <command> [options]
+
+  ${c.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
+
+  ${c.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
+`);
+}
+
+// --- 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(c.red("\nError: " + err.message)); process.exit(1); });

package/bin/lib/commands/analyze.js

@@ -0,0 +1,70 @@
+/**
+ * @fileoverview Analyze command - Skill structure analysis
+ */
+
+import fs from "fs";
+import path from "path";
+import { resolveScope, getDirSize } from "../helpers.js";
+import { parseSkillMdFrontmatter, detectSkillStructure } from "../skills.js";
+import { step, stepLine, S, c, fatal } from "../ui.js";
+
+/**
+ * Analyze skill structure
+ * @param {string} skillName - Skill to analyze
+ */
+export async function run(skillName) {
+    if (!skillName) fatal("Missing skill name");
+
+    const scope = resolveScope();
+    const skillDir = path.join(scope, skillName);
+
+    if (!fs.existsSync(skillDir)) fatal(`Skill not found: ${skillName}`);
+
+    stepLine();
+    step(c.bold(`Skill Analysis: ${skillName}`), S.diamondFilled, "cyan");
+    console.log(` ${c.gray(S.branch)}  ${c.dim("Path: " + skillDir)}`);
+    stepLine();
+
+    // SKILL.md frontmatter
+    const smp = path.join(skillDir, "SKILL.md");
+    if (fs.existsSync(smp)) {
+        const m = parseSkillMdFrontmatter(smp);
+        console.log(` ${c.gray(S.branch)}  ${c.cyan("SKILL.md Frontmatter:")}`);
+        console.log(` ${c.gray(S.branch)}    Name: ${m.name || c.dim("(not set)")}`);
+        console.log(` ${c.gray(S.branch)}    Description: ${m.description ? m.description.substring(0, 60) : c.red("(MISSING)")}`);
+        if (m.tags) console.log(` ${c.gray(S.branch)}    Tags: ${m.tags.join(", ")}`);
+        stepLine();
+    }
+
+    // Structure
+    const structure = detectSkillStructure(skillDir);
+    console.log(` ${c.gray(S.branch)}  ${c.cyan("Structure:")}`);
+
+    const items = [
+        ["resources", structure.hasResources],
+        ["examples", structure.hasExamples],
+        ["scripts", structure.hasScripts],
+        ["constitution", structure.hasConstitution],
+        ["doctrines", structure.hasDoctrines]
+    ];
+
+    items.forEach(([n, has]) => {
+        console.log(` ${c.gray(S.branch)}    ${has ? c.green(S.check) : c.dim("○")} ${has ? c.bold(n) : c.dim(n)}`);
+    });
+
+    stepLine();
+
+    // Antigravity Score
+    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 ? c.green : score >= 50 ? c.yellow : c.red;
+    console.log(` ${c.gray(S.branch)}  ${c.cyan("Antigravity Score:")} ${scoreColor(score + "/100")}`);
+    stepLine();
+}

package/bin/lib/commands/cache.js

@@ -0,0 +1,65 @@
+/**
+ * @fileoverview Cache command
+ */
+
+import fs from "fs";
+import { step, stepLine, S, c, fatal, success } from "../ui.js";
+import { getDirSize, formatBytes, listBackups } from "../helpers.js";
+import { CACHE_ROOT, REGISTRY_CACHE, BACKUP_DIR, DRY } from "../config.js";
+
+/**
+ * Manage cache
+ * @param {string} [sub] - Subcommand: info, clear, backups
+ */
+export async function run(sub) {
+    stepLine();
+
+    if (sub === "clear") {
+        if (DRY) {
+            step(`Would clear: ${CACHE_ROOT}`, S.diamond);
+            return;
+        }
+        if (fs.existsSync(CACHE_ROOT)) {
+            const size = getDirSize(CACHE_ROOT);
+            fs.rmSync(CACHE_ROOT, { recursive: true, force: true });
+            success(`Cache cleared (${formatBytes(size)})`);
+        } else {
+            step("Cache already empty", S.diamond);
+        }
+        return;
+    }
+
+    if (sub === "info" || !sub) {
+        if (!fs.existsSync(CACHE_ROOT)) {
+            step("Cache is empty", S.diamond);
+            return;
+        }
+
+        const rs = fs.existsSync(REGISTRY_CACHE) ? getDirSize(REGISTRY_CACHE) : 0;
+        const bs = fs.existsSync(BACKUP_DIR) ? getDirSize(BACKUP_DIR) : 0;
+
+        step(c.bold("Cache Info"), S.diamondFilled, "cyan");
+        console.log(` ${c.gray(S.branch)}  Location: ${CACHE_ROOT}`);
+        console.log(` ${c.gray(S.branch)}  Registries: ${formatBytes(rs)}`);
+        console.log(` ${c.gray(S.branch)}  Backups: ${formatBytes(bs)}`);
+        console.log(` ${c.gray(S.branch)}  Total: ${formatBytes(getDirSize(CACHE_ROOT))}`);
+        stepLine();
+        return;
+    }
+
+    if (sub === "backups") {
+        const backups = listBackups();
+        if (backups.length === 0) {
+            step("No backups found", S.diamond);
+            return;
+        }
+
+        step(c.bold("Backups"), S.diamondFilled, "cyan");
+        stepLine();
+        backups.forEach(b => console.log(` ${c.gray(S.branch)}  ${b.name} (${formatBytes(b.size)})`));
+        stepLine();
+        return;
+    }
+
+    fatal(`Unknown cache subcommand: ${sub}`);
+}