@agentskillkit/agent-skills 3.2.1 → 3.2.5

package/packages/kit/kit.js

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+/**
+ * Install Agent Skill CLI
+ * @description Package manager for AI Agent Skills
+ */
+import { c, brandedIntro } from "./lib/ui.js";
+import { command, params, VERSION } from "./lib/config.js";
+
+// --- Command Registry ---
+const COMMANDS = {
+    // Installation
+    install: { module: "./lib/commands/install.js", hasParam: true, aliases: ["add", "i"] },
+    uninstall: { module: "./lib/commands/uninstall.js", hasParam: true, aliases: ["remove", "rm"] },
+    update: { module: "./lib/commands/update.js", hasParam: true },
+
+    // Workspace
+    init: { module: "./lib/commands/init.js", aliases: ["list", "ls"] },
+    lock: { module: "./lib/commands/lock.js" },
+    cache: { module: "./lib/commands/cache.js", hasParam: true },
+
+    // Validation
+    verify: { module: "./lib/commands/verify.js" },
+    doctor: { module: "./lib/commands/doctor.js" },
+    validate: { module: "./lib/commands/validate.js", hasParam: true, aliases: ["check"] },
+    analyze: { module: "./lib/commands/analyze.js", hasParam: true },
+
+    // Info
+    info: { module: "./lib/commands/info.js", hasParam: true, aliases: ["show"] },
+    help: { module: "./lib/commands/help.js", aliases: ["--help", "-h"] }
+};
+
+/**
+ * Find command config by name or alias
+ * @param {string} cmd - Command name or alias
+ * @returns {{ name: string, config: object } | null}
+ */
+function findCommand(cmd) {
+    // Direct match
+    if (COMMANDS[cmd]) {
+        return { name: cmd, config: COMMANDS[cmd] };
+    }
+
+    // Alias match
+    for (const [name, config] of Object.entries(COMMANDS)) {
+        if (config.aliases?.includes(cmd)) {
+            return { name, config };
+        }
+    }
+
+    return null;
+}
+
+// --- MAIN ---
+async function main() {
+    brandedIntro(VERSION);
+
+    try {
+        // Handle version flag
+        if (command === "--version" || command === "-V") {
+            console.log(VERSION);
+            return;
+        }
+
+        // Find command
+        const found = findCommand(command);
+
+        if (found) {
+            const cmdModule = await import(found.config.module);
+            await cmdModule.run(found.config.hasParam ? params[0] : undefined);
+        } else if (command.includes("/")) {
+            // Direct install via org/repo syntax
+            const cmdModule = await import("./lib/commands/install.js");
+            await cmdModule.run(command);
+        } else {
+            console.log(`Unknown command: ${command}`);
+            const cmdModule = await import("./lib/commands/help.js");
+            await cmdModule.run();
+        }
+    } catch (err) {
+        console.error(c.red("\nError: " + err.message));
+        if (process.env.DEBUG) console.error(err.stack);
+        process.exit(1);
+    }
+}
+
+main().catch(err => {
+    console.error(c.red("\nFatal Error: " + err.message));
+    process.exit(1);
+});

package/packages/kit/lib/agents.js

@@ -0,0 +1,208 @@
+/**
+ * @fileoverview Agent definitions and detection
+ * Based on Vercel's agent-skills CLI structure
+ */
+
+import { existsSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+
+const home = homedir();
+
+// Environment-based paths
+const codexHome = process.env.CODEX_HOME?.trim() || join(home, ".codex");
+const claudeHome = process.env.CLAUDE_CONFIG_DIR?.trim() || join(home, ".claude");
+
+/**
+ * @typedef {Object} AgentConfig
+ * @property {string} name - Internal agent ID
+ * @property {string} displayName - Display name for UI
+ * @property {string} skillsDir - Project-level skills directory
+ * @property {string} globalSkillsDir - Global skills directory
+ * @property {() => boolean} detect - Detection function
+ */
+
+/**
+ * All supported agents with detection logic
+ * @type {Record<string, AgentConfig>}
+ */
+export const AGENTS = {
+    antigravity: {
+        name: "antigravity",
+        displayName: "Antigravity",
+        skillsDir: ".agent/skills",
+        globalSkillsDir: join(home, ".gemini/antigravity/global_skills"),
+        detect: () => existsSync(join(process.cwd(), ".agent")) || existsSync(join(home, ".gemini/antigravity"))
+    },
+    "claude-code": {
+        name: "claude-code",
+        displayName: "Claude Code",
+        skillsDir: ".claude/skills",
+        globalSkillsDir: join(claudeHome, "skills"),
+        detect: () => existsSync(claudeHome)
+    },
+    codex: {
+        name: "codex",
+        displayName: "Codex",
+        skillsDir: ".codex/skills",
+        globalSkillsDir: join(codexHome, "skills"),
+        detect: () => existsSync(codexHome) || existsSync("/etc/codex")
+    },
+    "gemini-cli": {
+        name: "gemini-cli",
+        displayName: "Gemini CLI",
+        skillsDir: ".gemini/skills",
+        globalSkillsDir: join(home, ".gemini/skills"),
+        detect: () => existsSync(join(home, ".gemini"))
+    },
+    "github-copilot": {
+        name: "github-copilot",
+        displayName: "GitHub Copilot",
+        skillsDir: ".github/skills",
+        globalSkillsDir: join(home, ".copilot/skills"),
+        detect: () => existsSync(join(process.cwd(), ".github")) || existsSync(join(home, ".copilot"))
+    },
+    windsurf: {
+        name: "windsurf",
+        displayName: "Windsurf",
+        skillsDir: ".windsurf/skills",
+        globalSkillsDir: join(home, ".codeium/windsurf/skills"),
+        detect: () => existsSync(join(home, ".codeium/windsurf"))
+    },
+    cursor: {
+        name: "cursor",
+        displayName: "Cursor",
+        skillsDir: ".cursor/skills",
+        globalSkillsDir: join(home, ".cursor/skills"),
+        detect: () => existsSync(join(home, ".cursor"))
+    },
+    cline: {
+        name: "cline",
+        displayName: "Cline",
+        skillsDir: ".cline/skills",
+        globalSkillsDir: join(home, ".cline/skills"),
+        detect: () => existsSync(join(home, ".cline"))
+    },
+    roo: {
+        name: "roo",
+        displayName: "Roo Code",
+        skillsDir: ".roo/skills",
+        globalSkillsDir: join(home, ".roo/skills"),
+        detect: () => existsSync(join(home, ".roo"))
+    },
+    continue: {
+        name: "continue",
+        displayName: "Continue",
+        skillsDir: ".continue/skills",
+        globalSkillsDir: join(home, ".continue/skills"),
+        detect: () => existsSync(join(process.cwd(), ".continue")) || existsSync(join(home, ".continue"))
+    },
+    goose: {
+        name: "goose",
+        displayName: "Goose",
+        skillsDir: ".goose/skills",
+        globalSkillsDir: join(home, ".config/goose/skills"),
+        detect: () => existsSync(join(home, ".config/goose"))
+    },
+    trae: {
+        name: "trae",
+        displayName: "Trae",
+        skillsDir: ".trae/skills",
+        globalSkillsDir: join(home, ".trae/skills"),
+        detect: () => existsSync(join(home, ".trae"))
+    },
+    kilo: {
+        name: "kilo",
+        displayName: "Kilo Code",
+        skillsDir: ".kilocode/skills",
+        globalSkillsDir: join(home, ".kilocode/skills"),
+        detect: () => existsSync(join(home, ".kilocode"))
+    },
+    opencode: {
+        name: "opencode",
+        displayName: "OpenCode",
+        skillsDir: ".opencode/skills",
+        globalSkillsDir: join(home, ".config/opencode/skills"),
+        detect: () => existsSync(join(home, ".config/opencode"))
+    },
+    amp: {
+        name: "amp",
+        displayName: "Amp",
+        skillsDir: ".agents/skills",
+        globalSkillsDir: join(home, ".config/agents/skills"),
+        detect: () => existsSync(join(home, ".config/amp"))
+    },
+    junie: {
+        name: "junie",
+        displayName: "Junie",
+        skillsDir: ".junie/skills",
+        globalSkillsDir: join(home, ".junie/skills"),
+        detect: () => existsSync(join(home, ".junie"))
+    },
+    "kiro-cli": {
+        name: "kiro-cli",
+        displayName: "Kiro CLI",
+        skillsDir: ".kiro/skills",
+        globalSkillsDir: join(home, ".kiro/skills"),
+        detect: () => existsSync(join(home, ".kiro"))
+    },
+    zencoder: {
+        name: "zencoder",
+        displayName: "Zencoder",
+        skillsDir: ".zencoder/skills",
+        globalSkillsDir: join(home, ".zencoder/skills"),
+        detect: () => existsSync(join(home, ".zencoder"))
+    },
+    openhands: {
+        name: "openhands",
+        displayName: "OpenHands",
+        skillsDir: ".openhands/skills",
+        globalSkillsDir: join(home, ".openhands/skills"),
+        detect: () => existsSync(join(home, ".openhands"))
+    },
+    "qwen-code": {
+        name: "qwen-code",
+        displayName: "Qwen Code",
+        skillsDir: ".qwen/skills",
+        globalSkillsDir: join(home, ".qwen/skills"),
+        detect: () => existsSync(join(home, ".qwen"))
+    }
+};
+
+/**
+ * Detect all installed agents on the system
+ * @returns {Array<{name: string, displayName: string, skillsDir: string, globalSkillsDir: string}>}
+ */
+export function detectInstalledAgents() {
+    const detected = [];
+
+    for (const [key, config] of Object.entries(AGENTS)) {
+        if (config.detect()) {
+            detected.push({
+                name: config.name,
+                displayName: config.displayName,
+                skillsDir: config.skillsDir,
+                globalSkillsDir: config.globalSkillsDir
+            });
+        }
+    }
+
+    return detected;
+}
+
+/**
+ * Get agent config by name
+ * @param {string} name - Agent name
+ * @returns {AgentConfig | undefined}
+ */
+export function getAgentConfig(name) {
+    return AGENTS[name];
+}
+
+/**
+ * Get all agent names
+ * @returns {string[]}
+ */
+export function getAllAgentNames() {
+    return Object.keys(AGENTS);
+}

package/packages/kit/lib/commands/analyze.js

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

package/packages/kit/lib/commands/cache.js

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

package/packages/kit/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/packages/kit/lib/commands/help.js

@@ -0,0 +1,155 @@
+/**
+ * @fileoverview Help command
+ */
+
+import { step, stepLine, S, c, select, isCancel, cancel } from "../ui.js";
+import { VERSION } from "../config.js";
+
+/**
+ * Show interactive help menu
+ */
+export async function run() {
+  let running = true;
+
+  while (running) {
+
+    const choice = await select({
+      message: "Select a topic",
+      options: [
+        { value: "commands", label: "Commands", hint: "View all available commands" },
+        { value: "options", label: "Options", hint: "View all flags and options" },
+        { value: "quickstart", label: "Quick Start", hint: "Get started quickly" },
+        { value: "exit", label: "Exit", hint: "Close help" }
+      ]
+    });
+
+    if (isCancel(choice) || choice === "exit") {
+      stepLine();
+      step("Goodbye!");
+      stepLine();
+      return;
+    }
+
+    stepLine();
+
+    switch (choice) {
+      case "commands":
+        await showCommands();
+        break;
+      case "options":
+        showOptions();
+        break;
+      case "quickstart":
+        showQuickStart();
+        break;
+    }
+
+    stepLine();
+
+    // Ask what to do next
+    const next = await select({
+      message: "What's next?",
+      options: [
+        { value: "back", label: "Back to menu", hint: "See other topics" },
+        { value: "exit", label: "Exit", hint: "Close help" }
+      ]
+    });
+
+    if (isCancel(next) || next === "exit") {
+      stepLine();
+      step("Goodbye!");
+      stepLine();
+      running = false;
+    }
+  }
+}
+
+async function showCommands() {
+  step(c.bold("Available Commands"), S.diamondFilled, "cyan");
+  stepLine();
+
+  step(c.cyan("<org/repo>") + c.dim("          Install all skills from repository"));
+  step(c.dim("Example: kit agentskillkit/agent-skills"));
+  stepLine();
+
+  step(c.cyan("<org/repo#skill>") + c.dim("    Install specific skill"));
+  step(c.dim("Example: kit agentskillkit/agent-skills#react-patterns"));
+  stepLine();
+
+  step(c.cyan("list") + c.dim("                List installed skills"));
+  step(c.cyan("uninstall") + c.dim("          Remove skill(s) (interactive)"));
+  step(c.cyan("uninstall all") + c.dim("       Remove everything (automatic)"));
+  step(c.cyan("update <skill>") + c.dim("      Update a skill"));
+  step(c.cyan("verify") + c.dim("              Verify checksums"));
+  step(c.cyan("doctor") + c.dim("              Check health"));
+  step(c.cyan("lock") + c.dim("                Generate skill-lock.json"));
+  step(c.cyan("init") + c.dim("                Initialize skills directory"));
+  step(c.cyan("validate [skill]") + c.dim("    Validate against Antigravity spec"));
+  step(c.cyan("analyze <skill>") + c.dim("     Analyze skill structure"));
+  step(c.cyan("cache [info|clear]") + c.dim("  Manage cache"));
+  step(c.cyan("info <skill>") + c.dim("        Show skill info"));
+
+  stepLine();
+
+  // Interactive command selection
+  const executeCmd = await select({
+    message: "Execute a command?",
+    options: [
+      { value: "list", label: "list", hint: "List installed skills" },
+      { value: "doctor", label: "doctor", hint: "Check health" },
+      { value: "verify", label: "verify", hint: "Verify checksums" },
+      { value: "uninstall", label: "uninstall", hint: "Interactive removal" },
+      { value: "lock", label: "lock", hint: "Generate lockfile" },
+      { value: "init", label: "init", hint: "Initialize directory" },
+      { value: "none", label: "← Back", hint: "Return to topics" }
+    ]
+  });
+
+  if (!isCancel(executeCmd) && executeCmd !== "none") {
+    stepLine();
+    step(c.cyan(`Running: kit ${executeCmd}`));
+    stepLine();
+
+    // Dynamic import and execute command
+    try {
+      const commandModule = await import(`./${executeCmd}.js`);
+      await commandModule.run();
+    } catch (err) {
+      step(c.red(`Command not yet implemented: ${executeCmd}`));
+    }
+  }
+}
+
+function showOptions() {
+  step(c.bold("Available Options"), S.diamondFilled, "cyan");
+  stepLine();
+
+  step(c.cyan("--global, -g") + c.dim("        Use global scope (~/.gemini)"));
+  step(c.cyan("--force, -f") + c.dim("         Force operation without confirmation"));
+  step(c.cyan("--strict") + c.dim("            Fail on any violations"));
+  step(c.cyan("--fix") + c.dim("               Auto-fix issues (e.g., checksums)"));
+  step(c.cyan("--dry-run") + c.dim("           Preview changes without executing"));
+  step(c.cyan("--verbose, -v") + c.dim("       Show detailed output"));
+  step(c.cyan("--json") + c.dim("              Output in JSON format"));
+}
+
+function showQuickStart() {
+  step(c.bold("Quick Start Guide"), S.diamondFilled, "cyan");
+  stepLine();
+
+  step(c.bold("1. Install skills"));
+  step("   " + c.cyan("kit agentskillkit/agent-skills"));
+  stepLine();
+
+  step(c.bold("2. Choose scope"));
+  step("   " + c.dim("→ Current Project (local .agent/)"));
+  step("   " + c.dim("→ Global System (available everywhere)"));
+  stepLine();
+
+  step(c.bold("3. Check installation"));
+  step("   " + c.cyan("kit doctor"));
+  stepLine();
+
+  step(c.bold("4. Use in your AI"));
+  step("   " + c.dim("Skills are now available in .agent/skills/"));
+}