install-agent-skill 1.0.0

package/bin/add-skill.v1.backup.js

@@ -0,0 +1,1904 @@
+#!/usr/bin/env node
+/**
+ * @dataguruin/add-skill
+ * Enterprise-grade Agent Skill Manager
+ * VERSION 4.0.0 - Antigravity Skills Edition
+ *
+ * Features:
+ * - list: Show all installed skills with metadata
+ * - uninstall: Remove a skill
+ * - update: Update a single skill
+ * - cache: Manage cache (clear, info)
+ * - init: Initialize .agent/skills directory
+ * - validate: Validate skill structure against Antigravity spec
+ * - analyze: Analyze SKILL.md frontmatter and structure
+ * - Colored output with fallback
+ * - Progress spinners
+ * - JSON output mode (--json)
+ * - Verbose mode (--verbose)
+ * - Offline mode (--offline)
+ * - Backup before upgrade
+ * - Better error handling
+ * - Enhanced SKILL.md parsing (description, tags, author)
+ * - Progressive Disclosure structure detection
+ */
+
+import { execSync, spawn } from "child_process";
+import fs from "fs";
+import path from "path";
+import os from "os";
+import crypto from "crypto";
+import { createRequire } from "module";
+import { promisify } from "util";
+import readline from "readline";
+
+/* ===================== BOOTSTRAP ===================== */
+
+const require = createRequire(import.meta.url);
+const pkg = (() => {
+    try {
+        return require("../package.json");
+    } catch {
+        return { version: "4.0.0" };
+    }
+})();
+
+const cwd = process.cwd();
+
+/* ===================== CONSTANTS ===================== */
+
+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");
+const CONFIG_FILE = path.join(CACHE_ROOT, "config.json");
+
+/* ===================== ARG PARSE ===================== */
+
+const args = process.argv.slice(2);
+const command = args[0];
+const flags = new Set(args.filter((a) => a.startsWith("--")));
+const params = args.filter((a) => !a.startsWith("--")).slice(1);
+
+const DRY = flags.has("--dry-run");
+const STRICT = flags.has("--strict");
+const FIX = flags.has("--fix");
+const LOCKED = flags.has("--locked");
+const VERBOSE = flags.has("--verbose") || flags.has("-v");
+const JSON_OUTPUT = flags.has("--json");
+const OFFLINE = flags.has("--offline");
+const FORCE = flags.has("--force") || flags.has("-f");
+const GLOBAL = flags.has("--global") || flags.has("-g");
+
+/* ===================== COLORS ===================== */
+
+const supportsColor = process.stdout.isTTY && !process.env.NO_COLOR;
+
+const colors = {
+    reset: supportsColor ? "\x1b[0m" : "",
+    bold: supportsColor ? "\x1b[1m" : "",
+    dim: supportsColor ? "\x1b[2m" : "",
+    red: supportsColor ? "\x1b[31m" : "",
+    green: supportsColor ? "\x1b[32m" : "",
+    yellow: supportsColor ? "\x1b[33m" : "",
+    blue: supportsColor ? "\x1b[34m" : "",
+    magenta: supportsColor ? "\x1b[35m" : "",
+    cyan: supportsColor ? "\x1b[36m" : "",
+};
+
+const icons = {
+    success: supportsColor ? "✅" : "[OK]",
+    error: supportsColor ? "❌" : "[ERROR]",
+    warning: supportsColor ? "⚠️" : "[WARN]",
+    info: supportsColor ? "ℹ️" : "[INFO]",
+    check: supportsColor ? "✔" : "[+]",
+    cross: supportsColor ? "✖" : "[-]",
+    arrow: supportsColor ? "→" : "->",
+    spinner: ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"],
+    package: supportsColor ? "📦" : "[PKG]",
+    lock: supportsColor ? "🔒" : "[LOCK]",
+    rocket: supportsColor ? "🚀" : "[GO]",
+    trash: supportsColor ? "🗑️" : "[DEL]",
+    refresh: supportsColor ? "♻️" : "[UPD]",
+    folder: supportsColor ? "📁" : "[DIR]",
+};
+
+/* ===================== UI ENGINE ===================== */
+
+const theme = {
+    border: supportsColor ? "\x1b[90m" : "", // Gray
+    accent: supportsColor ? "\x1b[36m" : "", // Cyan
+    text: supportsColor ? "\x1b[37m" : "",   // White
+    dim: supportsColor ? "\x1b[2m" : "",     // Dim
+    reset: supportsColor ? "\x1b[0m" : "",
+    success: supportsColor ? "\x1b[32m" : "", // Green
+    error: supportsColor ? "\x1b[31m" : "",   // Red
+    warning: supportsColor ? "\x1b[33m" : "", // Yellow
+};
+
+const symbols = {
+    top: "┌",
+    middle: "│",
+    bottom: "└",
+    item: "◇",
+    success: "✔",
+    error: "✖",
+    arrow: "→",
+};
+
+class TreeUI {
+    constructor(title) {
+        this.title = title;
+        this.stepCount = 0;
+        this.isDone = false;
+
+        // Print Header
+        if (!JSON_OUTPUT) {
+            console.log(); // spacer
+            console.log(`${theme.border}${symbols.top}   ${theme.accent}\x1b[1m${title}${theme.reset}`);
+            console.log(`${theme.border}${symbols.middle}${theme.reset}`);
+        }
+    }
+
+    step(text, icon = symbols.item) {
+        if (JSON_OUTPUT) return;
+        console.log(`${theme.border}${symbols.middle}  ${theme.accent}${icon}  ${theme.text}${text}${theme.reset}`);
+        console.log(`${theme.border}${symbols.middle}${theme.reset}`);
+    }
+
+    log(text) {
+        if (JSON_OUTPUT) return;
+        console.log(`${theme.border}${symbols.middle}      ${theme.dim}${text}${theme.reset}`);
+    }
+
+    success(text) {
+        if (JSON_OUTPUT) return;
+        this.close(text, theme.success, symbols.success);
+    }
+
+    error(text) {
+        if (JSON_OUTPUT) {
+            console.log(JSON.stringify({ success: false, error: text }));
+            return;
+        }
+        this.close(text, theme.error, symbols.error);
+    }
+
+    close(text, color, icon) {
+        if (this.isDone) return;
+        this.isDone = true;
+        console.log(`${theme.border}${symbols.bottom}  ${color}${icon}  ${text}${theme.reset}\n`);
+    }
+}
+
+// Global UI instance
+let ui = new TreeUI("add-skill");
+
+/* ===================== HELPERS ===================== */
+
+function fatal(msg, error = null) {
+    ui.error(msg);
+    if (error && VERBOSE) {
+        console.error(theme.dim + error.stack + theme.reset);
+    }
+    process.exit(1);
+}
+
+function success(msg) { ui.success(msg); }
+function info(msg) { ui.step(msg); }
+function warn(msg) { ui.step(msg, "⚠️"); }
+function verbose(msg) { if (VERBOSE) ui.log(msg); }
+function outputJSON(data) { if (JSON_OUTPUT) console.log(JSON.stringify(data, null, 2)); }
+
+function spin(text) {
+    // Simplified spinner for TreeUI (renders as step)
+    ui.step(text + "...");
+    return {
+        succeed: (t) => { /* already logged start, simplistic approach */ },
+        fail: (t) => ui.log(`${theme.error}Failed: ${t}${theme.reset}`)
+    };
+}
+
+/* ===================== PROMPT ===================== */
+
+async function confirm(question) {
+    if (FORCE) return true;
+    if (!process.stdin.isTTY) return false;
+
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+
+    return new Promise((resolve) => {
+        rl.question(`${question} (y/N) `, (answer) => {
+            rl.close();
+            resolve(answer.toLowerCase() === "y" || answer.toLowerCase() === "yes");
+        });
+    });
+}
+
+/* ===================== CORE HELPERS ===================== */
+
+function merkleHash(dir) {
+    const files = [];
+    function walk(p) {
+        for (const f of fs.readdirSync(p)) {
+            if (f === ".skill-source.json") continue; // exclude metadata
+            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 resolveScope() {
+    if (GLOBAL) return GLOBAL_DIR;
+    if (fs.existsSync(path.join(cwd, ".agent"))) return WORKSPACE;
+    return GLOBAL_DIR;
+}
+
+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 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);
+
+            // Parse SKILL.md frontmatter for Antigravity Skills metadata
+            let skillMeta = {};
+            if (hasSkillMd) {
+                skillMeta = parseSkillMdFrontmatter(skillFile);
+            }
+
+            // Detect Progressive Disclosure structure
+            const structure = detectSkillStructure(dir);
+
+            skills.push({
+                name,
+                path: dir,
+                ...meta,
+                hasSkillMd,
+                // Antigravity Skills metadata
+                description: skillMeta.description || meta.description || "",
+                tags: skillMeta.tags || meta.tags || [],
+                author: skillMeta.author || meta.publisher || "",
+                version: skillMeta.version || meta.ref || "unknown",
+                type: skillMeta.type || "standard",
+                authority: skillMeta.authority || "normal",
+                // Progressive Disclosure structure
+                structure,
+                size: getDirSize(dir),
+            });
+        }
+    }
+
+    return skills;
+}
+
+/**
+ * Parse SKILL.md YAML frontmatter
+ * Supports multi-line description with > syntax
+ */
+function parseSkillMdFrontmatter(skillMdPath) {
+    try {
+        const content = fs.readFileSync(skillMdPath, "utf-8");
+        const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+        if (!match) return {};
+
+        const yaml = match[1];
+        const meta = {};
+        let currentKey = null;
+        let multiLineValue = "";
+        let isMultiLine = false;
+
+        for (const line of yaml.split(/\r?\n/)) {
+
+            // Handle multi-line values (> or |)
+            if (isMultiLine) {
+                if (line.startsWith("  ") || line.trim() === "") {
+                    multiLineValue += " " + line.trim();
+                    continue;
+                } else {
+                    meta[currentKey] = multiLineValue.trim();
+                    isMultiLine = false;
+                }
+            }
+
+            const colonIndex = line.indexOf(":");
+            if (colonIndex === -1) continue;
+
+            const key = line.substring(0, colonIndex).trim();
+            let value = line.substring(colonIndex + 1).trim();
+
+            // Handle multi-line indicator
+            if (value === ">" || value === "|") {
+                isMultiLine = true;
+                currentKey = key;
+                multiLineValue = "";
+                continue;
+            }
+
+            // Handle inline values
+            if (key && value) {
+                // Parse tags as array
+                if (key === "tags") {
+                    meta[key] = value.split(",").map((t) => t.trim()).filter(Boolean);
+                } else {
+                    meta[key] = value;
+                }
+            }
+        }
+
+        // Finalize any pending multi-line value
+        if (isMultiLine && currentKey) {
+            meta[currentKey] = multiLineValue.trim();
+        }
+
+        return meta;
+    } catch (err) {
+        verbose(`Failed to parse SKILL.md: ${err.message}`);
+        return {};
+    }
+}
+
+/**
+ * Detect Progressive Disclosure structure
+ * Returns information about skill's directory structure
+ */
+function detectSkillStructure(skillDir) {
+    const structure = {
+        hasResources: false,
+        hasExamples: false,
+        hasScripts: false,
+        hasConstitution: false,
+        hasDoctrines: false,
+        hasEnforcement: false,
+        hasAssets: false,
+        hasProposals: false,
+        directories: [],
+        files: [],
+    };
+
+    try {
+        const items = fs.readdirSync(skillDir);
+
+        for (const item of items) {
+            const fullPath = path.join(skillDir, item);
+            const stat = fs.statSync(fullPath);
+
+            if (stat.isDirectory()) {
+                structure.directories.push(item);
+
+                // Check for Antigravity Skills standard directories
+                switch (item.toLowerCase()) {
+                    case "resources":
+                        structure.hasResources = true;
+                        break;
+                    case "examples":
+                        structure.hasExamples = true;
+                        break;
+                    case "scripts":
+                        structure.hasScripts = true;
+                        break;
+                    case "constitution":
+                        structure.hasConstitution = true;
+                        break;
+                    case "doctrines":
+                        structure.hasDoctrines = true;
+                        break;
+                    case "enforcement":
+                        structure.hasEnforcement = true;
+                        break;
+                    case "assets":
+                        structure.hasAssets = true;
+                        break;
+                    case "proposals":
+                        structure.hasProposals = true;
+                        break;
+                }
+            } else {
+                structure.files.push(item);
+            }
+        }
+    } catch (err) {
+        verbose(`Failed to detect structure: ${err.message}`);
+    }
+
+    return structure;
+}
+
+
+
+function getDirSize(dir) {
+    let size = 0;
+    function 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);
+    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(isoString) {
+    if (!isoString) return "unknown";
+    const date = new Date(isoString);
+    return date.toLocaleDateString() + " " + date.toLocaleTimeString();
+}
+
+/* ===================== REGISTRY HELPERS ===================== */
+
+function registryCachePath(name) {
+    return path.join(REGISTRY_CACHE, `${name}.json`);
+}
+
+function loadRegistries() {
+    if (!fs.existsSync(REGISTRIES_FILE)) return [];
+    try {
+        return 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 verifyRegistrySignature(index) {
+    if (!index.signature) return false;
+
+    const { algorithm, value, publicKey } = index.signature;
+    if (algorithm !== "ed25519") return false;
+
+    try {
+        const clone = { ...index };
+        delete clone.signature;
+
+        const data = Buffer.from(JSON.stringify(clone));
+        const sig = Buffer.from(value, "base64");
+        const key = Buffer.from(publicKey, "base64");
+
+        return crypto.verify(null, data, key, sig);
+    } catch (err) {
+        verbose(`Signature verification failed: ${err.message}`);
+        return false;
+    }
+}
+
+function fetchRegistry(url) {
+    const name = url.replace(/[^a-z0-9]/gi, "_").toLowerCase();
+    fs.mkdirSync(REGISTRY_CACHE, { recursive: true });
+
+    if (OFFLINE) {
+        const cached = registryCachePath(name);
+        if (fs.existsSync(cached)) {
+            verbose(`Using cached registry: ${url}`);
+            return JSON.parse(fs.readFileSync(cached, "utf-8"));
+        }
+        fatal("Offline mode: no cached registry available");
+    }
+
+    try {
+        verbose(`Fetching registry: ${url}`);
+        const json = execSync(`curl -fsSL "${url}"`, {
+            encoding: "utf-8",
+            timeout: 30000,
+        });
+        const index = JSON.parse(json);
+
+        if (!verifyRegistrySignature(index)) {
+            warn("Registry signature verification failed");
+            if (STRICT) fatal("Invalid registry signature (strict mode)");
+        }
+
+        fs.writeFileSync(registryCachePath(name), JSON.stringify(index, null, 2));
+        return index;
+    } catch (err) {
+        verbose(`Failed to fetch registry: ${err.message}`);
+        const cached = registryCachePath(name);
+        if (fs.existsSync(cached)) {
+            warn("Using cached registry (fetch failed)");
+            return JSON.parse(fs.readFileSync(cached, "utf-8"));
+        }
+        fatal("Failed to fetch registry and no cache available");
+    }
+}
+
+function loadAllRegistries() {
+    const regs = loadRegistries();
+    const result = [];
+
+    for (const url of regs) {
+        try {
+            const index = fetchRegistry(url);
+            result.push({ url, ...index });
+        } catch (err) {
+            warn(`Failed to load registry: ${url}`);
+        }
+    }
+    return result;
+}
+
+/* ===================== BACKUP HELPERS ===================== */
+
+function createBackup(skillDir, skillName) {
+    if (DRY) return null;
+
+    const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+    const backupPath = path.join(BACKUP_DIR, `${skillName}_${timestamp}`);
+
+    fs.mkdirSync(BACKUP_DIR, { recursive: true });
+    fs.cpSync(skillDir, backupPath, { recursive: true });
+
+    verbose(`Created backup: ${backupPath}`);
+    return backupPath;
+}
+
+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 backupPath = path.join(BACKUP_DIR, name);
+        const stat = fs.statSync(backupPath);
+
+        backups.push({
+            name,
+            path: backupPath,
+            createdAt: stat.mtime,
+            size: getDirSize(backupPath),
+        });
+    }
+
+    return backups.sort((a, b) => b.createdAt - a.createdAt);
+}
+
+/* ===================== PUBLISH HELPER ===================== */
+
+function publishSkill(skillDir, privateKeyPath) {
+    if (!fs.existsSync(skillDir)) fatal("Skill directory not found");
+
+    const skillName = path.basename(skillDir);
+    const checksum = merkleHash(skillDir);
+
+    const metaFile = path.join(skillDir, ".skill-source.json");
+    const skillMd = path.join(skillDir, "SKILL.md");
+
+    if (!fs.existsSync(skillMd)) fatal("SKILL.md missing");
+
+    // Parse SKILL.md frontmatter
+    let skillMeta = {};
+    try {
+        const content = fs.readFileSync(skillMd, "utf-8");
+        const match = content.match(/^---\n([\s\S]*?)\n---/);
+        if (match) {
+            const yaml = match[1];
+            for (const line of yaml.split("\n")) {
+                const [key, ...valueParts] = line.split(":");
+                if (key && valueParts.length) {
+                    skillMeta[key.trim()] = valueParts.join(":").trim();
+                }
+            }
+        }
+    } catch (err) {
+        verbose(`Failed to parse SKILL.md frontmatter: ${err.message}`);
+    }
+
+    const meta = fs.existsSync(metaFile)
+        ? JSON.parse(fs.readFileSync(metaFile, "utf-8"))
+        : {};
+
+    const manifest = {
+        skill: skillName,
+        repo: meta.repo || "local",
+        version: meta.ref || skillMeta.version || "1.0.0",
+        ref: meta.ref || null,
+        checksum: `sha256:${checksum}`,
+        publisher: meta.publisher || skillMeta.author || os.userInfo().username,
+        engines: meta.engines || [],
+        tags: meta.tags || skillMeta.tags?.split(",").map((t) => t.trim()) || [],
+        description: meta.description || skillMeta.description || "",
+        createdAt: new Date().toISOString(),
+    };
+
+    const data = Buffer.from(JSON.stringify(manifest));
+    const privateKey = fs.readFileSync(privateKeyPath);
+
+    const signature = crypto.sign(null, data, privateKey);
+
+    const output = {
+        manifest,
+        signature: {
+            algorithm: "ed25519",
+            keyId: `${manifest.publisher}-skill-v1`,
+            value: signature.toString("base64"),
+        },
+    };
+
+    const outFile = `${skillName}.publish.json`;
+
+    if (DRY) {
+        info(`Would create: ${outFile}`);
+        outputJSON(output);
+        return;
+    }
+
+    fs.writeFileSync(outFile, JSON.stringify(output, null, 2));
+    success(`Skill manifest generated: ${outFile}`);
+    outputJSON(output);
+}
+
+/* ===================== INSTALL HELPER ===================== */
+
+function resolveSkillSpec(spec) {
+    if (spec.includes("/")) return null;
+
+    const registries = loadAllRegistries();
+    for (const r of registries) {
+        if (r.skills?.[spec]) {
+            const s = r.skills[spec];
+            const v = s.latest;
+            return {
+                repo: s.repo,
+                skill: spec,
+                ref: s.versions[v].ref,
+                checksum: s.versions[v].checksum,
+                registry: r.url,
+            };
+        }
+    }
+    return null;
+}
+
+function parseSkillSpec(spec) {
+    const [repoPart, skillPart] = spec.split("#");
+    const [org, repo] = repoPart.split("/");
+    const [skill, ref] = (skillPart || "").split("@");
+    return { org, repo, skill, ref };
+}
+
+/* ===================== COMMANDS ===================== */
+
+function runInit() {
+    const targetDir = GLOBAL ? GLOBAL_DIR : WORKSPACE;
+
+    if (fs.existsSync(targetDir)) {
+        info(`Skills directory already exists: ${targetDir}`);
+        return;
+    }
+
+    if (DRY) {
+        info(`Would create: ${targetDir}`);
+        return;
+    }
+
+    fs.mkdirSync(targetDir, { recursive: true });
+    success(`Initialized skills directory: ${targetDir}`);
+
+    // Create .gitignore if in workspace
+    if (!GLOBAL) {
+        const gitignore = path.join(cwd, ".agent", ".gitignore");
+        if (!fs.existsSync(gitignore)) {
+            fs.writeFileSync(gitignore, "# Skill caches\nskills/*/.skill-source.json\n");
+            verbose("Created .gitignore");
+        }
+    }
+}
+
+function runList() {
+    const skills = getInstalledSkills();
+
+    if (skills.length === 0) {
+        info("No skills installed");
+        outputJSON({ skills: [] });
+        return;
+    }
+
+    if (JSON_OUTPUT) {
+        outputJSON({ skills });
+        return;
+    }
+
+    log(`\n${icons.package} ${colors.bold}Installed Skills${colors.reset}\n`);
+    log(`${colors.dim}Location: ${resolveScope()}${colors.reset}\n`);
+
+    for (const skill of skills) {
+        const status = skill.hasSkillMd
+            ? `${colors.green}${icons.check}${colors.reset}`
+            : `${colors.yellow}${icons.warning}${colors.reset}`;
+
+        // Authority badge
+        let authorityBadge = "";
+        if (skill.authority === "supreme") {
+            authorityBadge = ` ${colors.magenta}[SUPREME]${colors.reset}`;
+        } else if (skill.authority === "constitutional") {
+            authorityBadge = ` ${colors.cyan}[CONST]${colors.reset}`;
+        }
+
+        log(
+            `  ${status} ${colors.bold}${skill.name}${colors.reset}` +
+            `${authorityBadge} ` +
+            `${colors.dim}v${skill.version} (${formatBytes(skill.size)})${colors.reset}`
+        );
+
+        // Show description if available
+        if (skill.description && VERBOSE) {
+            const desc = skill.description.length > 80
+                ? skill.description.substring(0, 77) + "..."
+                : skill.description;
+            log(`     ${colors.dim}${desc}${colors.reset}`);
+        }
+
+        // Show Progressive Disclosure structure
+        if (VERBOSE && skill.structure) {
+            const features = [];
+            if (skill.structure.hasResources) features.push("resources");
+            if (skill.structure.hasExamples) features.push("examples");
+            if (skill.structure.hasScripts) features.push("scripts");
+            if (skill.structure.hasConstitution) features.push("constitution");
+            if (skill.structure.hasDoctrines) features.push("doctrines");
+            if (skill.structure.hasEnforcement) features.push("enforcement");
+
+            if (features.length > 0) {
+                log(`     ${colors.cyan}Structure: ${features.join(", ")}${colors.reset}`);
+            }
+        }
+
+        // Show tags
+        if (skill.tags && skill.tags.length > 0 && VERBOSE) {
+            log(`     ${colors.yellow}Tags: ${skill.tags.join(", ")}${colors.reset}`);
+        }
+
+        if (VERBOSE) {
+            log(`     ${colors.dim}Repo: ${skill.repo || "local"}${colors.reset}`);
+            log(`     ${colors.dim}Author: ${skill.author || "unknown"}${colors.reset}`);
+            log(`     ${colors.dim}Installed: ${formatDate(skill.installedAt)}${colors.reset}`);
+        }
+    }
+
+    log(`\n${colors.dim}Total: ${skills.length} skill(s)${colors.reset}\n`);
+}
+
+
+
+function runLock() {
+    if (!fs.existsSync(WORKSPACE)) fatal("No .agent/skills directory");
+
+    const skills = {};
+    for (const name of fs.readdirSync(WORKSPACE)) {
+        const dir = path.join(WORKSPACE, name);
+        if (!fs.statSync(dir).isDirectory()) continue;
+
+        const metaFile = path.join(dir, ".skill-source.json");
+        if (!fs.existsSync(metaFile)) continue;
+
+        const meta = JSON.parse(fs.readFileSync(metaFile, "utf-8"));
+        skills[name] = {
+            repo: meta.repo,
+            skill: meta.skill,
+            ref: meta.ref,
+            checksum: `sha256:${meta.checksum}`,
+            publisher: meta.publisher || null,
+        };
+    }
+
+    const lock = {
+        lockVersion: 1,
+        generatedAt: new Date().toISOString(),
+        generator: `@dataguruin/add-skill@${pkg.version}`,
+        skills,
+    };
+
+    if (DRY) {
+        info("Would generate skill-lock.json");
+        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");
+    outputJSON(lock);
+}
+
+function runVerify() {
+    const scope = resolveScope();
+    let issues = 0;
+    const results = [];
+
+    if (!fs.existsSync(scope)) {
+        info("No skills directory found");
+        return;
+    }
+
+    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");
+        if (!fs.existsSync(metaFile)) {
+            log(`${icons.cross} ${colors.red}${name}: missing metadata${colors.reset}`);
+            results.push({ name, status: "missing_metadata" });
+            issues++;
+            continue;
+        }
+
+        const meta = JSON.parse(fs.readFileSync(metaFile, "utf-8"));
+        const actual = merkleHash(dir);
+
+        if (actual !== meta.checksum) {
+            log(`${icons.cross} ${colors.red}${name}: checksum mismatch${colors.reset}`);
+            results.push({ name, status: "checksum_mismatch", expected: meta.checksum, actual });
+            issues++;
+        } else {
+            log(`${icons.check} ${colors.green}${name}${colors.reset}`);
+            results.push({ name, status: "ok" });
+        }
+    }
+
+    outputJSON({ verified: results.length, issues, results });
+
+    if (issues && STRICT) process.exit(1);
+}
+
+function runDoctor() {
+    const scope = resolveScope();
+    let errors = 0;
+    let warnings = 0;
+    const results = [];
+
+    if (!fs.existsSync(scope)) {
+        info("No skills directory found");
+        return;
+    }
+
+    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;
+
+        const result = { name, issues: [] };
+
+        if (!fs.existsSync(path.join(dir, "SKILL.md"))) {
+            log(`${icons.cross} ${colors.red}${name}: missing SKILL.md${colors.reset}`);
+            result.issues.push("missing_skill_md");
+            errors++;
+            results.push(result);
+            continue;
+        }
+
+        const metaFile = path.join(dir, ".skill-source.json");
+        if (!fs.existsSync(metaFile)) {
+            log(`${icons.cross} ${colors.red}${name}: missing metadata${colors.reset}`);
+            result.issues.push("missing_metadata");
+            errors++;
+            results.push(result);
+            continue;
+        }
+
+        const meta = JSON.parse(fs.readFileSync(metaFile, "utf-8"));
+        const actual = merkleHash(dir);
+
+        if (actual !== meta.checksum) {
+            if (FIX && !DRY) {
+                meta.checksum = actual;
+                fs.writeFileSync(metaFile, JSON.stringify(meta, null, 2));
+                warn(`${name}: checksum fixed`);
+                result.issues.push("checksum_fixed");
+            } else {
+                log(`${STRICT ? icons.cross : icons.warning} ${STRICT ? colors.red : colors.yellow}${name}: checksum drift${colors.reset}`);
+                result.issues.push("checksum_drift");
+                STRICT ? errors++ : warnings++;
+            }
+        }
+
+        if (lock && !lock.skills[name]) {
+            log(`${STRICT ? icons.cross : icons.warning} ${STRICT ? colors.red : colors.yellow}${name}: not in skill-lock.json${colors.reset}`);
+            result.issues.push("not_in_lock");
+            STRICT ? errors++ : warnings++;
+        }
+
+        if (result.issues.length === 0) {
+            log(`${icons.check} ${colors.green}${name}${colors.reset}`);
+        }
+
+        results.push(result);
+    }
+
+    outputJSON({ errors, warnings, results });
+
+    if (STRICT && errors) process.exit(1);
+}
+
+function runUpgradeAll() {
+    const scope = resolveScope();
+    if (!fs.existsSync(scope)) {
+        info("No skills directory found");
+        return;
+    }
+
+    const skills = getInstalledSkills().filter((s) => s.repo && s.repo !== "local");
+
+    if (skills.length === 0) {
+        info("No upgradable skills found");
+        return;
+    }
+
+    log(`\n${icons.refresh} Upgrading ${skills.length} skill(s)...\n`);
+
+    for (const skill of skills) {
+        const spinner = spin(`Upgrading ${skill.name}`);
+
+        try {
+            if (!DRY) {
+                createBackup(skill.path, skill.name);
+                fs.rmSync(skill.path, { recursive: true, force: true });
+            }
+
+            const spec = `${skill.repo}#${skill.skill}${skill.ref ? "@" + skill.ref : ""}`;
+
+            if (DRY) {
+                spinner.succeed(`Would upgrade: ${skill.name}`);
+            } else {
+                execSync(`node "${process.argv[1]}" install "${spec}"`, { stdio: "pipe" });
+                spinner.succeed(`Upgraded: ${skill.name}`);
+            }
+        } catch (err) {
+            spinner.fail(`Failed: ${skill.name}`);
+            verbose(err.message);
+        }
+    }
+
+    success("Upgrade complete");
+}
+
+async function runUninstall(skillName) {
+    if (!skillName) fatal("Missing skill name");
+
+    const scope = resolveScope();
+    const targetDir = path.join(scope, skillName);
+
+    if (!fs.existsSync(targetDir)) {
+        fatal(`Skill not found: ${skillName}`);
+    }
+
+    const confirmed = await confirm(
+        `${icons.trash} Remove skill "${skillName}"?`
+    );
+
+    if (!confirmed) {
+        info("Cancelled");
+        return;
+    }
+
+    if (DRY) {
+        info(`Would remove: ${targetDir}`);
+        return;
+    }
+
+    createBackup(targetDir, skillName);
+    fs.rmSync(targetDir, { recursive: true, force: true });
+
+    success(`Removed: ${skillName}`);
+}
+
+async function runUpdate(skillName) {
+    if (!skillName) fatal("Missing skill name");
+
+    const scope = resolveScope();
+    const 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");
+    }
+
+    const spinner = spin(`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 : ""}`;
+
+        if (DRY) {
+            spinner.succeed(`Would update: ${skillName}`);
+        } else {
+            execSync(`node "${process.argv[1]}" install "${spec}"`, { stdio: "pipe" });
+            spinner.succeed(`Updated: ${skillName}`);
+        }
+    } catch (err) {
+        spinner.fail(`Failed to update: ${skillName}`);
+        verbose(err.message);
+    }
+}
+
+function runInstall(spec) {
+    // Auto-init local workspace if not global and not already initialized
+    if (!GLOBAL && !fs.existsSync(path.join(cwd, ".agent"))) {
+        info("Initializing local workspace...");
+        runInit();
+    }
+
+    if (!spec) fatal("Missing skill reference");
+
+    const resolved = resolveSkillSpec(spec);
+    let org, repo, skill, ref;
+
+    if (resolved) {
+        const repoParts = resolved.repo.split("/");
+        org = repoParts[0];
+        repo = repoParts[1];
+        skill = resolved.skill;
+        ref = resolved.ref;
+        verbose(`Resolved from registry: ${resolved.registry}`);
+    } else {
+        const parsed = parseSkillSpec(spec);
+        org = parsed.org;
+        repo = parsed.repo;
+        skill = parsed.skill;
+        ref = parsed.ref;
+    }
+
+    if (!org || !repo || !skill) fatal("Invalid skill reference");
+
+    if (LOCKED) {
+        const lock = loadSkillLock();
+        if (!lock.skills[skill]) fatal(`Skill "${skill}" not in lock`);
+    }
+
+    const scope = resolveScope();
+    const targetDir = path.join(scope, skill);
+
+    if (fs.existsSync(targetDir) && !FORCE) {
+        fatal(`Skill already installed: ${skill} (use --force to reinstall)`);
+    }
+
+    if (fs.existsSync(targetDir)) {
+        createBackup(targetDir, skill);
+        fs.rmSync(targetDir, { recursive: true, force: true });
+    }
+
+    fs.mkdirSync(scope, { recursive: true });
+
+    const spinner = spin(`Installing ${skill} from ${org}/${repo}`);
+
+    try {
+        const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "add-skill-"));
+
+        if (DRY) {
+            spinner.succeed(`Would install: ${skill}${ref ? ` @ ${ref}` : ""}`);
+            return;
+        }
+
+        execSync(`git clone --depth=1 https://github.com/${org}/${repo}.git "${tmp}"`, {
+            stdio: "pipe",
+        });
+
+        if (ref) {
+            execSync(`git -C "${tmp}" checkout ${ref}`, { stdio: "pipe" });
+        }
+
+        const skillSrc = path.join(tmp, skill);
+        if (!fs.existsSync(skillSrc)) {
+            fs.rmSync(tmp, { recursive: true, force: true });
+            spinner.fail(`Skill not found in repo: ${skill}`);
+            fatal(`The skill "${skill}" was not found in ${org}/${repo}`);
+        }
+
+        fs.cpSync(skillSrc, targetDir, { recursive: true });
+
+        if (!fs.existsSync(path.join(targetDir, "SKILL.md"))) {
+            fs.rmSync(targetDir, { recursive: true, force: true });
+            fs.rmSync(tmp, { recursive: true, force: true });
+            spinner.fail("Invalid skill");
+            fatal("SKILL.md missing");
+        }
+
+        const checksum = merkleHash(targetDir);
+
+        fs.writeFileSync(
+            path.join(targetDir, ".skill-source.json"),
+            JSON.stringify(
+                {
+                    repo: `${org}/${repo}`,
+                    skill,
+                    ref: ref || null,
+                    checksum,
+                    installedAt: new Date().toISOString(),
+                },
+                null,
+                2
+            )
+        );
+
+        if (LOCKED) {
+            const lock = loadSkillLock();
+            const expected = lock.skills[skill].checksum;
+            if (expected !== `sha256:${checksum}`) {
+                fs.rmSync(targetDir, { recursive: true, force: true });
+                spinner.fail("Checksum mismatch");
+                fatal("Checksum mismatch in locked mode");
+            }
+        }
+
+        fs.rmSync(tmp, { recursive: true, force: true });
+
+        spinner.succeed(`Installed: ${skill}${ref ? ` @ ${ref}` : ""}`);
+        outputJSON({ installed: skill, checksum, ref });
+    } catch (err) {
+        spinner.fail(`Failed to install: ${skill}`);
+        fatal(err.message, err);
+    }
+}
+
+function runRegistry(sub, url) {
+    if (sub === "add") {
+        if (!url) fatal("Missing registry URL");
+
+        const regs = loadRegistries();
+        if (regs.includes(url)) {
+            info("Registry already added");
+            return;
+        }
+
+        const spinner = spin(`Adding registry`);
+        try {
+            regs.push(url);
+            saveRegistries(regs);
+            fetchRegistry(url);
+            spinner.succeed(`Registry added: ${url}`);
+        } catch (err) {
+            spinner.fail("Failed to add registry");
+            fatal(err.message);
+        }
+        return;
+    }
+
+    if (sub === "list") {
+        const regs = loadRegistries();
+        if (regs.length === 0) {
+            info("No registries configured");
+            outputJSON({ registries: [] });
+        } else {
+            log(`\n${icons.folder} ${colors.bold}Configured Registries${colors.reset}\n`);
+            regs.forEach((r) => log(`  ${icons.arrow} ${r}`));
+            log("");
+            outputJSON({ registries: regs });
+        }
+        return;
+    }
+
+    if (sub === "remove") {
+        if (!url) fatal("Missing registry URL");
+
+        const regs = loadRegistries();
+        const filtered = regs.filter((r) => r !== url);
+
+        if (filtered.length === regs.length) {
+            info("Registry not found");
+            return;
+        }
+
+        saveRegistries(filtered);
+        success(`Registry removed: ${url}`);
+        return;
+    }
+
+    if (sub === "refresh") {
+        const regs = loadRegistries();
+        const spinner = spin(`Refreshing ${regs.length} registry(ies)`);
+
+        for (const url of regs) {
+            try {
+                fetchRegistry(url);
+            } catch (err) {
+                warn(`Failed to refresh: ${url}`);
+            }
+        }
+
+        spinner.succeed("Registries refreshed");
+        return;
+    }
+
+    fatal(`Unknown registry subcommand: ${sub || "(none)"}`);
+}
+
+function runSearch(query) {
+    if (!query) fatal("Missing search query");
+
+    const registries = loadAllRegistries();
+    const results = [];
+
+    for (const r of registries) {
+        for (const [name, meta] of Object.entries(r.skills || {})) {
+            const matches =
+                name.toLowerCase().includes(query.toLowerCase()) ||
+                meta.description?.toLowerCase().includes(query.toLowerCase()) ||
+                meta.tags?.some((t) => t.toLowerCase().includes(query.toLowerCase()));
+
+            if (matches) {
+                results.push({
+                    name,
+                    publisher: meta.publisher,
+                    latest: meta.latest,
+                    description: meta.description,
+                    tags: meta.tags,
+                    registry: r.url,
+                });
+            }
+        }
+    }
+
+    if (results.length === 0) {
+        info("No skills found matching your query");
+        outputJSON({ results: [] });
+        return;
+    }
+
+    if (JSON_OUTPUT) {
+        outputJSON({ results });
+        return;
+    }
+
+    log(`\n${icons.package} ${colors.bold}Search Results${colors.reset}\n`);
+
+    for (const r of results) {
+        log(
+            `  ${colors.bold}${r.name}${colors.reset} ` +
+            `${colors.dim}v${r.latest}${colors.reset} ` +
+            `${colors.cyan}@${r.publisher}${colors.reset}`
+        );
+        if (r.description) {
+            log(`    ${colors.dim}${r.description}${colors.reset}`);
+        }
+        if (r.tags?.length) {
+            log(`    ${colors.yellow}${r.tags.map((t) => `#${t}`).join(" ")}${colors.reset}`);
+        }
+    }
+
+    log(`\n${colors.dim}Found ${results.length} skill(s)${colors.reset}\n`);
+}
+
+function runInfo(name) {
+    if (!name) fatal("Missing skill name");
+
+    // Check if installed locally first
+    const scope = resolveScope();
+    const localDir = path.join(scope, name);
+
+    if (fs.existsSync(localDir)) {
+        const metaFile = path.join(localDir, ".skill-source.json");
+        const skillMd = path.join(localDir, "SKILL.md");
+
+        log(`\n${icons.package} ${colors.bold}${name}${colors.reset} ${colors.green}(installed)${colors.reset}\n`);
+        log(`  ${colors.dim}Path: ${localDir}${colors.reset}`);
+
+        if (fs.existsSync(metaFile)) {
+            const meta = JSON.parse(fs.readFileSync(metaFile, "utf-8"));
+            log(`  ${colors.dim}Repo: ${meta.repo || "local"}${colors.reset}`);
+            log(`  ${colors.dim}Ref: ${meta.ref || "N/A"}${colors.reset}`);
+            log(`  ${colors.dim}Installed: ${formatDate(meta.installedAt)}${colors.reset}`);
+            log(`  ${colors.dim}Checksum: ${meta.checksum?.substring(0, 12)}...${colors.reset}`);
+        }
+
+        if (fs.existsSync(skillMd)) {
+            log(`\n${colors.dim}--- SKILL.md ---${colors.reset}\n`);
+            const content = fs.readFileSync(skillMd, "utf-8");
+            const lines = content.split("\n").slice(0, 20);
+            log(lines.join("\n"));
+            if (content.split("\n").length > 20) {
+                log(`\n${colors.dim}... (truncated)${colors.reset}`);
+            }
+        }
+
+        log("");
+        return;
+    }
+
+    // Check registries
+    const registries = loadAllRegistries();
+
+    for (const r of registries) {
+        if (r.skills?.[name]) {
+            const s = r.skills[name];
+
+            if (JSON_OUTPUT) {
+                outputJSON({ name, ...s, registry: r.url });
+                return;
+            }
+
+            log(`\n${icons.package} ${colors.bold}${name}${colors.reset}\n`);
+            log(`  Publisher: ${colors.cyan}@${s.publisher}${colors.reset}`);
+            log(`  Repo: ${s.repo}`);
+            log(`  Latest: ${colors.green}${s.latest}${colors.reset}`);
+            if (s.description) log(`  Description: ${s.description}`);
+            if (s.tags?.length) log(`  Tags: ${s.tags.map((t) => `#${t}`).join(" ")}`);
+            log(`\n  Versions:`);
+            Object.keys(s.versions).forEach((v) => log(`    - ${v}`));
+            log("");
+            return;
+        }
+    }
+
+    fatal("Skill not found");
+}
+
+function runPublish() {
+    const skillDir = params[0];
+    if (!skillDir) fatal("Missing skill directory");
+
+    const keyIndex = args.indexOf("--key");
+    const keyPath = keyIndex !== -1 ? args[keyIndex + 1] : null;
+    if (!keyPath) fatal("Missing --key <private-key>");
+
+    publishSkill(path.resolve(skillDir), keyPath);
+}
+
+function runCache(sub) {
+    if (sub === "clear") {
+        if (DRY) {
+            info(`Would clear cache: ${CACHE_ROOT}`);
+            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 {
+            info("Cache already empty");
+        }
+        return;
+    }
+
+    if (sub === "info" || !sub) {
+        if (!fs.existsSync(CACHE_ROOT)) {
+            info("Cache is empty");
+            return;
+        }
+
+        const registrySize = fs.existsSync(REGISTRY_CACHE) ? getDirSize(REGISTRY_CACHE) : 0;
+        const backupSize = fs.existsSync(BACKUP_DIR) ? getDirSize(BACKUP_DIR) : 0;
+        const totalSize = getDirSize(CACHE_ROOT);
+
+        log(`\n${icons.folder} ${colors.bold}Cache Info${colors.reset}\n`);
+        log(`  Location: ${CACHE_ROOT}`);
+        log(`  Registries: ${formatBytes(registrySize)}`);
+        log(`  Backups: ${formatBytes(backupSize)}`);
+        log(`  Total: ${formatBytes(totalSize)}`);
+
+        const backups = listBackups();
+        if (backups.length) {
+            log(`\n  Recent backups:`);
+            backups.slice(0, 5).forEach((b) => {
+                log(`    - ${b.name} (${formatBytes(b.size)})`);
+            });
+        }
+
+        log("");
+        return;
+    }
+
+    if (sub === "backups") {
+        const backups = listBackups();
+        if (backups.length === 0) {
+            info("No backups found");
+            return;
+        }
+
+        log(`\n${icons.folder} ${colors.bold}Backups${colors.reset}\n`);
+        backups.forEach((b) => {
+            log(`  ${b.name} (${formatBytes(b.size)}) - ${formatDate(b.createdAt.toISOString())}`);
+        });
+        log("");
+        return;
+    }
+
+    fatal(`Unknown cache subcommand: ${sub}`);
+}
+
+/**
+ * Validate skill against Antigravity Skills specification
+ */
+function runValidate(skillName) {
+    const scope = resolveScope();
+    let skillsToValidate = [];
+
+    if (skillName) {
+        const skillDir = path.join(scope, skillName);
+        if (!fs.existsSync(skillDir)) {
+            fatal(`Skill not found: ${skillName}`);
+        }
+        skillsToValidate = [{ name: skillName, path: skillDir }];
+    } else {
+        skillsToValidate = getInstalledSkills();
+    }
+
+    if (skillsToValidate.length === 0) {
+        info("No skills to validate");
+        return;
+    }
+
+    log(`\n${colors.bold}🔍 Antigravity Skills Validation${colors.reset}\n`);
+
+    let totalErrors = 0;
+    let totalWarnings = 0;
+    const results = [];
+
+    for (const skill of skillsToValidate) {
+        const skillDir = skill.path;
+        const errors = [];
+        const warnings = [];
+        const suggestions = [];
+
+        // Check 1: SKILL.md exists
+        const skillMdPath = path.join(skillDir, "SKILL.md");
+        if (!fs.existsSync(skillMdPath)) {
+            errors.push("Missing SKILL.md (required)");
+        } else {
+            // Check 2: Valid YAML frontmatter
+            const meta = parseSkillMdFrontmatter(skillMdPath);
+
+            if (!meta.name) {
+                warnings.push("SKILL.md: Missing 'name' in frontmatter");
+            }
+
+            // Check 3: Description field (critical for semantic routing)
+            if (!meta.description) {
+                errors.push("SKILL.md: Missing 'description' field (required for semantic routing)");
+            } else if (meta.description.length < 50) {
+                warnings.push("SKILL.md: Description is too short (recommend 50+ chars for better routing)");
+            }
+
+            // Check 4: Tags
+            if (!meta.tags || meta.tags.length === 0) {
+                suggestions.push("Consider adding 'tags' for better discoverability");
+            }
+
+            // Check 5: Author
+            if (!meta.author) {
+                suggestions.push("Consider adding 'author' field");
+            }
+        }
+
+        // Check 6: .skill-source.json
+        const metaPath = path.join(skillDir, ".skill-source.json");
+        if (fs.existsSync(metaPath)) {
+            try {
+                const meta = JSON.parse(fs.readFileSync(metaPath, "utf-8"));
+                if (!meta.repo) warnings.push(".skill-source.json: Missing 'repo' field");
+                if (!meta.ref) warnings.push(".skill-source.json: Missing 'ref' (version) field");
+                if (!meta.publisher) suggestions.push(".skill-source.json: Consider adding 'publisher'");
+            } catch (err) {
+                errors.push(".skill-source.json: Invalid JSON");
+            }
+        }
+
+        // Check 7: Progressive Disclosure structure
+        const structure = skill.structure || detectSkillStructure(skillDir);
+
+        // Resources, examples, scripts are recommended
+        if (!structure.hasResources && !structure.hasExamples && !structure.hasScripts) {
+            suggestions.push("Consider adding resources/, examples/, or scripts/ for Progressive Disclosure");
+        }
+
+        // Print results for this skill
+        const hasIssues = errors.length > 0 || warnings.length > 0;
+        const status = errors.length > 0
+            ? `${colors.red}❌ FAIL${colors.reset}`
+            : warnings.length > 0
+                ? `${colors.yellow}⚠️  WARN${colors.reset}`
+                : `${colors.green}✅ PASS${colors.reset}`;
+
+        log(`${status} ${colors.bold}${skill.name}${colors.reset}`);
+
+        if (VERBOSE || hasIssues) {
+            errors.forEach(e => log(`  ${colors.red}ERROR: ${e}${colors.reset}`));
+            warnings.forEach(w => log(`  ${colors.yellow}WARN: ${w}${colors.reset}`));
+            if (VERBOSE) {
+                suggestions.forEach(s => log(`  ${colors.dim}SUGGEST: ${s}${colors.reset}`));
+            }
+        }
+
+        totalErrors += errors.length;
+        totalWarnings += warnings.length;
+
+        results.push({
+            name: skill.name,
+            valid: errors.length === 0,
+            errors,
+            warnings,
+            suggestions,
+        });
+    }
+
+    log(`\n${colors.dim}─────────────────────────────────────────${colors.reset}`);
+    log(`Total: ${skillsToValidate.length} skill(s), ${totalErrors} error(s), ${totalWarnings} warning(s)\n`);
+
+    outputJSON({ results, totalErrors, totalWarnings });
+
+    if (STRICT && totalErrors > 0) {
+        process.exit(1);
+    }
+}
+
+/**
+ * Analyze skill metadata and structure in detail
+ */
+function runAnalyze(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}`);
+    }
+
+    const skillMdPath = path.join(skillDir, "SKILL.md");
+    const metaPath = path.join(skillDir, ".skill-source.json");
+
+    log(`\n${colors.bold}📊 Skill Analysis: ${skillName}${colors.reset}\n`);
+    log(`${colors.dim}Path: ${skillDir}${colors.reset}\n`);
+
+    // Parse SKILL.md
+    if (fs.existsSync(skillMdPath)) {
+        const meta = parseSkillMdFrontmatter(skillMdPath);
+
+        log(`${colors.cyan}SKILL.md Frontmatter:${colors.reset}`);
+        log(`  Name: ${meta.name || colors.dim + "(not set)" + colors.reset}`);
+        log(`  Version: ${meta.version || colors.dim + "(not set)" + colors.reset}`);
+        log(`  Type: ${meta.type || "standard"}`);
+        log(`  Authority: ${meta.authority || "normal"}`);
+        log(`  Author: ${meta.author || colors.dim + "(not set)" + colors.reset}`);
+
+        if (meta.description) {
+            log(`  Description: ${meta.description.substring(0, 100)}${meta.description.length > 100 ? "..." : ""}`);
+        } else {
+            log(`  Description: ${colors.red}(MISSING - required for semantic routing)${colors.reset}`);
+        }
+
+        if (meta.tags && meta.tags.length > 0) {
+            log(`  Tags: ${meta.tags.join(", ")}`);
+        }
+
+        if (meta.parent) {
+            log(`  Parent: ${meta.parent}`);
+        }
+
+        log("");
+    } else {
+        log(`${colors.red}SKILL.md: NOT FOUND${colors.reset}\n`);
+    }
+
+    // Parse .skill-source.json
+    if (fs.existsSync(metaPath)) {
+        try {
+            const meta = JSON.parse(fs.readFileSync(metaPath, "utf-8"));
+            log(`${colors.cyan}Source Metadata:${colors.reset}`);
+            log(`  Repo: ${meta.repo || "local"}`);
+            log(`  Ref: ${meta.ref || "N/A"}`);
+            log(`  Publisher: ${meta.publisher || "unknown"}`);
+            log(`  Installed: ${formatDate(meta.installedAt)}`);
+            if (meta.checksum) {
+                log(`  Checksum: ${meta.checksum.substring(0, 16)}...`);
+            }
+            log("");
+        } catch (err) {
+            log(`${colors.red}.skill-source.json: Invalid${colors.reset}\n`);
+        }
+    }
+
+    // Structure analysis
+    const structure = detectSkillStructure(skillDir);
+
+    log(`${colors.cyan}Progressive Disclosure Structure:${colors.reset}`);
+
+    const structureItems = [
+        { name: "resources/", has: structure.hasResources, desc: "On-demand heavy content" },
+        { name: "examples/", has: structure.hasExamples, desc: "Before/after code examples" },
+        { name: "scripts/", has: structure.hasScripts, desc: "Validation/automation scripts" },
+        { name: "constitution/", has: structure.hasConstitution, desc: "Supreme authority docs" },
+        { name: "doctrines/", has: structure.hasDoctrines, desc: "Domain-specific laws" },
+        { name: "enforcement/", has: structure.hasEnforcement, desc: "Checklists & protocols" },
+        { name: "proposals/", has: structure.hasProposals, desc: "Evolution & Change Control" },
+        { name: "assets/", has: structure.hasAssets, desc: "Static assets" },
+    ];
+
+    for (const item of structureItems) {
+        const icon = item.has ? colors.green + "✓" + colors.reset : colors.dim + "○" + colors.reset;
+        const name = item.has ? colors.bold + item.name + colors.reset : colors.dim + item.name + colors.reset;
+        log(`  ${icon} ${name} ${colors.dim}${item.desc}${colors.reset}`);
+    }
+
+    log("");
+
+    // Files list
+    log(`${colors.cyan}Top-level Files:${colors.reset}`);
+    structure.files.forEach(f => {
+        log(`  ${colors.dim}•${colors.reset} ${f}`);
+    });
+
+    log("");
+
+    // Directories list  
+    if (structure.directories.length > 0) {
+        log(`${colors.cyan}Directories:${colors.reset}`);
+        structure.directories.forEach(d => {
+            const subPath = path.join(skillDir, d);
+            try {
+                const subItems = fs.readdirSync(subPath);
+                log(`  ${colors.dim}📁${colors.reset} ${d}/ ${colors.dim}(${subItems.length} items)${colors.reset}`);
+            } catch {
+                log(`  ${colors.dim}📁${colors.reset} ${d}/`);
+            }
+        });
+        log("");
+    }
+
+    // Size info
+    const size = getDirSize(skillDir);
+    log(`${colors.cyan}Size:${colors.reset} ${formatBytes(size)}\n`);
+
+    // Antigravity compatibility score
+    let score = 0;
+    if (fs.existsSync(skillMdPath)) score += 20;
+    const meta = parseSkillMdFrontmatter(skillMdPath);
+    if (meta.description) score += 25;
+    if (meta.tags && meta.tags.length > 0) score += 10;
+    if (meta.author) score += 5;
+    if (structure.hasResources || structure.hasExamples || structure.hasScripts) score += 20;
+    if (fs.existsSync(metaPath)) score += 10;
+    if (structure.hasConstitution || structure.hasDoctrines) score += 10;
+
+    const scoreColor = score >= 80 ? colors.green : score >= 50 ? colors.yellow : colors.red;
+    log(`${colors.cyan}Antigravity Compatibility Score:${colors.reset} ${scoreColor}${score}/100${colors.reset}`);
+
+    if (score < 50) {
+        log(`${colors.dim}Tip: Add 'description' to SKILL.md and consider Progressive Disclosure structure${colors.reset}`);
+    } else if (score < 80) {
+        log(`${colors.dim}Tip: Add examples/ or scripts/ to improve Progressive Disclosure${colors.reset}`);
+    } else {
+        log(`${colors.green}✨ Excellent! This skill follows Antigravity best practices${colors.reset}`);
+    }
+
+    log("");
+}
+
+
+function showHelp() {
+    console.log(`
+${colors.bold}add-skill${colors.reset} v${pkg.version} - Enterprise Agent Skill Manager
+
+
+${colors.bold}USAGE${colors.reset}
+  add-skill <command> [options]
+
+${colors.bold}COMMANDS${colors.reset}
+  ${colors.cyan}install${colors.reset} <org/repo#skill@ref>   Install a skill from GitHub
+  ${colors.cyan}install${colors.reset} <skill-name>           Install a skill from registry
+  ${colors.cyan}uninstall${colors.reset} <skill-name>         Remove an installed skill
+  ${colors.cyan}update${colors.reset} <skill-name>            Update a single skill
+  ${colors.cyan}upgrade-all${colors.reset}                    Upgrade all installed skills
+  ${colors.cyan}list${colors.reset}                           Show installed skills
+  ${colors.cyan}verify${colors.reset}                         Verify skill checksums
+  ${colors.cyan}doctor${colors.reset}                         Check skill health
+  ${colors.cyan}lock${colors.reset}                           Generate skill-lock.json
+  ${colors.cyan}init${colors.reset}                           Initialize skills directory
+
+${colors.bold}ANTIGRAVITY SKILLS${colors.reset}
+  ${colors.cyan}validate${colors.reset} [skill-name]          Validate against Antigravity spec
+  ${colors.cyan}analyze${colors.reset} <skill-name>           Analyze skill metadata & structure
+
+${colors.bold}REGISTRY${colors.reset}
+  ${colors.cyan}registry add${colors.reset} <url>             Add a skill registry
+  ${colors.cyan}registry list${colors.reset}                  List configured registries
+  ${colors.cyan}registry remove${colors.reset} <url>          Remove a registry
+  ${colors.cyan}registry refresh${colors.reset}               Refresh registry cache
+  ${colors.cyan}search${colors.reset} <query>                 Search skills in registries
+  ${colors.cyan}info${colors.reset} <skill-name>              Show skill details
+
+${colors.bold}PUBLISHING${colors.reset}
+  ${colors.cyan}publish${colors.reset} <dir> --key <path>     Generate signed manifest
+
+${colors.bold}CACHE${colors.reset}
+  ${colors.cyan}cache info${colors.reset}                     Show cache statistics
+  ${colors.cyan}cache clear${colors.reset}                    Clear all caches
+  ${colors.cyan}cache backups${colors.reset}                  List skill backups
+
+${colors.bold}FLAGS${colors.reset}
+  ${colors.yellow}--global, -g${colors.reset}     Use global skills directory
+  ${colors.yellow}--force, -f${colors.reset}      Force operation (skip prompts)
+  ${colors.yellow}--locked${colors.reset}         Enforce skill-lock.json
+  ${colors.yellow}--strict${colors.reset}         Fail on any violation
+  ${colors.yellow}--fix${colors.reset}            Auto-fix safe issues
+  ${colors.yellow}--dry-run${colors.reset}        Preview without changes
+  ${colors.yellow}--verbose, -v${colors.reset}    Detailed output
+  ${colors.yellow}--json${colors.reset}           Output as JSON
+  ${colors.yellow}--offline${colors.reset}        Use cached registries only
+
+${colors.bold}EXAMPLES${colors.reset}
+  add-skill install dataguruin/skills#browser@v1.0.0
+  add-skill install browser --force
+  add-skill list --verbose
+  add-skill update browser
+  add-skill verify --strict
+  add-skill doctor --fix
+  add-skill registry add https://skills.example.com/index.json
+  add-skill search "automation" --json
+`);
+}
+
+/* ===================== MAIN ROUTER ===================== */
+
+async function main() {
+    try {
+        switch (command) {
+            case "init":
+                runInit();
+                break;
+
+            case "list":
+            case "ls":
+                runList();
+                break;
+
+            case "lock":
+                runLock();
+                break;
+
+            case "verify":
+                runVerify();
+                break;
+
+            case "doctor":
+                runDoctor();
+                break;
+
+            case "upgrade-all":
+                runUpgradeAll();
+                break;
+
+            case "uninstall":
+            case "remove":
+            case "rm":
+                await runUninstall(params[0]);
+                break;
+
+            case "update":
+                await runUpdate(params[0]);
+                break;
+
+            case "install":
+            case "add":
+            case "i":
+                runInstall(params[0]);
+                break;
+
+            case "registry":
+            case "reg":
+                runRegistry(params[0], params[1]);
+                break;
+
+            case "search":
+            case "s":
+                runSearch(params[0]);
+                break;
+
+            case "info":
+            case "show":
+                runInfo(params[0]);
+                break;
+
+            case "publish":
+                runPublish();
+                break;
+
+            case "validate":
+            case "check":
+                runValidate(params[0]);
+                break;
+
+            case "analyze":
+                runAnalyze(params[0]);
+                break;
+
+            case "cache":
+                runCache(params[0]);
+                break;
+
+
+            case "help":
+            case "--help":
+            case "-h":
+            case undefined:
+                showHelp();
+                break;
+
+            case "--version":
+            case "-V":
+                console.log(pkg.version);
+                break;
+
+            default:
+                // Smart Install: If command looks like org/repo, treat as install arg
+                if (command && command.includes("/")) {
+                    runInstall(command);
+                    break;
+                }
+
+                console.error(`${icons.error} Unknown command: ${command}`);
+                showHelp();
+                process.exit(1);
+        }
+    } catch (err) {
+        fatal(err.message, err);
+    }
+}
+
+main();