@cg3/equip 0.8.0 → 0.9.1

package/README.md

@@ -1,99 +1,32 @@
 # @cg3/equip
 
-Universal MCP server + behavioral rules installer for AI coding agents.
+Cross-platform installer for MCP tools, behavioral rules, agent skills, and lifecycle hooks.
 
-[Join the Discord](https://discord.gg/bBcRHT4J) — bug reports, feedback, share what you're building.
+[Join the Discord](https://discord.gg/bBcRHT4J) | [Tool Author Guide](./docs/tool-author.md)
 
-Equip handles the hard part of distributing your MCP tool: detecting which AI coding platforms are installed, writing the correct config format for each one, and managing versioned behavioral rules — all with zero dependencies.
+## What It Does
 
-## Run the Demo
+You build an MCP tool. You want it to work on Claude Code, Cursor, VS Code, Windsurf, Cline, Roo Code, Codex, Gemini CLI, and more. Each platform has its own config format, file paths, root keys, URL fields, and quirks.
 
-```bash
-npx @cg3/equip demo
-```
+Equip handles all of that. One setup script, 11 platforms.
 
-A self-contained, inline-documented setup script that walks through every equip feature — platform detection, MCP config, behavioral rules, and uninstallation. Runs in dry-run mode by default (no files touched). See [`demo/setup.js`](./demo/setup.js) for the full source.
+## Install
 
 ```bash
-npx @cg3/equip demo --live        # actually write config files
-npx @cg3/equip demo --uninstall   # clean up demo files
+npm install -g @cg3/equip
 ```
 
-## Supported Platforms
-
-Equip supports **11 platforms** across two tiers, depending on whether the platform has a writable location for behavioral rules.
-
-### Full Support — MCP + Behavioral Rules
-
-These platforms get both MCP server config *and* auto-installed behavioral rules. Rules teach agents *when* to use your tool (e.g., "search before debugging") and are versioned for idempotent updates.
-
-| Platform | MCP Config | Rules |
-|---|---|---|
-| Claude Code | `~/.claude.json` (JSON, `mcpServers`) | `~/.claude/CLAUDE.md` (append) |
-| Windsurf | `~/.codeium/windsurf/mcp_config.json` (JSON, `mcpServers`, `serverUrl`) | `~/.codeium/windsurf/memories/global_rules.md` (append) |
-| Cline | `globalStorage/.../cline_mcp_settings.json` (JSON, `mcpServers`) | `~/Documents/Cline/Rules/` (standalone file) |
-| Roo Code | `globalStorage/.../cline_mcp_settings.json` (JSON, `mcpServers`) | `~/.roo/rules/` (standalone file) |
-| Codex | `~/.codex/config.toml` (TOML, `mcp_servers`) | `~/.codex/AGENTS.md` (append) |
-| Gemini CLI | `~/.gemini/settings.json` (JSON, `mcpServers`, `httpUrl`) | `~/.gemini/GEMINI.md` (append) |
-
-### MCP Only — No Writable Rules Path
-
-These platforms get MCP server config but don't have a writable global rules file (`rulesPath: null`). The MCP tools work fine — but equip can't auto-install behavioral rules.
-
-| Platform | MCP Config |
-|---|---|
-| Cursor | `~/.cursor/mcp.json` (JSON, `mcpServers`, `type: "streamable-http"`) |
-| VS Code | `Code/User/mcp.json` (JSON, `servers`, `type: "http"`) |
-| Junie (JetBrains) | `~/.junie/mcp/mcp.json` (JSON, `mcpServers`) |
-| Copilot (JetBrains) | `~/.config/github-copilot/intellij/mcp.json` (JSON, `mcpServers`) |
-| Copilot CLI | `~/.copilot/mcp-config.json` (JSON, `mcpServers`) |
-
-For these platforms, `installRules()` returns `{ action: "clipboard" }` if the platform is in the configurable `clipboardPlatforms` list (default: `["cursor", "vscode"]`) and automatically copies the rules content to the system clipboard. For platforms with no rules path and not in `clipboardPlatforms`, it returns `{ action: "skipped" }`.
-
-### Hooks — Structural Enforcement
-
-Some platforms support **lifecycle hooks** — scripts that run automatically at key moments (e.g., after a tool fails, when the agent finishes responding). Hooks provide structural enforcement that behavioral rules alone cannot:
-
-| Platform | Hooks Support | Events |
-|---|---|---|
-| Claude Code | ✅ | `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `Stop`, `SessionStart`, `SessionEnd`, `UserPromptSubmit`, `Notification`, `SubagentStart`, `SubagentStop`, `PreCompact`, `TaskCompleted` |
-| All others | ❌ | — |
-
-When hooks are supported, equip writes the consumer-provided scripts to a configurable directory (default: `~/.${name}/hooks/`) and registers them in the platform's settings. Hooks are a **silent enhancement** — if the platform doesn't support them, equip installs only MCP + rules without any error or warning.
-
-Hook scripts and event bindings are defined by the consumer (your package), not by equip. Equip provides only the installation infrastructure — capabilities detection, file writing, settings registration, and cleanup. As more platforms add hook support, equip can enable them without consumer code changes.
-
 ## Quick Start
 
 ```bash
-npx @cg3/equip prior
-```
-
-That's it. Detects your platforms, authenticates, installs MCP + rules, and verifies — all in one command. Pass `--dry-run` to preview without writing files.
-
-## CLI Usage
-
-You can invoke any npm package that has an equip-based setup command:
-
-```bash
-# Full package name + command
-npx @cg3/equip @cg3/prior-node setup
-
-# Shorthand (if registered)
-npx @cg3/equip prior
+equip prior                    # Install a tool
+equip status                   # See what's installed across all platforms
+equip doctor                   # Validate config integrity
+equip update                   # Update equip + migrate configs
+unequip prior                  # Remove a tool
 ```
 
-The CLI runs `npx -y <package>@latest <command>` with any extra args forwarded (e.g. `--dry-run`, `--platform codex`).
-
-### Shorthand Registry
-
-Registered shorthands save typing. Open a PR to [`registry.json`](./registry.json) to add yours:
-
-| Shorthand | Expands to |
-|---|---|
-| `prior` | `@cg3/prior-node setup` |
-
-## Programmatic Usage
+## For Tool Authors
 
 ```js
 const { Equip } = require("@cg3/equip");
@@ -105,103 +38,106 @@ const equip = new Equip({
     content: `<!-- my-tool:v1.0.0 -->\n## My Tool\nAlways check My Tool first.\n<!-- /my-tool -->`,
     version: "1.0.0",
     marker: "my-tool",
-    fileName: "my-tool.md",  // For platforms with rules directories
+  },
+  skill: {
+    name: "lookup",
+    files: [{ path: "SKILL.md", content: "---\nname: lookup\ndescription: Look up docs\n---\n\n# Lookup\n" }],
   },
 });
 
-// Detect installed platforms
 const platforms = equip.detect();
-
-// Install MCP + rules on all detected platforms
 for (const p of platforms) {
   equip.installMcp(p, "api_key_here");
   equip.installRules(p);
-}
-
-// Uninstall
-for (const p of platforms) {
-  equip.uninstallMcp(p);
-  equip.uninstallRules(p);
+  equip.installSkill(p);
 }
 ```
 
-## API
-
-### `new Equip(config)`
-
-- `config.name` — Server name in MCP configs (required)
-- `config.serverUrl` — Remote MCP server URL (required unless `stdio` provided)
-- `config.rules` — Behavioral rules config (optional)
-  - `content` — Markdown content with version markers
-  - `version` — Version string for idempotency tracking
-  - `marker` — Marker name used in `<!-- marker:vX.X -->` comments
-  - `fileName` — Standalone filename for directory-based platforms
-  - `clipboardPlatforms` — Platform IDs that use clipboard (default: `["cursor", "vscode"]`)
-- `config.stdio` — Stdio transport config (optional, alternative to HTTP)
-  - `command`, `args`, `envKey`
-- `config.hooks` — Lifecycle hook definitions (optional, array)
-  - `event` — Hook event name (e.g., `"PostToolUseFailure"`)
-  - `matcher` — Regex matcher for event filtering (optional, e.g., `"Bash"`)
-  - `script` — Hook script content (Node.js)
-  - `name` — Script filename (without `.js` extension)
-- `config.hookDir` — Directory for hook scripts (default: `~/.${name}/hooks/`)
-
-### Instance Methods
-
-- `equip.detect()` — Returns array of detected platform objects
-- `equip.installMcp(platform, apiKey, options?)` — Install MCP config
-- `equip.uninstallMcp(platform, dryRun?)` — Remove MCP config
-- `equip.updateMcpKey(platform, apiKey, transport?)` — Update API key
-- `equip.installRules(platform, options?)` — Install behavioral rules
-- `equip.uninstallRules(platform, dryRun?)` — Remove behavioral rules
-- `equip.readMcp(platform)` — Check if MCP is configured
-- `equip.buildConfig(platformId, apiKey, transport?)` — Build MCP config object
-- `equip.installHooks(platform, options?)` — Install lifecycle hooks (if supported)
-- `equip.uninstallHooks(platform, options?)` — Remove hooks
-- `equip.hasHooks(platform, options?)` — Check if hooks are installed
-- `equip.supportsHooks(platform)` — Check if platform supports hooks
-
-### Utilities
+See the [Tool Author Guide](./docs/tool-author.md) for the complete walkthrough, or run `equip demo` for an interactive example.
 
-```js
-const { createManualPlatform, platformName, resolvePlatformId, parseRulesVersion, markerPatterns, cli, KNOWN_PLATFORMS, PLATFORM_REGISTRY, getPlatform } = require("@cg3/equip");
-```
+## The Four Layers
 
-- `createManualPlatform(id)` — Create a platform object for a specific platform ID (bypasses detection)
-- `platformName(id)` — Human-readable display name for a platform ID
-- `resolvePlatformId(input)` — Resolve a friendly name or alias to a canonical platform ID (e.g., `"claude"` → `"claude-code"`, `"roo"` → `"roo-code"`)
-- `parseRulesVersion(content, marker)` — Extract version from a marker block in content
-- `markerPatterns(marker)` — Get regex patterns for a marker name
-- `KNOWN_PLATFORMS` — Array of all supported platform IDs
-- `PLATFORM_REGISTRY` — Map of platform definitions (for advanced use)
-- `getPlatform(id)` — Get a platform definition by ID (throws if unknown)
-- `cli` — Output helpers: `log`, `ok`, `fail`, `warn`, `info`, `step`, `prompt`, `copyToClipboard`, color constants
+Equip distributes your tool through four complementary layers:
 
-## Key Features
+| Layer | What It Does | Reliability | Coverage |
+|---|---|---|---|
+| [MCP Config](./docs/mcp-servers.md) | Makes the tool *available* — agent can call it | Baseline | 11 platforms |
+| [Behavioral Rules](./docs/rules.md) | Teaches the agent *when* to call it | Strong | 8 platforms + clipboard |
+| [Agent Skills](./docs/skills.md) | Gives the agent *detailed knowledge* of how to use it | Strong (varies) | 8 platforms |
+| [Lifecycle Hooks](./docs/hooks.md) | *Structurally enforces* behavior at key moments | Strongest | 1 platform (Claude Code) |
 
-- **Zero dependencies** — Pure Node.js, works with Node 18+
-- **11 platforms** — Covers ~80% of active AI coding tool users
-- **Platform-aware** — Handles each platform's config quirks (JSON vs TOML, root keys, URL fields, type requirements)
-- **Non-destructive** — Merges into existing configs, creates backups, preserves other servers
-- **Versioned rules** — Marker-based blocks enable idempotent updates without clobbering user content
-- **Dry-run support** — Preview changes without writing files
-- **CLI helpers** — Colored output, prompts, clipboard utilities included
+Each layer compensates for the limitations of the one before it. Tool descriptions alone don't reliably trigger behavior. Rules are stronger but can be compacted. Skills add depth but may not auto-invoke on all platforms. Hooks fire automatically, independent of the agent's memory.
 
-## How the Layers Work Together
+No layer is a silver bullet. Together, they give you the best coverage available.
 
-Equip distributes your MCP tool through three complementary layers, each stronger than the last:
+## Supported Platforms
 
-1. **MCP config** — Makes the tool available. The agent *can* call it.
-2. **Behavioral rules** — Teaches the agent *when* to call it. Rules live in the agent's system prompt or project context, close to where decisions happen.
-3. **Lifecycle hooks** — Structurally enforces behavior at key moments (e.g., after an error, on task completion). Hooks inject context into the agent's reasoning at exactly the right time, without relying on the agent remembering its rules.
+| Platform | MCP | Rules | Skills | Hooks |
+|---|---|---|---|---|
+| Claude Code | Yes | Yes | Yes | Yes |
+| Cursor | Yes | clipboard | Yes | -- |
+| VS Code / Copilot | Yes | clipboard | Yes | -- |
+| Windsurf | Yes | Yes | Yes | -- |
+| Cline | Yes | Yes | Yes | -- |
+| Roo Code | Yes | Yes | Yes | -- |
+| Codex | Yes | Yes | Yes | -- |
+| Gemini CLI | Yes | Yes | Yes | -- |
+| Junie | Yes | -- | -- | -- |
+| Copilot (JetBrains) | Yes | -- | -- | -- |
+| Copilot CLI | Yes | -- | -- | -- |
+
+See [Platforms](./docs/platforms.md) for full details — config paths, detection, and per-platform quirks.
+
+## CLI Commands
+
+| Command | Description |
+|---|---|
+| `equip <tool>` | Install an MCP tool |
+| `equip status` | Cross-platform MCP server inventory |
+| `equip doctor` | Validate config integrity, detect drift |
+| `equip update` | Update equip and migrate configs |
+| `equip list` | Show registered tools |
+| `equip uninstall <tool>` | Remove a tool (alias: `unequip`) |
+| `equip demo` | Run the interactive demo |
 
-Each layer compensates for the limitations of the one before it:
+See [CLI Reference](./docs/cli.md) for details.
 
-- **Tool descriptions alone** don't reliably trigger behavior. [Research on 856 MCP tools](https://arxiv.org/abs/2602.14878) found that even fully optimized descriptions only improve task success by ~6 percentage points.
-- **Behavioral rules** are stronger, but can be dropped during context window compaction in long sessions, and the agent can still rationalize skipping them.
-- **Lifecycle hooks** are the strongest available enforcement — they fire automatically at the platform level, independent of the agent's memory or reasoning. Not all platforms support hooks yet, but equip installs them where available and silently skips where not.
+## Documentation
 
-No layer is a silver bullet. Together, they give you the best coverage available today across the broadest set of platforms.
+| Guide | Audience |
+|---|---|
+| [Tool Author Guide](./docs/tool-author.md) | Building a setup script with equip |
+| [Platforms](./docs/platforms.md) | Supported platforms, capabilities, paths |
+| [MCP Servers](./docs/mcp-servers.md) | Config format translation, API reference |
+| [Behavioral Rules](./docs/rules.md) | Marker-based versioned instructions |
+| [Agent Skills](./docs/skills.md) | SKILL.md format, cross-platform distribution |
+| [Lifecycle Hooks](./docs/hooks.md) | Event-driven enforcement scripts |
+| [CLI Reference](./docs/cli.md) | Commands, state tracking, tool registry |
+
+## Key Design Decisions
+
+- **Zero runtime dependencies** — installs fast, no supply chain risk
+- **Platform registry as single source of truth** — one place for all platform knowledge
+- **Atomic file writes** — crash-safe config modifications
+- **State reconciliation from disk** — CLI scans what's actually installed, no stale cache
+- **Corrupt config detection** — throws instead of silently overwriting
+
+## Tool Registry
+
+Register a shorthand for your tool so users can run `equip <name>`. Open a PR to [`registry.json`](./registry.json):
+
+```json
+{
+  "my-tool": {
+    "package": "@myorg/my-tool",
+    "command": "setup",
+    "description": "What my tool does",
+    "marker": "my-tool",
+    "hookDir": "~/.my-tool/hooks",
+    "skillName": "my-skill"
+  }
+}
+```
 
 ## License
 

package/bin/equip.js

@@ -60,6 +60,8 @@ function cmdHelp() {
   console.log("");
   console.log("Commands:");
   console.log("  <tool>           Install an MCP tool (e.g. equip prior)");
+  console.log("  ./script.js      Run a local setup script (for development)");
+  console.log("  .                Run current directory's package bin entry");
   console.log("  uninstall <tool> Remove an installed tool (alias: unequip)");
   console.log("  status           Show all MCP servers across all platforms");
   console.log("  doctor           Validate config integrity and detect drift");
@@ -137,7 +139,20 @@ function cmdUpdate() {
 
 // ─── Tool Dispatch ──────────────────────────────────────────
 
+function isLocalPath(arg) {
+  return arg.startsWith("./") || arg.startsWith("../") || arg.startsWith("/")
+    || arg.startsWith(".\\") || arg.startsWith("..\\")
+    || arg === "."
+    || arg.endsWith(".js");
+}
+
 function dispatchTool(alias, extraArgs) {
+  // Local path: run directly with node
+  if (isLocalPath(alias)) {
+    runLocal(alias, extraArgs);
+    return;
+  }
+
   const entry = TOOLS[alias];
 
   if (!entry) {
@@ -157,6 +172,75 @@ function dispatchTool(alias, extraArgs) {
   spawnTool(entry.package, entry.command, extraArgs, alias);
 }
 
+/**
+ * Run a local script or package directory.
+ * - equip ./piratehat.js       → node ./piratehat.js
+ * - equip .                    → reads package.json bin, runs it
+ * - equip ../my-tool/setup.js  → node ../my-tool/setup.js
+ */
+function runLocal(localPath, extraArgs) {
+  const _path = require("path");
+  const _fs = require("fs");
+  let scriptPath;
+  let toolName = null;
+
+  if (localPath === "." || (_fs.existsSync(localPath) && _fs.statSync(localPath).isDirectory())) {
+    // Directory — look for package.json with bin field
+    const pkgPath = _path.join(localPath, "package.json");
+    if (!_fs.existsSync(pkgPath)) {
+      console.error(`No package.json found in ${localPath}`);
+      process.exit(1);
+    }
+    const pkg = JSON.parse(_fs.readFileSync(pkgPath, "utf-8"));
+    toolName = pkg.name?.replace(/^@[^/]+\//, "") || null;
+    const binEntries = pkg.bin;
+    if (!binEntries || typeof binEntries !== "object") {
+      console.error(`No bin field in ${pkgPath}`);
+      process.exit(1);
+    }
+    // Use the first bin entry
+    const binScript = Object.values(binEntries)[0];
+    scriptPath = _path.resolve(localPath, binScript);
+  } else {
+    // Direct script path
+    scriptPath = _path.resolve(localPath);
+    // Infer tool name from filename (piratehat.js → piratehat)
+    toolName = _path.basename(scriptPath, ".js");
+  }
+
+  if (!_fs.existsSync(scriptPath)) {
+    console.error(`Script not found: ${scriptPath}`);
+    process.exit(1);
+  }
+
+  const child = spawn(process.execPath, [scriptPath, ...extraArgs], {
+    stdio: "inherit",
+    env: { ...process.env, EQUIP_VERSION },
+  });
+  child.on("close", (code) => {
+    if (toolName) {
+      try {
+        const { reconcileState } = require("../dist/lib/reconcile");
+        const changed = reconcileState({
+          toolName,
+          package: toolName,
+          marker: toolName,
+        });
+        if (changed > 0) {
+          process.stderr.write(`\n  equip: tracked ${toolName} on ${changed} platform${changed === 1 ? "" : "s"}\n`);
+        }
+      } catch (e) {
+        process.stderr.write(`\n[equip] state reconciliation failed: ${e.message}\n`);
+      }
+    }
+    process.exit(code || 0);
+  });
+  child.on("error", (err) => {
+    console.error(`Failed to run ${scriptPath}: ${err.message}`);
+    process.exit(1);
+  });
+}
+
 function spawnTool(pkg, command, extraArgs, toolName) {
   const npxCmd = process.platform === "win32" ? "npx.cmd" : "npx";
   const child = spawn(npxCmd, ["-y", `${pkg}@latest`, command, ...extraArgs], {

package/demo/setup.js

@@ -14,9 +14,10 @@
 //   1. Platform detection (which AI tools are installed?)
 //   2. MCP server configuration (HTTP or stdio transport)
 //   3. Behavioral rules installation (versioned, marker-based)
-//   4. Lifecycle hooks (optional, platform-dependent)
-//   5. Uninstallation (clean removal of everything it installed)
-//   6. CLI output helpers (colors, prompts, clipboard)
+//   4. Skills installation (SKILL.md files for agent discovery)
+//   5. Lifecycle hooks (optional, platform-dependent)
+//   6. Uninstallation (clean removal of everything it installed)
+//   7. CLI output helpers (colors, prompts, clipboard)
 //
 // Everything is inline-documented. Copy this file as a starting
 // point for your own tool's setup script.
@@ -120,6 +121,40 @@ const equip = new Equip({
   //     `,
   //   },
   // ],
+
+  // Skills are optional. A skill is a SKILL.md file (Agent Skills
+  // spec) that agents auto-discover. Unlike MCP config and rules,
+  // the skill format is universal — same file works on all platforms.
+  skill: {
+    name: "lookup",
+    files: [
+      {
+        path: "SKILL.md",
+        content: `---
+name: lookup
+description: Look up Acme API docs for the current project's dependency version.
+metadata:
+  author: acme-docs-demo
+  version: "${RULES_VERSION}"
+---
+
+# Acme Docs Lookup
+
+Use this skill when working with Acme APIs or libraries.
+
+## When to Use
+- Before writing code that calls an Acme API
+- When you see a deprecation warning from Acme
+- When the user asks about Acme API signatures
+
+## How to Use
+1. Call the acme-docs MCP tool with the function name
+2. The tool returns versioned docs matching the project's dependency
+3. Use the returned signatures, not training data
+`,
+      },
+    ],
+  },
 });
 
 // ─── 5. Detect platforms (shared by install and uninstall) ───
@@ -155,7 +190,7 @@ function detectTargetPlatforms() {
 async function runUninstall() {
   cli.log(`\n${cli.BOLD}@cg3/equip demo — uninstall${cli.RESET}\n`);
 
-  cli.step(1, 3, "Detecting platforms");
+  cli.step(1, 4, "Detecting platforms");
   const platforms = detectTargetPlatforms();
 
   for (const p of platforms) {
@@ -163,7 +198,7 @@ async function runUninstall() {
   }
 
   // ── Remove MCP config ────────────────────────────────────
-  cli.step(2, 3, "Removing MCP config");
+  cli.step(2, 4, "Removing MCP config");
 
   for (const p of platforms) {
     const removed = equip.uninstallMcp(p);
@@ -175,7 +210,7 @@ async function runUninstall() {
   }
 
   // ── Remove behavioral rules ──────────────────────────────
-  cli.step(3, 3, "Removing behavioral rules");
+  cli.step(3, 4, "Removing behavioral rules");
 
   for (const p of platforms) {
     const removed = equip.uninstallRules(p);
@@ -186,6 +221,18 @@ async function runUninstall() {
     }
   }
 
+  // ── Remove skills ──────────────────────────────────────
+  cli.step(4, 4, "Removing skills");
+
+  for (const p of platforms) {
+    const removed = equip.uninstallSkill(p);
+    if (removed) {
+      cli.ok(`${platformName(p.platform)} → skill removed`);
+    } else {
+      cli.info(`${platformName(p.platform)} → no skill found`);
+    }
+  }
+
   cli.log(`\n${cli.GREEN}${cli.BOLD}✓ Uninstall complete${cli.RESET}`);
   cli.log(`  Demo config for "${TOOL_NAME}" has been cleaned up.\n`);
 }
@@ -215,7 +262,7 @@ async function runInstall() {
   //
   // You can also force a specific platform with createManualPlatform().
 
-  cli.step(1, 4, "Detecting platforms");
+  cli.step(1, 5, "Detecting platforms");
 
   const platforms = detectTargetPlatforms();
 
@@ -229,7 +276,7 @@ async function runInstall() {
   // In a real setup script, you'd prompt for or generate an
   // API key here. For the demo, we use a placeholder.
 
-  cli.step(2, 4, "API key");
+  cli.step(2, 5, "API key");
 
   // Real example:
   // const apiKey = await cli.prompt("  Enter your API key: ");
@@ -243,11 +290,11 @@ async function runInstall() {
   // installMcp() handles all platform differences:
   //   - JSON vs TOML config formats
   //   - Different root keys (mcpServers vs servers vs mcp_servers)
-  //   - CLI-first installation (claude mcp add, cursor --add-mcp)
-  //   - Fallback to direct file write with backup
+  //   - Different URL fields (url vs serverUrl vs httpUrl)
+  //   - Atomic file writes with crash safety
   //   - Windows path handling (cmd /c wrapper for stdio)
 
-  cli.step(3, 4, "Installing MCP config");
+  cli.step(3, 5, "Installing MCP config");
 
   for (const p of platforms) {
     const result = equip.installMcp(p, apiKey, { dryRun });
@@ -272,7 +319,7 @@ async function runInstall() {
   // Platforms without a rules file (Cursor, VS Code) get the
   // content copied to clipboard instead.
 
-  cli.step(4, 4, "Installing behavioral rules");
+  cli.step(4, 5, "Installing behavioral rules");
 
   for (const p of platforms) {
     const result = equip.installRules(p, { dryRun });
@@ -300,6 +347,32 @@ async function runInstall() {
     }
   }
 
+  // ── Step 5: Install skills ──────────────────────────────
+  //
+  // Skills are SKILL.md files (Agent Skills spec) that agents
+  // auto-discover from standard directories. Unlike MCP config,
+  // the skill format is universal — same file works on all
+  // platforms. Equip installs to each platform's native skill
+  // directory, or ~/.agents/skills/ for platforms without one.
+
+  cli.step(5, 5, "Installing skills");
+
+  for (const p of platforms) {
+    const result = equip.installSkill(p, { dryRun });
+    switch (result.action) {
+      case "created":
+        cli.ok(`${platformName(p.platform)} → skill installed`);
+        break;
+      case "skipped":
+        if (p.skillsPath) {
+          cli.info(`${platformName(p.platform)} → skill already current`);
+        } else {
+          cli.info(`${platformName(p.platform)} → no skills support`);
+        }
+        break;
+    }
+  }
+
   // ── Done ──────────────────────────────────────────────────
 
   cli.log(`\n${cli.GREEN}${cli.BOLD}✓ Setup complete${cli.RESET}`);

package/dist/index.d.ts

@@ -2,6 +2,7 @@ import { parseRulesVersion, markerPatterns } from "./lib/rules";
 import { type HookDefinition } from "./lib/hooks";
 import { createManualPlatform, platformName, resolvePlatformId, KNOWN_PLATFORMS, PLATFORM_REGISTRY, getPlatform, type DetectedPlatform, type PlatformDefinition, type PlatformHttpShape, type PlatformHookCapabilities } from "./lib/platforms";
 import * as cli from "./lib/cli";
+import { type SkillConfig, type SkillFile } from "./lib/skills";
 export interface EquipConfig {
     name: string;
     serverUrl?: string;
@@ -19,6 +20,7 @@ export interface EquipConfig {
     };
     hooks?: HookDefinition[];
     hookDir?: string;
+    skill?: SkillConfig;
 }
 /**
  * Equip — configure AI coding tools with your MCP server and behavioral rules.
@@ -30,6 +32,7 @@ declare class Equip {
     stdio: EquipConfig["stdio"] | null;
     hookDefs: HookDefinition[] | null;
     hookDir: string;
+    skill: SkillConfig | null;
     constructor(config: EquipConfig);
     detect(): DetectedPlatform[];
     buildConfig(platformId: string, apiKey: string, transport?: string): Record<string, unknown>;
@@ -68,6 +71,13 @@ declare class Equip {
         hookDir?: string;
     }): boolean;
     supportsHooks(platform: DetectedPlatform): boolean;
+    installSkill(platform: DetectedPlatform, options?: {
+        dryRun?: boolean;
+    }): {
+        action: string;
+    };
+    uninstallSkill(platform: DetectedPlatform, dryRun?: boolean): boolean;
+    hasSkill(platform: DetectedPlatform): boolean;
     /**
      * Verify that a tool is correctly installed on a platform.
      * Returns a structured result with per-check status.
@@ -85,5 +95,5 @@ export interface VerifyResult {
     checks: VerifyCheck[];
 }
 export { Equip, createManualPlatform, platformName, resolvePlatformId, KNOWN_PLATFORMS, PLATFORM_REGISTRY, getPlatform, parseRulesVersion, markerPatterns, cli, };
-export type { DetectedPlatform, PlatformDefinition, PlatformHttpShape, PlatformHookCapabilities, HookDefinition };
+export type { DetectedPlatform, PlatformDefinition, PlatformHttpShape, PlatformHookCapabilities, HookDefinition, SkillConfig, SkillFile };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}