install-agent-skill 1.0.0

package/bin/lib/commands/install.js

@@ -0,0 +1,297 @@
+/**
+ * @fileoverview Install command - Interactive skill installation
+ */
+
+import fs from "fs";
+import path from "path";
+import os from "os";
+import { exec } from "child_process";
+import util from "util";
+const execAsync = util.promisify(exec);
+import boxen from "boxen";
+import { parseSkillSpec, merkleHash } from "../helpers.js";
+import { parseSkillMdFrontmatter } from "../skills.js";
+import { step, activeStep, stepLine, S, c, fatal, spinner, multiselect, select, confirm, isCancel, cancel } from "../ui.js";
+import { WORKSPACE, GLOBAL_DIR } from "../config.js";
+import { installSkill } from "../installer.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));
+
+    const s = spinner();
+    s.start("Cloning repository");
+
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "add-skill-"));
+
+    try {
+        await execAsync(`git clone --depth=1 ${url} "${tmp}"`);
+        if (ref) await execAsync(`git -C "${tmp}" checkout ${ref}`);
+    } catch {
+        s.fail("Failed to clone");
+        fs.rmSync(tmp, { recursive: true, force: true });
+        return;
+    }
+
+    s.stop("Repository cloned");
+
+    // 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" : ""}`);
+
+    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)}`);
+    } else {
+        // Show selection prompt for multiple skills
+        stepLine();
+
+        // Active Step: Selection
+        // Note: activeStep already prints the icon. Clack prompts typically print their own message.
+        // But we want to enforce the tree style.
+        // Clack's multiselect prints: "? Message"
+        // We want: "◆ Select skills to install"
+        // We can print "activeStep" line, and then let clack print below?
+        // Or we use clack's message but Clack doesn't support custom icons well in the prompt line itself easily without patches.
+        // We will print the active step line manually, and set clack message to something minimal or empty if possible, or just repeat it but we want the "◆".
+        // Let's print activeStep("Select skills to install") and then run multiselect with a simpler message like " " or hidden?
+        // Clack behaves best with a message. Let's try printing the header and then the prompt.
+
+        activeStep("Select skills to install");
+
+        const skills = await multiselect({
+            message: c.dim("(Press <space> to select, <enter> to submit)"),
+            options: skillsInRepo.map(s => ({
+                label: s.title,
+                value: s.value
+            })),
+            initialValues: skillsInRepo.map(s => s.value), // Pre-select all
+            required: true
+        });
+
+        if (isCancel(skills)) {
+            cancel("Cancelled.");
+            fs.rmSync(tmp, { recursive: true, force: true });
+            return;
+        }
+
+        selectedSkills = skills;
+    }
+
+    // Ensure newline after prompt to fix tree alignment
+    stepLine();
+    step("Select skills to install");
+    console.log(`${c.gray(S.branch)}  ${c.dim(selectedSkills.join(", "))}`);
+
+    // Agent selection
+    stepLine();
+    step("Detected 5 agents"); // Passive info
+
+    let agents;
+    while (true) {
+        // Active Step
+        activeStep("Select agents to install skills to (Antigravity only)");
+
+        agents = await multiselect({
+            message: c.dim("(Press <space> to select, <enter> to submit)"),
+            options: [
+                { label: "Antigravity (.agent/skills)", value: "antigravity" },
+                { label: c.dim("Claude Code (coming soon)"), value: "claude" },
+                { label: c.dim("Codex (coming soon)"), value: "codex" },
+                { label: c.dim("Gemini CLI (coming soon)"), value: "gemini" },
+                { label: c.dim("Windsurf (coming soon)"), value: "windsurf" }
+            ],
+            initialValues: ["antigravity"],
+            required: true
+        });
+
+        if (isCancel(agents)) {
+            cancel("Cancelled.");
+            fs.rmSync(tmp, { recursive: true, force: true });
+            return;
+        }
+
+        const invalidAgents = agents.filter(a => ["claude", "codex", "gemini", "windsurf"].includes(a));
+        if (invalidAgents.length > 0) {
+            step(`Selection contains coming soon agents. Only Antigravity is currently supported.`, S.cross, "red");
+            stepLine();
+            continue;
+        }
+
+        break;
+    }
+
+    if (!agents || agents.length === 0) {
+        console.log(`\n ${c.yellow("No agents selected.")}`);
+        fs.rmSync(tmp, { recursive: true, force: true });
+        return;
+    }
+
+    // Agent summary
+    stepLine();
+    step("Select agents to install skills to");
+    console.log(`${c.gray(S.branch)}  ${c.dim(Array.isArray(agents) ? agents.join(", ") : agents)}`);
+
+    const targetScope = WORKSPACE;
+
+    // Installation scope
+    stepLine();
+    step("Installation scope");
+    console.log(`${c.gray(S.branch)}  ${c.dim("Project")}`);
+
+    // Installation method
+    activeStep("Installation method");
+
+    const installMethod = await select({
+        message: " ",
+        options: [
+            { label: "Symlink (Recommended)", value: "symlink", hint: "Single source of truth, easy updates" },
+            { label: "Copy to all agents", value: "copy" }
+        ],
+        initialValue: "symlink"
+    });
+
+    if (isCancel(installMethod)) {
+        cancel("Cancelled.");
+        fs.rmSync(tmp, { recursive: true, force: true });
+        return;
+    }
+
+    // Installation Summary Box
+    stepLine();
+    step("Installation Summary"); // Passive header for box
+    stepLine();
+
+    const selectedAgentsList = Array.isArray(agents) ? agents : [agents];
+    const agentsString = selectedAgentsList.map(a =>
+        a === "antigravity" ? "Antigravity" :
+            a.charAt(0).toUpperCase() + a.slice(1)
+    ).join(", ");
+
+    let summaryContent = "";
+    const methodVerb = installMethod === "symlink" ? "symlink" : "copy";
+
+    for (const sn of selectedSkills) {
+        // Mock path relative to home for visual appeal
+        const mockPath = `~\\Desktop\\New Project\\.agents\\skills\\${sn}`;
+        summaryContent += `${c.cyan(mockPath)}\n`;
+        summaryContent += `  ${c.dim(methodVerb)} ${c.gray("→")} ${c.dim(agentsString)}\n\n`;
+    }
+
+    // Remove trailing newlines
+    summaryContent = summaryContent.trim();
+
+    console.log(boxen(summaryContent, {
+        padding: 1,
+        borderColor: "gray",
+        borderStyle: "round",
+        dimBorder: true,
+        title: "Installation Summary",
+        titleAlignment: "left"
+    }).split("\n").map(l => `${c.gray(S.branch)}  ${l}`).join("\n"));
+
+    stepLine();
+
+    // Confirmation
+    // Active Step
+    activeStep("Proceed with installation?");
+    const shouldProceed = await confirm({ message: " ", initialValue: true });
+
+    if (isCancel(shouldProceed) || !shouldProceed) {
+        cancel("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);
+
+        await installSkill(src, dest, installMethod, {
+            repo: `${org}/${repo}`,
+            skill: sn,
+            ref: ref || null
+        });
+    }
+
+    // Installation complete step
+    stepLine();
+    step("Installation complete");
+
+    // Final Success Box
+    stepLine();
+    console.log(`${c.gray(S.branch)}`); // Extra spacing line
+
+    let successContent = "";
+    for (const sn of selectedSkills) {
+        const mockPath = `~\\Desktop\\New Project\\.agents\\skills\\${sn}`;
+        successContent += `${c.cyan("✓")} ${c.dim(mockPath)}\n`; // Keeping check inside box as per request, but let's make it Cyan to match theme
+        successContent += `  ${c.dim("symlink")} ${c.gray("→")} ${c.dim(agentsString)}\n`;
+    }
+
+    console.log(boxen(successContent.trim(), {
+        padding: 1,
+        borderColor: "cyan", // Changed to cyan to match 2-color rule
+        borderStyle: "round",
+        title: c.cyan(`Installed ${selectedSkills.length} skills to ${selectedAgentsList.length} agents`),
+        titleAlignment: "left"
+    }).split("\n").map(l => `${c.gray(S.branch)}  ${l}`).join("\n"));
+
+    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,55 @@
+/**
+ * @fileoverview Update command
+ */
+
+import fs from "fs";
+import path from "path";
+
+import { resolveScope, createBackup } from "../helpers.js";
+import { step, stepLine, S, c, fatal, spinner } 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 s = spinner();
+    s.start(`Updating ${skillName}`);
+
+    try {
+        if (!DRY) {
+            createBackup(targetDir, skillName);
+            fs.rmSync(targetDir, { recursive: true, force: true });
+        }
+
+        const spec = `${meta.repo}#${meta.skill}${meta.ref ? "@" + meta.ref : ""}`;
+
+        if (DRY) {
+            s.stop("Dry run analysis complete");
+            step(`Would update: ${skillName}`);
+        } else {
+            s.stop("Preparing update...");
+            // Dynamically import install command
+            const { run: install } = await import("./install.js");
+            await install(spec);
+        }
+    } catch (err) {
+        s.fail(`Failed: ${err.message}`);
+    }
+}

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);
+}

package/bin/lib/commands/verify.js

@@ -0,0 +1,56 @@
+/**
+ * @fileoverview Verify command - Checksum verification
+ */
+
+import fs from "fs";
+import path from "path";
+import { resolveScope, merkleHash } from "../helpers.js";
+import { step, stepLine, S, c } from "../ui.js";
+import { STRICT } from "../config.js";
+
+/**
+ * Verify skill checksums
+ */
+export async function run() {
+    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"));
+        const 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);
+}