add-skill-kit 1.0.0

package/README.md

@@ -0,0 +1,194 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/agentskillkit/add-skill-kit/main/.github/logo.svg" height="128">
+  <h1 align="center">add-skill-kit</h1>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/add-skill-kit"><img src="https://img.shields.io/npm/v/add-skill-kit?style=flat&colorA=18181b&colorB=7c3aed" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/add-skill-kit"><img src="https://img.shields.io/npm/d18m/add-skill-kit?style=flat&colorA=18181b&colorB=7c3aed" alt="npm downloads"></a>
+  <a href="https://github.com/agentskillkit/add-skill-kit/blob/main/LICENSE"><img src="https://img.shields.io/github/license/agentskillkit/add-skill-kit?style=flat&colorA=18181b&colorB=7c3aed" alt="license"></a>
+</p>
+
+<p align="center">
+  The enterprise-grade package manager for AI Agent Skills.<br/>
+  Designed for the <strong>Antigravity Skills</strong> specification.
+</p>
+
+<p align="center">
+  <a href="#installation">Installation</a> •
+  <a href="#quick-start">Quick Start</a> •
+  <a href="#commands">Commands</a> •
+  <a href="#features">Features</a> •
+  <a href="#documentation">Docs</a>
+</p>
+
+---
+
+## What is add-skill-kit?
+
+`add-skill-kit` is a CLI tool for managing **Agent Skills**—immutable, verifiable intelligence artifacts that extend your AI agent's capabilities. Think of it as `npm` for AI agents.
+
+```bash
+npx add-skill-kit agentskillkit/agent-skills
+```
+
+Skills are **data, not code**. They won't execute on your system—they're read by your agent to enhance its behavior.
+
+---
+
+## Installation
+
+```bash
+# Using npm
+npm install -g add-skill-kit
+
+# Using pnpm
+pnpm add -g add-skill-kit
+
+# Using Yarn
+yarn global add add-skill-kit
+
+# Or run directly with npx
+npx add-skill-kit <command>
+```
+
+> **Requirements:** Node.js 18.0.0 or later
+
+---
+
+## Quick Start
+
+### 1. Initialize your workspace
+
+```bash
+npx add-skill-kit init
+```
+
+This creates the `.agent/skills` directory structure in your project.
+
+### 2. Install a skill
+
+Install from GitHub with optional version pinning:
+
+```bash
+# Latest version
+npx add-skill-kit agentskillkit/agent-skills
+
+# Specific skill
+npx add-skill-kit agentskillkit/agent-skills#react-patterns
+
+# Specific version
+npx add-skill-kit agentskillkit/agent-skills#react-patterns@v1.0.0
+```
+
+### 3. List installed skills
+
+```bash
+npx add-skill-kit list
+```
+
+### 4. Validate compliance
+
+```bash
+npx add-skill-kit validate
+```
+
+---
+
+## Commands
+
+| Command | Description |
+| :--- | :--- |
+| `init` | Initialize `.agent/skills` workspace |
+| `install <spec>` | Install a skill from GitHub or registry |
+| `uninstall <name>` | Remove an installed skill |
+| `update <name>` | Update a skill to latest version |
+| `upgrade-all` | Upgrade all skills in workspace |
+| `list` | List installed skills with metadata |
+| `validate` | Check Antigravity compliance |
+| `analyze <name>` | Inspect skill structure & Progressive Disclosure |
+| `doctor` | Check health & integrity |
+| `lock` | Generate `skill-lock.json` |
+| `cache clear` | Clear local cache |
+
+---
+
+## Features
+
+### Progressive Disclosure
+
+Skills follow a structured hierarchy that lets agents read only what they need:
+
+```
+skill/
+├── SKILL.md              # Core instructions (always read)
+├── resources/            # Reference materials (on-demand)
+├── examples/             # Implementation patterns (when coding)
+├── scripts/              # Helper utilities (when needed)
+├── constitution/         # Governing rules
+└── doctrines/           # Behavioral policies
+```
+
+### Deterministic Locking
+
+Pin exact versions for reproducible builds across your team:
+
+```bash
+# Generate lockfile
+npx add-skill-kit lock
+
+# Install from lockfile
+npx add-skill-kit install --locked
+```
+
+### Security by Design
+
+| Feature | Description |
+| :--- | :--- |
+| **No Execution** | Skills are data artifacts, never executed |
+| **SHA-256 Hashing** | Every skill is verified against its Merkle hash |
+| **Integrity Checks** | `doctor` command detects tampering |
+| **Audit Trail** | Full provenance tracking in `.skill-source.json` |
+
+---
+
+## Documentation
+
+<table>
+<tbody>
+<tr>
+<td><a href="https://github.com/agentskillkit/add-skill-kit/blob/main/specs/SKILL_V1.md">Skill Spec v1.0</a></td>
+<td>The Antigravity Skills specification</td>
+</tr>
+<tr>
+<td><a href="https://github.com/agentskillkit/add-skill-kit/tree/main/examples">Examples</a></td>
+<td>Example skills and integration patterns</td>
+</tr>
+<tr>
+<td><a href="https://github.com/agentskillkit/add-skill-kit/issues">Issues</a></td>
+<td>Report bugs or request features</td>
+</tr>
+</tbody>
+</table>
+
+---
+
+## Community
+
+We welcome contributions! See our [Contributing Guide](https://github.com/agentskillkit/add-skill-kit/blob/main/CONTRIBUTING.md) to get started.
+
+<a href="https://github.com/agentskillkit/add-skill-kit/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=agentskillkit/add-skill-kit" />
+</a>
+
+---
+
+<p align="center">
+  <sub>Built with ❤️ by <a href="https://github.com/agentskillkit">Agent Skill Kit</a></sub>
+</p>
+
+<p align="center">
+  <a href="https://github.com/agentskillkit/add-skill-kit">GitHub</a> •
+  <a href="https://www.npmjs.com/package/add-skill-kit">npm</a> •
+  <a href="https://github.com/agentskillkit/add-skill-kit/blob/main/LICENSE">License</a>
+</p>

package/bin/cli.js

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+/**
+ * Install Agent Skill v1.0.0
+ */
+import { c, step, fatal, intro, outro } from "./lib/ui.js";
+import { command, params, flags, VERSION } from "./lib/config.js";
+
+// --- MAIN ---
+async function main() {
+    intro(c.bgBlue(c.white(` Add Skill Kit v${VERSION} `)));
+
+    // Basic command routing
+    let cmdModule;
+
+    try {
+        switch (command) {
+            case "list":
+            case "ls":
+            case "init":
+                cmdModule = await import("./lib/commands/init.js");
+                await cmdModule.run();
+                break;
+            case "install":
+            case "add":
+            case "i":
+                cmdModule = await import("./lib/commands/install.js");
+                await cmdModule.run(params[0]);
+                break;
+            case "uninstall":
+            case "remove":
+            case "rm":
+                cmdModule = await import("./lib/commands/uninstall.js");
+                await cmdModule.run(params[0]);
+                break;
+            case "update":
+                cmdModule = await import("./lib/commands/update.js");
+                await cmdModule.run(params[0]);
+                break;
+            case "lock":
+                cmdModule = await import("./lib/commands/lock.js");
+                await cmdModule.run();
+                break;
+            case "verify":
+                cmdModule = await import("./lib/commands/verify.js");
+                await cmdModule.run();
+                break;
+            case "doctor":
+                cmdModule = await import("./lib/commands/doctor.js");
+                await cmdModule.run();
+                break;
+            case "cache":
+                cmdModule = await import("./lib/commands/cache.js");
+                await cmdModule.run(params[0]);
+                break;
+            case "validate":
+            case "check":
+                cmdModule = await import("./lib/commands/validate.js");
+                await cmdModule.run(params[0]);
+                break;
+            case "analyze":
+                cmdModule = await import("./lib/commands/analyze.js");
+                await cmdModule.run(params[0]);
+                break;
+            case "info":
+            case "show":
+                cmdModule = await import("./lib/commands/info.js");
+                await cmdModule.run(params[0]);
+                break;
+            case "help":
+            case "--help":
+            case "-h":
+                cmdModule = await import("./lib/commands/help.js");
+                await cmdModule.run();
+                break;
+            case "--version":
+            case "-V":
+                console.log(VERSION);
+                break;
+            default:
+                // Handle direct install via org/repo syntax
+                if (command.includes("/")) {
+                    cmdModule = await import("./lib/commands/install.js");
+                    await cmdModule.run(command);
+                } else {
+                    console.log(`Unknown command: ${command}`);
+                    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/bin/lib/commands/analyze.js

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

package/bin/lib/commands/cache.js

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

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-kit")} ${c.dim("v" + VERSION)}
+
+  ${c.bold("Usage")}
+    $ add-skill-kit <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}`);
+}