add-skill-kit 1.1.0 → 1.3.0

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/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.1.0",
+  "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>",