add-skill-kit 1.1.0 → 1.3.1

package/README.md

@@ -1,105 +1,175 @@
-<p align="center">
-  <img src="https://raw.githubusercontent.com/agentskillkit/add-skill-kit/main/.github/logo.svg" height="96">
-</p>
+# add-skill-kit
 
-<h1 align="center">add-skill-kit</h1>
+> **The package manager for AI Agent Skills**
 
-<p align="center">
-  <strong>The package manager for AI Agent Skills</strong>
-</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"></a>
-  <a href="https://www.npmjs.com/package/add-skill-kit"><img src="https://img.shields.io/npm/dm/add-skill-kit?style=flat&colorA=18181b&colorB=7c3aed" alt="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">
-  <a href="#install">Install</a> •
-  <a href="#why">Why?</a> •
-  <a href="#what-you-get">What You Get</a> •
-  <a href="#commands">Commands</a>
-</p>
+[![npm](https://img.shields.io/npm/v/add-skill-kit?style=flat&colorA=18181b&colorB=7c3aed)](https://www.npmjs.com/package/add-skill-kit)
+[![downloads](https://img.shields.io/npm/dm/add-skill-kit?style=flat&colorA=18181b&colorB=7c3aed)](https://www.npmjs.com/package/add-skill-kit)
+[![license](https://img.shields.io/github/license/agentskillkit/add-skill-kit?style=flat&colorA=18181b&colorB=7c3aed)](https://github.com/agentskillkit/add-skill-kit/blob/main/LICENSE)
 
 ---
 
-## Install
+## Quick Install
 
 ```bash
 npx -y add-skill-kit agentskillkit/agent-skills
 ```
 
-One command. 40+ skills. Your AI agent just got superpowers.
+Or install globally:
 
----
+```bash
+npm install -g add-skill-kit
+add-skill-kit agentskillkit/agent-skills
+```
 
-## Why?
+This installs the `.agent` folder containing all templates into your project.
 
-**Problem:** AI agents give inconsistent advice. No memory. No standards.
+---
 
-**Solution:** Skills are portable intelligence packages. Install once, benefit forever.
+## What's Included
 
-| Before | After |
-|--------|-------|
-| Copy-paste prompts | Version-controlled skills |
-| Inconsistent output | Curated best practices |
-| No team standards | Shared skill repositories |
-| Manual updates | `add-skill-kit update` |
+| Component | Count | Description |
+|-----------|-------|-------------|
+| **Agents** | 20 | Specialist AI personas (frontend, backend, security, PM, QA, etc.) |
+| **Skills** | 40+ | Domain-specific knowledge modules |
+| **Workflows** | 11 | Slash command procedures |
 
 ---
 
-## What You Get
+## Usage
+
+### Using Agents
+
+**No need to mention agents explicitly!** The system automatically detects and applies the right specialist(s):
 
 ```
-your-project/
-└── .agent/
-    ├── skills/           # 40+ domain skills
-    │   ├── react-patterns/
-    │   ├── api-patterns/
-    │   ├── testing-patterns/
-    │   └── ...
-    ├── workflows/        # /debug, /plan, /deploy...
-    └── GEMINI.md         # Agent config
+You: "Add JWT authentication"
+AI: 🤖 Applying @security-auditor + @backend-specialist...
+
+You: "Fix the dark mode button"
+AI: 🤖 Using @frontend-specialist...
+
+You: "Login returns 500 error"
+AI: 🤖 Using @debugger for systematic analysis...
 ```
 
-**Top Skills:**
-- `react-patterns` — Hooks, composition, performance
-- `api-patterns` — REST, GraphQL, tRPC
-- `testing-patterns` — Unit, integration, E2E
-- `systematic-debugging` — 4-phase methodology
-- `vulnerability-scanner` — OWASP security
+**How it works:**
+1. Analyzes your request silently
+2. Detects domain(s) automatically (frontend, backend, security, etc.)
+3. Selects the best specialist(s)
+4. Informs you which expertise is being applied
 
----
+**Benefits:**
+- ✅ Zero learning curve - just describe what you need
+- ✅ Always get expert responses
+- ✅ Transparent - shows which agent is being used
+- ✅ Can still override by mentioning agent explicitly
 
-## How It Works
+---
 
+### Using Workflows
+
+Invoke workflows with slash commands:
+
+| Command | Description |
+|---------|-------------|
+| `/brainstorm` | Explore options before implementation |
+| `/create` | Create new features or apps |
+| `/debug` | Systematic debugging |
+| `/deploy` | Deploy application |
+| `/enhance` | Improve existing code |
+| `/orchestrate` | Multi-agent coordination |
+| `/plan` | Create task breakdown |
+| `/preview` | Preview changes locally |
+| `/status` | Check project status |
+| `/test` | Generate and run tests |
+| `/ui-ux-pro-max` | Design with 50 styles |
+
+**Example:**
 ```
-GitHub Repo → add-skill-kit → .agent/skills/
-                                    ↓
-                              AI Agent reads
+/brainstorm authentication system
+/create landing page with hero section
+/debug why login fails
 ```
 
-**Security:**
-- ✅ Skills are read-only data
-- ✅ No code execution
-- ✅ SHA-256 verification
+---
+
+### Using Skills
+
+Skills are loaded automatically based on task context:
+
+| Skill | Description |
+|-------|-------------|
+| `react-patterns` | Modern React hooks & composition |
+| `api-patterns` | REST, GraphQL, tRPC design |
+| `testing-patterns` | Unit, integration, E2E strategies |
+| `clean-code` | Pragmatic coding standards |
+| `systematic-debugging` | 4-phase debug methodology |
+| `vulnerability-scanner` | OWASP security audit |
+| ...and 30+ more | |
 
 ---
 
-## Commands
+## CLI Commands
 
 ```bash
-# Install from repository
+# Install skills from repository
 npx -y add-skill-kit <org/repo>
 
 # Install specific skill
 npx -y add-skill-kit <org/repo>#skill-name
 
-# List installed
+# List installed skills
 npx -y add-skill-kit list
 
-# Validate
+# Validate skill integrity
 npx -y add-skill-kit validate
+
+# Check workspace health
+npx -y add-skill-kit doctor
+```
+
+---
+
+## How It Works
+
+Skills are **data, not code**. They never execute on your system.
+
+```
+┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
+│  GitHub Repo    │────▶│  add-skill-kit  │────▶│  .agent/skills  │
+│  (source)       │     │  (installer)    │     │  (your project) │
+└─────────────────┘     └─────────────────┘     └─────────────────┘
+                                                        │
+                                                        ▼
+                                               ┌─────────────────┐
+                                               │   AI Agent      │
+                                               │   reads skills  │
+                                               └─────────────────┘
+```
+
+**Security:**
+- ✅ Skills are read-only markdown & YAML
+- ✅ No scripts executed during install
+- ✅ SHA-256 integrity verification
+- ✅ Full audit trail in `.skill-source.json`
+
+---
+
+## Project Structure After Install
+
+```
+your-project/
+└── .agent/
+    ├── skills/           # 40+ domain skills
+    │   ├── react-patterns/
+    │   ├── api-patterns/
+    │   ├── testing-patterns/
+    │   └── ...
+    ├── workflows/        # Slash commands
+    │   ├── brainstorm.md
+    │   ├── debug.md
+    │   └── ...
+    └── GEMINI.md         # Agent configuration
 ```
 
 ---
@@ -111,21 +181,24 @@ npx -y add-skill-kit validate
 | **Antigravity** | ✅ Ready |
 | Claude Code | 🔜 Coming |
 | Gemini CLI | 🔜 Coming |
+| Codex | 🔜 Coming |
 
 ---
 
-## Install Now
+## Requirements
 
-```bash
-npx -y add-skill-kit agentskillkit/agent-skills
-```
+- Node.js 18+
+
+---
+
+## Documentation
+
+- [GitHub Repository](https://github.com/agentskillkit/add-skill-kit)
+- [Issues & Feature Requests](https://github.com/agentskillkit/add-skill-kit/issues)
+- [npm Package](https://www.npmjs.com/package/add-skill-kit)
+
+---
 
-<p align="center">
-  <sub>Built by <a href="https://github.com/agentskillkit">Agent Skill Kit</a></sub>
-</p>
+## License
 
-<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">MIT</a>
-</p>
+MIT © [Agent Skill Kit](https://github.com/agentskillkit)

package/bin/cli.js

@@ -1,91 +1,80 @@
 #!/usr/bin/env node
 /**
- * Install Agent Skill v1.0.0
+ * Install Agent Skill CLI
+ * @description Package manager for AI Agent Skills
  */
-import { c, step, fatal, intro, outro } from "./lib/ui.js";
-import { command, params, flags, VERSION } from "./lib/config.js";
+import { c, intro } 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() {
     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();
-                }
+        // 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));

package/bin/lib/commands/install.js

@@ -12,7 +12,7 @@ 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 { WORKSPACE, GLOBAL_DIR, OFFLINE } from "../config.js";
 import { installSkill } from "../installer.js";
 
 /**
@@ -32,6 +32,15 @@ export async function run(spec) {
         return;
     }
 
+    // Check offline mode
+    if (OFFLINE) {
+        stepLine();
+        step(c.yellow("Offline mode enabled"), S.diamond, "yellow");
+        step(c.dim("Cannot install from remote repository in offline mode"), S.branch, "gray");
+        step(c.dim("Use --locked to install from lockfile instead"), S.branch, "gray");
+        return;
+    }
+
     const url = `https://github.com/${org}/${repo}.git`;
 
     stepLine();
@@ -42,11 +51,50 @@ export async function run(spec) {
 
     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");
+    // Retry logic with exponential backoff
+    const MAX_RETRIES = 3;
+    let lastError = null;
+
+    for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+        try {
+            await execAsync(`git clone --depth=1 ${url} "${tmp}"`, { timeout: 60000 });
+            if (ref) await execAsync(`git -C "${tmp}" checkout ${ref}`, { timeout: 30000 });
+            lastError = null;
+            break;
+        } catch (err) {
+            lastError = err;
+
+            if (attempt < MAX_RETRIES) {
+                const delay = Math.pow(2, attempt) * 1000; // 2s, 4s
+                s.message(`Retry ${attempt}/${MAX_RETRIES} in ${delay / 1000}s...`);
+                await new Promise(r => setTimeout(r, delay));
+
+                // Clean up failed attempt
+                try { fs.rmSync(tmp, { recursive: true, force: true }); } catch { }
+                fs.mkdirSync(tmp, { recursive: true });
+            }
+        }
+    }
+
+    if (lastError) {
+        s.fail("Failed to clone repository");
+        stepLine();
+
+        // Provide helpful error messages
+        const errMsg = lastError.message || "";
+        if (errMsg.includes("not found") || errMsg.includes("404")) {
+            step(c.red(`Repository not found: ${org}/${repo}`), S.cross, "red");
+            step(c.dim("Check if the repository exists and is public"), S.branch, "gray");
+        } else if (errMsg.includes("timeout")) {
+            step(c.red("Connection timeout"), S.cross, "red");
+            step(c.dim("Check your internet connection and try again"), S.branch, "gray");
+        } else if (errMsg.includes("Could not resolve")) {
+            step(c.red("Network error: Unable to reach GitHub"), S.cross, "red");
+            step(c.dim("Check your internet connection"), S.branch, "gray");
+        } else {
+            step(c.red("Clone failed: " + errMsg.split("\n")[0]), S.cross, "red");
+        }
+
         fs.rmSync(tmp, { recursive: true, force: true });
         return;
     }
@@ -159,9 +207,17 @@ export async function run(spec) {
     step("Select skills to install");
     console.log(`${c.gray(S.branch)}  ${c.dim(selectedSkills.join(", "))}`);
 
-    // Agent selection
+    // Agent selection - currently only Antigravity supported
+    const availableAgents = [
+        { label: "Antigravity (.agent/skills)", value: "antigravity", available: true },
+        { label: "Claude Code (coming soon)", value: "claude", available: false },
+        { label: "Codex (coming soon)", value: "codex", available: false },
+        { label: "Gemini CLI (coming soon)", value: "gemini", available: false },
+        { label: "Windsurf (coming soon)", value: "windsurf", available: false }
+    ];
+    const activeAgentCount = availableAgents.filter(a => a.available).length;
     stepLine();
-    step("Detected 5 agents"); // Passive info
+    step(`Detected ${availableAgents.length} agents (${activeAgentCount} available)`);
 
     let agents;
     while (true) {
@@ -170,13 +226,10 @@ export async function run(spec) {
 
         agents = await multiselect({
             message: `${c.cyan("space")} select · ${c.cyan("enter")} confirm`,
-            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" }
-            ],
+            options: availableAgents.map(a => ({
+                label: a.available ? a.label : c.dim(a.label),
+                value: a.value
+            })),
             initialValues: ["antigravity"],
             required: true
         });
@@ -248,9 +301,9 @@ export async function run(spec) {
     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`;
+        // Show actual target path
+        const targetPath = path.relative(cwd, path.join(targetScope, sn));
+        summaryContent += `${c.cyan(targetPath)}\n`;
         summaryContent += `  ${c.dim(methodVerb)} ${c.gray("→")} ${c.dim(agentsString)}\n\n`;
     }
 

package/bin/lib/config.js

@@ -8,11 +8,11 @@ import os from "os";
 /** Current working directory */
 export const cwd = process.cwd();
 
-/** Local workspace skills directory */
-export const WORKSPACE = path.join(cwd, ".agent", "skills");
+/** Local workspace skills directory (configurable via ADD_SKILL_WORKSPACE) */
+export const WORKSPACE = process.env.ADD_SKILL_WORKSPACE || path.join(cwd, ".agent", "skills");
 
-/** Global skills directory */
-export const GLOBAL_DIR = path.join(os.homedir(), ".gemini", "antigravity", "skills");
+/** Global skills directory (configurable via ADD_SKILL_GLOBAL_DIR) */
+export const GLOBAL_DIR = process.env.ADD_SKILL_GLOBAL_DIR || path.join(os.homedir(), ".gemini", "antigravity", "skills");
 
 /** Cache root directory */
 export const CACHE_ROOT = process.env.ADD_SKILL_CACHE_DIR || path.join(os.homedir(), ".cache", "agentskillskit");
@@ -41,31 +41,28 @@ export const params = args.filter((a) => !a.startsWith("--")).slice(1);
 
 // --- Flag Shortcuts ---
 
-/** Use global scope */
+/** @type {boolean} Use global scope */
 export const GLOBAL = flags.has("--global") || flags.has("-g");
 
-/** Verbose output */
+/** @type {boolean} Verbose output */
 export const VERBOSE = flags.has("--verbose") || flags.has("-v");
 
-/** JSON output mode */
+/** @type {boolean} JSON output mode */
 export const JSON_OUTPUT = flags.has("--json");
 
-/** Force operation */
+/** @type {boolean} Force operation */
 export const FORCE = flags.has("--force") || flags.has("-f");
 
-/** Dry run mode */
+/** @type {boolean} Dry run mode */
 export const DRY = flags.has("--dry-run");
 
-/** Strict mode */
+/** @type {boolean} Strict mode */
 export const STRICT = flags.has("--strict");
 
-/** Auto-fix mode */
-export const FIX = flags.has("--fix");
-
-/** Locked mode */
+/** @type {boolean} Locked mode (install from lockfile) */
 export const LOCKED = flags.has("--locked");
 
-/** Offline mode */
+/** @type {boolean} Offline mode (skip network operations) */
 export const OFFLINE = flags.has("--offline");
 
 // --- Package Info ---
@@ -73,8 +70,9 @@ export const OFFLINE = flags.has("--offline");
 import { createRequire } from "module";
 const require = createRequire(import.meta.url);
 
-/** Package version */
+/** @type {string} Package version */
 export const VERSION = (() => {
     try { return require("../../package.json").version; }
-    catch { return "5.0.0"; }
+    catch { return "1.2.0"; }
 })();
+

package/bin/lib/helpers.js

@@ -24,7 +24,10 @@ export function getDirSize(dir) {
             }
         };
         walk(dir);
-    } catch { }
+    } catch (err) {
+        // Directory may not exist or be inaccessible
+        if (process.env.DEBUG) console.error(`getDirSize error: ${err.message}`);
+    }
     return size;
 }
 
@@ -78,10 +81,24 @@ export function merkleHash(dir) {
  * @returns {import('./types.js').ParsedSpec}
  */
 export function parseSkillSpec(spec) {
+    if (!spec || typeof spec !== 'string') {
+        throw new Error('Skill spec is required');
+    }
+
     const [repoPart, skillPart] = spec.split("#");
+
+    if (!repoPart.includes('/')) {
+        throw new Error(`Invalid spec format: "${spec}". Expected: org/repo or org/repo#skill`);
+    }
+
     const [org, repo] = repoPart.split("/");
+
+    if (!org || !repo) {
+        throw new Error(`Invalid spec: missing org or repo in "${spec}"`);
+    }
+
     const [skill, ref] = (skillPart || "").split("@");
-    return { org, repo, skill, ref };
+    return { org, repo, skill: skill || undefined, ref: ref || undefined };
 }
 
 /**
@@ -140,8 +157,12 @@ export function loadSkillLock() {
  * @returns {string[]}
  */
 export function loadRegistries() {
-    try { return fs.existsSync(REGISTRIES_FILE) ? JSON.parse(fs.readFileSync(REGISTRIES_FILE, "utf-8")) : []; }
-    catch { return []; }
+    try {
+        return fs.existsSync(REGISTRIES_FILE) ? JSON.parse(fs.readFileSync(REGISTRIES_FILE, "utf-8")) : [];
+    } catch (err) {
+        if (process.env.DEBUG) console.error(`loadRegistries error: ${err.message}`);
+        return [];
+    }
 }
 
 /**

package/bin/lib/helpers.test.js

@@ -0,0 +1,60 @@
+/**
+ * @fileoverview Tests for helpers.js
+ */
+import { describe, it, expect } from "vitest";
+import { formatBytes, formatDate, parseSkillSpec } from "./helpers.js";
+
+describe("formatBytes", () => {
+    it("formats bytes correctly", () => {
+        expect(formatBytes(0)).toBe("0 B");
+        expect(formatBytes(512)).toBe("512 B");
+        expect(formatBytes(1024)).toBe("1.0 KB");
+        expect(formatBytes(1536)).toBe("1.5 KB");
+        expect(formatBytes(1048576)).toBe("1.0 MB");
+        expect(formatBytes(1572864)).toBe("1.5 MB");
+    });
+});
+
+describe("formatDate", () => {
+    it("returns 'unknown' for undefined", () => {
+        expect(formatDate()).toBe("unknown");
+        expect(formatDate(undefined)).toBe("unknown");
+    });
+
+    it("formats ISO date strings", () => {
+        const result = formatDate("2026-01-25T00:00:00.000Z");
+        expect(result).toBeTruthy();
+        expect(typeof result).toBe("string");
+    });
+});
+
+describe("parseSkillSpec", () => {
+    it("parses org/repo format", () => {
+        const result = parseSkillSpec("agentskillkit/agent-skills");
+        expect(result.org).toBe("agentskillkit");
+        expect(result.repo).toBe("agent-skills");
+        expect(result.skill).toBeUndefined();
+        expect(result.ref).toBeUndefined();
+    });
+
+    it("parses org/repo#skill format", () => {
+        const result = parseSkillSpec("agentskillkit/agent-skills#react-patterns");
+        expect(result.org).toBe("agentskillkit");
+        expect(result.repo).toBe("agent-skills");
+        expect(result.skill).toBe("react-patterns");
+    });
+
+    it("parses org/repo#skill@ref format", () => {
+        const result = parseSkillSpec("agentskillkit/agent-skills#react-patterns@v1.0.0");
+        expect(result.org).toBe("agentskillkit");
+        expect(result.repo).toBe("agent-skills");
+        expect(result.skill).toBe("react-patterns");
+        expect(result.ref).toBe("v1.0.0");
+    });
+
+    it("throws error for invalid spec", () => {
+        expect(() => parseSkillSpec("")).toThrow("Skill spec is required");
+        expect(() => parseSkillSpec("invalid")).toThrow("Invalid spec format");
+        expect(() => parseSkillSpec(null)).toThrow("Skill spec is required");
+    });
+});

package/bin/lib/skills.js

@@ -30,7 +30,10 @@ export function parseSkillMdFrontmatter(p) {
             else if (key && val) meta[key] = val;
         }
         return meta;
-    } catch { return {}; }
+    } catch (err) {
+        if (process.env.DEBUG) console.error(`parseSkillMdFrontmatter error: ${err.message}`);
+        return {};
+    }
 }
 
 /**
@@ -69,7 +72,9 @@ export function detectSkillStructure(dir) {
                 s.files.push(item);
             }
         }
-    } catch { }
+    } catch (err) {
+        if (process.env.DEBUG) console.error(`detectSkillStructure error: ${err.message}`);
+    }
     return s;
 }
 

package/bin/lib/skills.test.js

@@ -0,0 +1,109 @@
+/**
+ * @fileoverview Tests for skills.js
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import fs from "fs";
+import path from "path";
+import os from "os";
+import { parseSkillMdFrontmatter, detectSkillStructure } from "./skills.js";
+
+describe("parseSkillMdFrontmatter", () => {
+    let tempDir;
+    let skillMdPath;
+
+    beforeEach(() => {
+        tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "skill-test-"));
+        skillMdPath = path.join(tempDir, "SKILL.md");
+    });
+
+    afterEach(() => {
+        fs.rmSync(tempDir, { recursive: true, force: true });
+    });
+
+    it("parses valid frontmatter", () => {
+        const content = `---
+name: test-skill
+description: A test skill for testing
+version: 1.0.0
+author: Test Author
+tags: react, testing, patterns
+---
+
+# Test Skill
+
+Some content here.
+`;
+        fs.writeFileSync(skillMdPath, content);
+
+        const result = parseSkillMdFrontmatter(skillMdPath);
+
+        expect(result.name).toBe("test-skill");
+        expect(result.description).toBe("A test skill for testing");
+        expect(result.version).toBe("1.0.0");
+        expect(result.author).toBe("Test Author");
+        expect(result.tags).toEqual(["react", "testing", "patterns"]);
+    });
+
+    it("returns empty object for no frontmatter", () => {
+        fs.writeFileSync(skillMdPath, "# Just a heading\n\nNo frontmatter here.");
+
+        const result = parseSkillMdFrontmatter(skillMdPath);
+
+        expect(result).toEqual({});
+    });
+
+    it("returns empty object for non-existent file", () => {
+        const result = parseSkillMdFrontmatter("/non/existent/path/SKILL.md");
+        expect(result).toEqual({});
+    });
+});
+
+describe("detectSkillStructure", () => {
+    let tempDir;
+
+    beforeEach(() => {
+        tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "skill-structure-"));
+    });
+
+    afterEach(() => {
+        fs.rmSync(tempDir, { recursive: true, force: true });
+    });
+
+    it("detects standard directories", () => {
+        fs.mkdirSync(path.join(tempDir, "resources"));
+        fs.mkdirSync(path.join(tempDir, "examples"));
+        fs.mkdirSync(path.join(tempDir, "scripts"));
+        fs.writeFileSync(path.join(tempDir, "SKILL.md"), "# Skill");
+
+        const result = detectSkillStructure(tempDir);
+
+        expect(result.hasResources).toBe(true);
+        expect(result.hasExamples).toBe(true);
+        expect(result.hasScripts).toBe(true);
+        expect(result.directories).toContain("resources");
+        expect(result.directories).toContain("examples");
+        expect(result.directories).toContain("scripts");
+        expect(result.files).toContain("SKILL.md");
+    });
+
+    it("detects governance directories", () => {
+        fs.mkdirSync(path.join(tempDir, "constitution"));
+        fs.mkdirSync(path.join(tempDir, "doctrines"));
+        fs.mkdirSync(path.join(tempDir, "enforcement"));
+        fs.mkdirSync(path.join(tempDir, "proposals"));
+
+        const result = detectSkillStructure(tempDir);
+
+        expect(result.hasConstitution).toBe(true);
+        expect(result.hasDoctrines).toBe(true);
+        expect(result.hasEnforcement).toBe(true);
+        expect(result.hasProposals).toBe(true);
+    });
+
+    it("returns empty structure for non-existent dir", () => {
+        const result = detectSkillStructure("/non/existent/path");
+
+        expect(result.directories).toEqual([]);
+        expect(result.files).toEqual([]);
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "add-skill-kit",
-  "version": "1.1.0",
+  "version": "1.3.1",
   "description": "Enterprise-grade Agent Skill Manager with Antigravity Skills support, Progressive Disclosure detection, and semantic routing validation",
   "license": "MIT",
   "author": "agentskillkit <agentskillkit@gmail.com>",
@@ -38,9 +38,12 @@
     "antigravity"
   ],
   "scripts": {
-    "lint": "echo \"No lint configured\"",
-    "test": "echo \"No tests yet\"",
-    "ci": "node bin/cli.js verify --strict && node bin/cli.js doctor --strict"
+    "lint": "eslint bin/",
+    "lint:fix": "eslint bin/ --fix",
+    "format": "prettier --write bin/",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "ci": "npm run lint && npm test && node bin/cli.js verify --strict && node bin/cli.js doctor --strict"
   },
   "publishConfig": {
     "access": "public"
@@ -52,5 +55,10 @@
     "kleur": "^4.1.5",
     "ora": "^8.1.0",
     "prompts": "^2.4.2"
+  },
+  "devDependencies": {
+    "eslint": "^8.57.0",
+    "prettier": "^3.2.5",
+    "vitest": "^1.6.0"
   }
 }