skillrepo 2.0.0 → 3.0.0

package/README.md

@@ -1,214 +1,279 @@
 # skillrepo
 
-Set up SkillRepo in any IDE -- one command.
+A pull-based CLI for managing your agent-skills library from the terminal.
 
 ```
 npx skillrepo init
 ```
 
-Auto-detects your IDEs, validates your access key, and writes the correct MCP
-configuration for each one. Safe to run multiple times.
+Validates your access key, auto-detects your IDEs, wires up the MCP config,
+and pulls your library. Safe to re-run at any time.
 
-## Quick Start
-
-1. **Create an access key** at [skillrepo.dev/app/settings](https://skillrepo.dev/app/settings) (Settings > Access Keys).
-2. **Run the CLI** in your project directory:
-   ```
-   npx skillrepo init
-   ```
-3. **Done.** Your IDE can now discover and activate skills from your SkillRepo library.
-
-## Usage
-
-```
-npx skillrepo init [options]
-```
-
-### Options
-
-| Flag | Short | Description |
-|------|-------|-------------|
-| `--key <key>` | `-k` | Access key. If omitted, the CLI reads `SKILLREPO_ACCESS_KEY` from the environment, then prompts interactively. |
-| `--url <url>` | `-u` | SkillRepo server URL. Defaults to `https://skillrepo.dev`. Use this for self-hosted instances. |
-| `--yes` | `-y` | Non-interactive mode. Skips confirmation prompts. Useful for CI or scripted setups. |
-
-### Examples
+## Install
 
 ```sh
-# Interactive setup (prompts for key and confirms detected IDEs)
-npx skillrepo init
-
-# Pass the key directly
-npx skillrepo init --key sk_live_abc123
+# One-off via npx (recommended)
+npx skillrepo <command>
 
-# Self-hosted instance, non-interactive
-npx skillrepo init --url https://skillrepo.internal.company.com --yes
-
-# Key from environment variable
-export SKILLREPO_ACCESS_KEY=sk_live_abc123
-npx skillrepo init --yes
+# Or install globally
+npm install -g skillrepo
+skillrepo <command>
 ```
 
-## What It Does
-
-The CLI performs four steps:
+Requires Node.js 18 or later.
 
-1. **Detects installed IDEs** by checking for IDE-specific directories in the
-   current project (`.claude/`, `.cursor/`, `.vscode/`) and global paths
-   (`~/.codeium/windsurf/`). If no IDE is detected, it defaults to Claude Code
-   and Cursor.
+## Quick start
 
-2. **Validates the access key** against the SkillRepo API and fetches the
-   current skill mapping data for your library.
-
-3. **Writes MCP configuration files** for each detected IDE, using the correct
-   format and environment variable syntax for that IDE.
-
-4. **Writes skill mapping files** that let agents match user requests to the
-   right skill without a network round-trip. For Claude Code, it also installs a
-   SessionStart hook that auto-refreshes the mapping on each session start.
-
-### Files Created or Modified
+1. **Create an access key** at [skillrepo.dev/app/settings](https://skillrepo.dev/app/settings)
+   (Settings → Access Keys).
+2. **Run `init`** inside your project directory:
+   ```sh
+   npx skillrepo init
+   ```
+3. **Your library is now on disk.** The CLI wrote skills into
+   `.claude/skills/` (project) and registered the MCP server with every IDE
+   it detected (`.claude/`, `.cursor/`, `.vscode/`, `~/.codeium/windsurf/`).
+4. **From now on**, use `skillrepo update` to pull new versions,
+   `skillrepo add` to add skills to your library, and `skillrepo list` to
+   see what you have.
 
-| File | IDE | Purpose |
-|------|-----|---------|
-| `.mcp.json` | Claude Code | MCP server connection config |
-| `.claude/skillrepo.md` | Claude Code | Skill-to-tool mapping |
-| `.cursor/mcp.json` | Cursor | MCP server connection config |
-| `.cursor/rules/skillrepo.mdc` | Cursor | Skill-to-tool mapping |
-| `~/.codeium/windsurf/mcp_config.json` | Windsurf | MCP server connection config (global) |
-| `.vscode/mcp.json` | VS Code + Copilot | MCP server connection config |
-| `.env.local` | All | Stores `SKILLREPO_ACCESS_KEY` (gitignored) |
+## Commands
 
-All writes are merge-safe. The CLI reads existing files, adds or updates only
-the `skillrepo` entry, and leaves all other entries untouched. Running `init`
-again with a new key updates the key in `.env.local` without affecting anything
-else.
+### `init` — first-run setup
 
-## IDE-Specific Details
+Validates your access key, detects installed IDEs, writes the MCP config,
+and runs the first library sync.
 
-### Claude Code
+```sh
+skillrepo init [--key <key>] [--url <url>] [--yes] [--force] [--ide <list>] [--global] [--json]
+```
 
-- Config file: `.mcp.json` with `mcpServers.skillrepo` entry
-- Uses `${SKILLREPO_ACCESS_KEY}` syntax for environment variable expansion
-- Includes `"type": "http"` in the server entry
-- Installs a SessionStart hook that refreshes the skill mapping file
-  (`.claude/skillrepo.md`) automatically on every session start
-- Skill mappings are always current without manual intervention
+| Flag | Description |
+|------|-------------|
+| `--key, -k <key>` | Access key. Falls back to `SKILLREPO_ACCESS_KEY` env var, then interactive prompt. |
+| `--url, -u <url>` | Server URL. Defaults to `https://skillrepo.dev`. Use for self-hosted. |
+| `--yes, -y` | Non-interactive. Skip all confirmation prompts. Required for CI. |
+| `--force` | Re-prompt for a new key even if `~/.claude/skillrepo/config.json` is valid. |
+| `--ide <list>` | Comma-separated vendor override. One or more of `claude`, `cursor`, `windsurf`, `vscode`, or `all`. |
+| `--global` | Write skills to `~/.claude/skills/` (personal) instead of `.claude/skills/` (project). |
+| `--json` | Emit a structured JSON summary on success. |
 
-### Cursor
+`init` is idempotent: re-running with a valid existing config re-runs
+detection + MCP merge + first sync without re-prompting for a key. If the
+stored key has been revoked (401 from `/auth/validate`), the CLI falls back
+to the interactive prompt automatically.
 
-- Config file: `.cursor/mcp.json` with `mcpServers.skillrepo` entry
-- Uses `${env:SKILLREPO_ACCESS_KEY}` syntax for environment variable expansion
-- Skill mapping file (`.cursor/rules/skillrepo.mdc`) is static; re-run
-  `npx skillrepo init` or ask your agent to run `update skills from skillrepo`
-  to refresh it after adding or removing skills
+**Headless / CI:** if you run from a directory with no IDE markers, init
+will refuse and print a copy-pasteable MCP config for manual wiring. To
+proceed anyway, pass `--ide claude` (or the target vendor).
 
-### Windsurf
+### `update` — sync your library
 
-- Config file: `~/.codeium/windsurf/mcp_config.json` (global, not per-project)
-- Uses `serverUrl` instead of `url` in the server entry
-- Uses `${env:SKILLREPO_ACCESS_KEY}` syntax for environment variable expansion
+```sh
+skillrepo update [--global] [--ide <list>] [--json]
+```
 
-### VS Code + Copilot
+Pulls the latest state of your library from the server using a delta
+sync. Writes new and updated skills, removes skills that were removed
+from the library, and skips skills that are unchanged. Uses ETag
+caching so repeat runs return `304 Not Modified` when nothing has
+changed.
 
-- Config file: `.vscode/mcp.json` with `servers.skillrepo` entry (note:
-  `servers`, not `mcpServers`)
-- VS Code does not support environment variable interpolation in MCP config;
-  instead, the CLI creates an `inputs` entry that prompts for the access key on
-  first use
-- Uses `${input:skillrepo-api-key}` syntax to reference the input prompt
+### `get` — fetch a single skill
 
-## Team Setup
+```sh
+skillrepo get <@owner/name> [--global] [--ide <list>] [--json]
+```
 
-For teams sharing a repository, an admin runs the setup once and commits the
-generated config files. Each developer then clones and adds their own key.
+One-shot fetch. Does NOT mutate your library or the server — just reads
+`GET /api/v1/skills/{owner}/{name}` and writes the skill to disk. Use
+this to preview or pin a specific skill without adding it to your library.
 
-### Admin (one-time)
+### `list` — show what's in your library
 
 ```sh
-cd your-team-repo
-npx skillrepo init
-git add .mcp.json .claude/ .cursor/ .vscode/
-git commit -m "chore: add SkillRepo integration"
-git push
+skillrepo list [--json]
 ```
 
-The `.env.local` file is not committed -- it contains the access key and should
-remain gitignored.
+Renders your library as a table: owner, name, version, description. Uses
+the same cached ETag as `update`.
 
-### Each Developer
+### `search` — explore the registry
 
 ```sh
-git pull
-npx skillrepo init
+skillrepo search <query> [--limit <n>] [--json] [--semantic]
 ```
 
-The CLI detects the existing config files, merges in any updates, and writes the
-developer's own access key to `.env.local`. Developers can also skip the CLI
-and set the environment variable manually:
+Queries `/api/v1/skills/search` for public skills matching `query`.
+`--limit` caps the result count (default 20). `--semantic` is accepted
+but currently a no-op — semantic search is a planned backend feature.
+
+### `add` — add a skill to your library
 
 ```sh
-echo 'SKILLREPO_ACCESS_KEY=sk_live_their_key' >> .env.local
+skillrepo add <@owner/name> [--global] [--ide <list>] [--json]
 ```
 
-## Self-Hosted Usage
+POSTs to `/api/v1/library`, then fetches the single skill directly and
+writes it to disk. Requires a write-scoped access key. On `409` (already
+in library), re-fetches the current version so your local state is
+consistent.
 
-If you run a self-hosted SkillRepo instance, pass the `--url` flag:
+### `remove` — remove a skill from your library
 
 ```sh
-npx skillrepo init --url https://skillrepo.internal.company.com
+skillrepo remove <@owner/name> [--global] [--ide <list>] [--json]
 ```
 
-The CLI writes the custom URL into all MCP config files. The access key is
-validated against your self-hosted instance instead of skillrepo.dev.
+DELETEs from `/api/v1/library` and deletes the local directory. Requires
+a write-scoped access key. The local delete is immediate and does not
+wait for a follow-up sync.
 
-You can also set the URL via the `SKILLREPO_URL` environment variable to avoid
-passing `--url` every time.
+## Configuration
 
-## Troubleshooting
-
-### "Invalid key format. Keys start with sk_live_"
-
-Access keys always begin with `sk_live_`. Verify you copied the full key from
-Settings > Access Keys. If the key was created with a different prefix, it may
-be a test key that is not valid for production use.
+### Credentials
 
-### "Cannot reach https://skillrepo.dev"
+The CLI stores credentials at `~/.claude/skillrepo/config.json` (chmod
+0600 on POSIX):
 
-Check your network connection. If you are behind a corporate proxy or firewall,
-ensure HTTPS traffic to `skillrepo.dev` (or your self-hosted URL) is allowed.
-For self-hosted instances, verify the `--url` flag points to the correct address.
+```json
+{
+  "schemaVersion": 1,
+  "apiKey": "sk_live_...",
+  "serverUrl": "https://skillrepo.dev",
+  "accountSlug": "alice",
+  "accountId": "acc_...",
+  "userId": "user_...",
+  "writtenAt": "2026-04-15T00:00:00Z"
+}
+```
 
-### "Cannot parse .mcp.json -- invalid JSON"
+Every command except `init` resolves credentials in this order:
+1. `--key` / `--url` CLI flags
+2. `~/.claude/skillrepo/config.json`
+3. `SKILLREPO_ACCESS_KEY` / `SKILLREPO_URL` environment variables
+4. Hard-fail with a "run `skillrepo init`" hint
+
+`init` is different by design. Because `init` owns the credential
+lifecycle — it writes the config file in the first place, and
+`--force` / stale-key re-prompts need to decide whether to reuse
+cached credentials — `init` uses a more nuanced order. Resolved
+in sequence (each step only runs if the prior ones produced no
+key):
+
+1. `--key` / `--url` CLI flags
+2. `SKILLREPO_ACCESS_KEY` / `SKILLREPO_URL` environment variables
+   (process env, not files)
+3. Existing `~/.claude/skillrepo/config.json` — skipped when
+   `--force` is set
+4. `.env.local` and `.env` files in the project directory — skipped
+   when `--force` is set
+5. Interactive prompt for the key; server URL falls back to
+   `https://skillrepo.dev`
+
+Two scenarios worth calling out:
+
+- **`init --force` with `SKILLREPO_ACCESS_KEY` set**: uses the env
+  var (step 2). `--force` only clears the cached credentials, not
+  the runtime env.
+- **`init` with valid existing config and no flags/env**: reuses
+  the cached credentials for a silent no-op refresh.
+- **`init` with a config that the server now rejects (stale key)**:
+  falls through to the interactive prompt automatically, without
+  needing `--force`.
+
+### Environment variables
+
+| Variable | Purpose |
+|----------|---------|
+| `SKILLREPO_ACCESS_KEY` | Access key for any command. Takes precedence over the config file but not CLI flags. |
+| `SKILLREPO_URL` | Server URL. Same precedence as above. |
+| `SKILLREPO_TIMEOUT_MS` | Per-request fetch timeout in milliseconds (default 30000). Set to `0` to disable. |
+| `NO_COLOR` | Set any non-empty value to disable ANSI color in CLI output. |
+
+### Skill placement
+
+By default, skills land at `.claude/skills/<name>/` (project-scoped). Pass
+`--global` to target `~/.claude/skills/<name>/` instead. When the CLI
+detects an IDE that has no documented skills convention (Cursor, Windsurf,
+VS Code), it falls back to project `/skills/<name>/` and adds `/skills/`
+to your `.gitignore` on first write.
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | Network error (unreachable server, DNS, timeout, exhausted retries) |
+| 2 | Auth error (invalid key, revoked, suspended account) |
+| 3 | Disk error (cannot read or write a file/directory) |
+| 4 | Scope error (key lacks the required `registry:write` scope) |
+| 5 | Validation error (bad flag, malformed identifier, unknown vendor) |
+
+Pass `--verbose` to any command to print stack traces and retry
+attempts on failure.
+
+## Retries
+
+The CLI automatically retries transient server failures on every
+idempotent API call — specifically `POST /auth/validate`,
+`GET /library`, `GET /skills/:owner/:name`, and `GET /skills/search`.
+This means the read-only commands (`update`, `get`, `list`, `search`)
+and the validate + sync calls inside `init` benefit automatically.
+
+- **Triggered by:** 429, 502, 503, 504, and raw network errors (DNS,
+  TCP reset, timeout).
+- **NOT triggered by:** 4xx auth/validation errors — those never
+  succeed on retry — nor 500, which is treated as a real-bug signal
+  that should surface loudly rather than be masked.
+- **Backoff:** exponential with full jitter, 3 attempts total, base
+  500ms, capped at 8 seconds per sleep.
+- **Write endpoints** (`add`, `remove`) are single-shot to keep
+  behavior predictable — a 503 mid-POST could mean either "body
+  never reached the server" or "body processed, response lost",
+  and the client cannot distinguish the two.
+
+## Self-hosted SkillRepo
+
+The CLI works against any SkillRepo instance that implements the v1 API.
+Point it at your own host:
 
-The CLI cannot merge into a malformed JSON file. Open the file, fix the syntax
-error (or delete it to start fresh), then run `npx skillrepo init` again.
+```sh
+skillrepo init --url https://skillrepo.internal.company.com
+```
 
-### "No IDEs detected"
+Or persist it via env var in your shell profile:
 
-The CLI looks for IDE-specific directories in the current working directory. If
-you are not in a project root, `cd` into your project first. If no IDE
-directories exist yet, the CLI defaults to configuring Claude Code and Cursor.
+```sh
+export SKILLREPO_URL=https://skillrepo.internal.company.com
+export SKILLREPO_ACCESS_KEY=sk_live_...
+```
 
-### VS Code prompts for the access key every time
+## Troubleshooting
 
-This is expected. VS Code does not support environment variable expansion in
-MCP config files, so it uses an input prompt instead. The key is cached for the
-duration of your VS Code session. Enter the same key from your `.env.local`
-file.
+**"No access key configured"** — Run `skillrepo init`, or pass `--key`,
+or set `SKILLREPO_ACCESS_KEY`.
 
-### Skill mappings are stale
+**"Invalid access key format"** — Keys must start with `sk_live_`.
+The CLI trims leading and trailing whitespace from keys in every
+path — both the interactive prompt in `init` and the Bearer header
+used by every subsequent command — so pasting from email or a
+browser with a trailing newline is safe.
 
-For Claude Code, the SessionStart hook refreshes mappings automatically. For
-Cursor and VS Code + Copilot, re-run `npx skillrepo init` or ask your agent to
-run `update skills from skillrepo` to regenerate the mapping file.
+**"No IDEs detected in this directory"** — The CLI detected no
+`.claude/`, `.cursor/`, `.vscode/`, or `~/.codeium/windsurf/` markers.
+Either run from inside a project with one of those folders, pass
+`--ide <vendor>` to target a specific IDE, or copy the printed MCP
+config manually.
 
-## Requirements
+**"Rate limit exceeded — retried automatically and still getting
+429"** — The CLI already retried with backoff. Wait a minute and
+retry. Pass `--verbose` to see the per-attempt timings.
 
-- Node.js 18 or later
-- Zero runtime dependencies (uses built-in `fetch` and `fs`)
+**Windows:** skill updates use a best-effort atomic rename pattern.
+A crash mid-update may leave a partial state; the next `update` run
+fully overwrites it.
 
 ## License
 
-AGPL-3.0
+MIT — see [LICENSE](./LICENSE).