add-skill-kit 1.0.3 → 1.3.0

package/README.md

@@ -1,194 +1,204 @@
-<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>
+# add-skill-kit
 
----
+> **The package manager for AI Agent Skills**
+
+[![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)
 
-## 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.
+## Quick Install
 
 ```bash
 npx -y 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
+Or install globally:
 
 ```bash
-# Using npm
 npm install -g add-skill-kit
+add-skill-kit agentskillkit/agent-skills
+```
 
-# Using pnpm
-pnpm add -g add-skill-kit
+This installs the `.agent` folder containing all templates into your project.
 
-# Using Yarn
-yarn global add add-skill-kit
+---
 
-# Or run directly with npx (use -y to skip install prompt)
-npx -y add-skill-kit <command>
-```
+## What's Included
 
-> **Requirements:** Node.js 18.0.0 or later
+| 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 |
 
 ---
 
-## Quick Start
+## Usage
 
-### 1. Initialize your workspace
+### Using Agents
+
+**No need to mention agents explicitly!** The system automatically detects and applies the right specialist(s):
 
-```bash
-npx -y add-skill-kit init
 ```
+You: "Add JWT authentication"
+AI: 🤖 Applying @security-auditor + @backend-specialist...
 
-This creates the `.agent/skills` directory structure in your project.
+You: "Fix the dark mode button"
+AI: 🤖 Using @frontend-specialist...
 
-### 2. Install a skill
+You: "Login returns 500 error"
+AI: 🤖 Using @debugger for systematic analysis...
+```
 
-Install from GitHub with optional version pinning:
+**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
 
-```bash
-# Latest version
-npx -y add-skill-kit agentskillkit/agent-skills
+**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
 
-# Specific skill
-npx -y add-skill-kit agentskillkit/agent-skills#react-patterns
+---
 
-# Specific version
-npx -y add-skill-kit agentskillkit/agent-skills#react-patterns@v1.0.0
-```
+### Using Workflows
 
-### 3. List installed skills
+Invoke workflows with slash commands:
 
-```bash
-npx -y add-skill-kit list
+| 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:**
 ```
-
-### 4. Validate compliance
-
-```bash
-npx -y add-skill-kit validate
+/brainstorm authentication system
+/create landing page with hero section
+/debug why login fails
 ```
 
 ---
 
-## Commands
+### Using Skills
 
-| 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 |
+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 | |
 
 ---
 
-## Features
+## CLI Commands
 
-### Progressive Disclosure
+```bash
+# Install skills from repository
+npx -y add-skill-kit <org/repo>
 
-Skills follow a structured hierarchy that lets agents read only what they need:
+# Install specific skill
+npx -y add-skill-kit <org/repo>#skill-name
 
-```
-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
+# List installed skills
+npx -y add-skill-kit list
+
+# Validate skill integrity
+npx -y add-skill-kit validate
+
+# Check workspace health
+npx -y add-skill-kit doctor
 ```
 
-### Deterministic Locking
+---
 
-Pin exact versions for reproducible builds across your team:
+## How It Works
 
-```bash
-# Generate lockfile
-npx -y add-skill-kit lock
+Skills are **data, not code**. They never execute on your system.
 
-# Install from lockfile
-npx -y add-skill-kit install --locked
 ```
+┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
+│  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`
+
+---
 
-### Security by Design
+## Project Structure After Install
 
-| 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` |
+```
+your-project/
+└── .agent/
+    ├── skills/           # 40+ domain skills
+    │   ├── react-patterns/
+    │   ├── api-patterns/
+    │   ├── testing-patterns/
+    │   └── ...
+    ├── workflows/        # Slash commands
+    │   ├── brainstorm.md
+    │   ├── debug.md
+    │   └── ...
+    └── GEMINI.md         # Agent configuration
+```
 
 ---
 
-## Documentation
+## Supported Agents
 
-<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>
+| Agent | Status |
+|-------|--------|
+| **Antigravity** | ✅ Ready |
+| Claude Code | 🔜 Coming |
+| Gemini CLI | 🔜 Coming |
+| Codex | 🔜 Coming |
 
 ---
 
-## Community
+## Requirements
+
+- Node.js 18+
 
-We welcome contributions! See our [Contributing Guide](https://github.com/agentskillkit/add-skill-kit/blob/main/CONTRIBUTING.md) to get started.
+---
+
+## Documentation
 
-<a href="https://github.com/agentskillkit/add-skill-kit/graphs/contributors">
-  <img src="https://contrib.rocks/image?repo=agentskillkit/add-skill-kit" />
-</a>
+- [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 with ❤️ 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">License</a>
-</p>
+MIT © [Agent Skill Kit](https://github.com/agentskillkit)

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

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "add-skill-kit",
-  "version": "1.0.3",
+  "version": "1.3.0",
   "description": "Enterprise-grade Agent Skill Manager with Antigravity Skills support, Progressive Disclosure detection, and semantic routing validation",
   "license": "MIT",
   "author": "agentskillkit <agentskillkit@gmail.com>",