install-agent-skill 1.2.3

package/bin/lib/commands/doctor.js

@@ -0,0 +1,75 @@
+/**
+ * @fileoverview Doctor command - Health check
+ */
+
+import fs from "fs";
+import path from "path";
+import { resolveScope, merkleHash, loadSkillLock } from "../helpers.js";
+import { step, stepLine, S, c } from "../ui.js";
+import { STRICT, FIX, DRY, cwd } from "../config.js";
+
+/**
+ * Run health check on installed skills
+ */
+export async function run() {
+    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;
+
+        // Check SKILL.md
+        if (!fs.existsSync(path.join(dir, "SKILL.md"))) {
+            step(`${name}: ${c.red("missing SKILL.md")}`, S.cross, "red");
+            errors++;
+            continue;
+        }
+
+        // Check metadata
+        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"));
+        const actual = merkleHash(dir);
+
+        // Check checksum
+        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);
+}

package/bin/lib/commands/help.js

@@ -0,0 +1,42 @@
+/**
+ * @fileoverview Help command
+ */
+
+import { c } from "../ui.js";
+import { VERSION } from "../config.js";
+
+/**
+ * Show help
+ */
+export async function run() {
+    console.log(`
+  ${c.bold("add-skill")} ${c.dim("v" + 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
+    info <skill>        Show skill info
+
+  ${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
+`);
+}

package/bin/lib/commands/info.js

@@ -0,0 +1,38 @@
+/**
+ * @fileoverview Info command
+ */
+
+import fs from "fs";
+import path from "path";
+import { resolveScope, formatDate } from "../helpers.js";
+import { step, stepLine, S, c, fatal } from "../ui.js";
+
+/**
+ * Show skill info
+ * @param {string} name
+ */
+export async function run(name) {
+    if (!name) fatal("Missing skill name");
+
+    const scope = resolveScope();
+    const 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();
+}

package/bin/lib/commands/init.js

@@ -0,0 +1,39 @@
+/**
+ * @fileoverview Init command
+ */
+
+import fs from "fs";
+import { step, stepLine, S, success } from "../ui.js";
+import { GLOBAL, GLOBAL_DIR, WORKSPACE, DRY, cwd } from "../config.js";
+import path from "path";
+
+/**
+ * Initialize skills directory
+ */
+export async function run() {
+    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 });
+
+    // Create .gitignore if workspace
+    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}`);
+}

package/bin/lib/commands/install.js

@@ -0,0 +1,188 @@
+/**
+ * @fileoverview Install command - Interactive skill installation
+ */
+
+import fs from "fs";
+import path from "path";
+import os from "os";
+import { execSync } from "child_process";
+import prompts from "prompts";
+import ora from "ora";
+import boxen from "boxen";
+import { parseSkillSpec, merkleHash } from "../helpers.js";
+import { parseSkillMdFrontmatter } from "../skills.js";
+import { step, stepLine, S, c, fatal } from "../ui.js";
+import { WORKSPACE, GLOBAL_DIR } from "../config.js";
+
+/**
+ * Install skills from repository
+ * @param {string} spec - Skill spec (org/repo or org/repo#skill)
+ */
+export async function run(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();
+    step("Source: " + c.cyan(url), S.diamond);
+
+    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();
+        step(c.red("Failed to clone"), S.cross, "red");
+        fs.rmSync(tmp, { recursive: true, force: true });
+        return;
+    }
+
+    spinner.stop();
+    step("Repository cloned", S.check, "green");
+
+    // Find skills in repo
+    const skillsInRepo = [];
+    for (const e of fs.readdirSync(tmp)) {
+        const sp = path.join(tmp, e);
+        if (fs.statSync(sp).isDirectory() && fs.existsSync(path.join(sp, "SKILL.md"))) {
+            const m = parseSkillMdFrontmatter(path.join(sp, "SKILL.md"));
+            skillsInRepo.push({
+                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} skill${skillsInRepo.length > 1 ? "s" : ""}`, S.diamond);
+
+    let selectedSkills = [];
+
+    // If single skill specified via #skill_name, auto-select it
+    if (singleSkill) {
+        const found = skillsInRepo.find(s => s.value === singleSkill);
+        if (!found) {
+            stepLine();
+            step(c.red(`Skill '${singleSkill}' not found in repository`), S.cross, "red");
+            fs.rmSync(tmp, { recursive: true, force: true });
+            return;
+        }
+        selectedSkills = [singleSkill];
+        stepLine();
+        step(`Auto-selected: ${c.cyan(singleSkill)}`, S.check, "green");
+    } else {
+        // Show selection prompt for multiple skills
+        stepLine();
+        step("Select skills to install", S.diamond, "cyan");
+
+        // Display choices with custom formatting
+        const skillsR = await prompts({
+            type: "multiselect",
+            name: "skills",
+            message: "Select skills to install",
+            choices: skillsInRepo.map(s => ({
+                title: s.title,
+                value: s.value,
+                selected: true  // Pre-select all by default
+            })),
+            hint: "- Space to toggle. 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;
+        }
+
+        selectedSkills = skillsR.skills;
+    }
+
+    // Scope selection
+    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;
+
+    // Summary
+    stepLine();
+    step("Installation Summary", S.diamond);
+    stepLine();
+
+    let boxContent = "";
+    for (const sn of selectedSkills) 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();
+
+    // Confirmation
+    const confirm = await prompts({ type: "confirm", name: "value", message: "Proceed?", initial: true });
+    if (!confirm.value) {
+        console.log(`\n ${c.yellow("Cancelled.")}`);
+        fs.rmSync(tmp, { recursive: true, force: true });
+        return;
+    }
+
+    // Install
+    stepLine();
+    fs.mkdirSync(targetScope, { recursive: true });
+
+    for (const sn of selectedSkills) {
+        const src = path.join(tmp, sn);
+        const dest = path.join(targetScope, sn);
+
+        if (fs.existsSync(dest)) fs.rmSync(dest, { recursive: true, force: true });
+        fs.cpSync(src, dest, { recursive: true });
+
+        const hash = merkleHash(dest);
+        fs.writeFileSync(path.join(dest, ".skill-source.json"), JSON.stringify({
+            repo: `${org}/${repo}`,
+            skill: sn,
+            ref: ref || null,
+            checksum: hash,
+            installedAt: new Date().toISOString()
+        }, null, 2));
+
+        step(`Installed: ${c.bold(sn)}`, S.check, "green");
+    }
+
+    fs.rmSync(tmp, { recursive: true, force: true });
+
+    stepLine();
+    console.log(` ${c.cyan("Done!")}`);
+    console.log();
+}

package/bin/lib/commands/list.js

@@ -0,0 +1,43 @@
+/**
+ * @fileoverview List command
+ */
+
+import { getInstalledSkills } from "../skills.js";
+import { resolveScope, formatBytes } from "../helpers.js";
+import { step, stepLine, S, c, outputJSON } from "../ui.js";
+import { VERBOSE, JSON_OUTPUT } from "../config.js";
+
+/**
+ * List installed skills
+ */
+export async function run() {
+    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 }, true);
+        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();
+}

package/bin/lib/commands/lock.js

@@ -0,0 +1,57 @@
+/**
+ * @fileoverview Lock command - Generate skill-lock.json
+ */
+
+import fs from "fs";
+import path from "path";
+import { step, stepLine, success, fatal, outputJSON } from "../ui.js";
+import { WORKSPACE, DRY, cwd, VERSION } from "../config.js";
+
+/**
+ * Generate skill-lock.json
+ */
+export async function run() {
+    if (!fs.existsSync(WORKSPACE)) {
+        fatal("No .agent/skills directory");
+        return;
+    }
+
+    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: `@dataguruin/add-skill@${VERSION}`,
+        skills
+    };
+
+    if (DRY) {
+        step("Would generate skill-lock.json");
+        outputJSON(lock, true);
+        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();
+}

package/bin/lib/commands/uninstall.js

@@ -0,0 +1,48 @@
+/**
+ * @fileoverview Uninstall command
+ */
+
+import fs from "fs";
+import path from "path";
+import prompts from "prompts";
+import { resolveScope, createBackup } from "../helpers.js";
+import { step, stepLine, success, fatal, c } from "../ui.js";
+import { DRY } from "../config.js";
+
+/**
+ * Remove a skill
+ * @param {string} skillName
+ */
+export async function run(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}`);
+
+    stepLine();
+
+    const confirm = await prompts({
+        type: "confirm",
+        name: "value",
+        message: `Remove skill "${skillName}"?`,
+        initial: false
+    });
+
+    if (!confirm.value) {
+        step("Cancelled");
+        return;
+    }
+
+    if (DRY) {
+        step(`Would remove: ${targetDir}`);
+        return;
+    }
+
+    createBackup(targetDir, skillName);
+    fs.rmSync(targetDir, { recursive: true, force: true });
+
+    success(`Removed: ${skillName}`);
+    stepLine();
+}

package/bin/lib/commands/update.js

@@ -0,0 +1,58 @@
+/**
+ * @fileoverview Update command
+ */
+
+import fs from "fs";
+import path from "path";
+import ora from "ora";
+import { resolveScope, createBackup } from "../helpers.js";
+import { step, stepLine, S, c, fatal } from "../ui.js";
+import { DRY } from "../config.js";
+
+/**
+ * Update a skill
+ * @param {string} skillName
+ */
+export async function run(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");
+
+    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}`);
+        } else {
+            // Dynamically import install command
+            const { run: install } = await import("./install.js");
+            await install(spec);
+        }
+    } catch (err) {
+        spinner.stop();
+        step(`Failed: ${err.message}`, S.cross, "red");
+    }
+}

package/bin/lib/commands/validate.js

@@ -0,0 +1,69 @@
+/**
+ * @fileoverview Validate command - Antigravity spec validation
+ */
+
+import fs from "fs";
+import path from "path";
+import { getInstalledSkills, parseSkillMdFrontmatter } from "../skills.js";
+import { resolveScope } from "../helpers.js";
+import { step, stepLine, S, c, fatal } from "../ui.js";
+import { VERBOSE, STRICT } from "../config.js";
+
+/**
+ * Validate skills against Antigravity spec
+ * @param {string} [skillName] - Optional specific skill
+ */
+export async function run(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);
+}