skillrepo 2.0.0 → 3.1.0

package/README.md

@@ -1,214 +1,345 @@
 # 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.
+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.
 
-3. **Writes MCP configuration files** for each detected IDE, using the correct
-   format and environment variable syntax for that IDE.
+## Commands
 
-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.
+### `init` — first-run setup
 
-### Files Created or Modified
+```sh
+skillrepo init [--key <key>] [--url <url>] [--yes] [--force] [--ide <list>] [--global] [--json] [--no-session-sync]
+```
 
-| 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) |
+Validates your access key, detects installed IDEs, writes the MCP config,
+installs the Claude Code SessionStart hook (opt-in — see `session-sync`
+below), and runs the first library sync.
 
-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.
+| 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. Installs the session-sync hook by default — pass `--no-session-sync` to opt out. |
+| `--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). |
+| `--no-session-sync` | Skip step 6 (SessionStart hook install). Works in both interactive and `--yes` modes. Use for CI scripts that bootstrap a project without ever starting a Claude Code session. |
+| `--json` | Emit a structured JSON summary on success. Includes a `sessionSync: { action, path }` block describing whether the hook was installed. |
 
-## IDE-Specific Details
+`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.
 
-### Claude Code
+**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).
 
-- 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
+### `update` — sync your library
 
-### Cursor
+```sh
+skillrepo update [--global] [--ide <list>] [--json]
+```
 
-- 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
+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.
 
-### Windsurf
+### `get` — fetch a single skill
 
-- 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 get <@owner/name> [--global] [--ide <list>] [--json]
+```
 
-### VS Code + Copilot
+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.
 
-- 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
+### `list` — show what's in your library
 
-## Team Setup
+```sh
+skillrepo 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.
+Renders your library as a table: owner, name, version, description. Uses
+the same cached ETag as `update`.
 
-### Admin (one-time)
+### `search` — explore the registry
 
 ```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 search <query> [--limit <n>] [--json] [--semantic]
 ```
 
-The `.env.local` file is not committed -- it contains the access key and should
-remain gitignored.
+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.
 
-### Each Developer
+### `add` — add a skill to your library
 
 ```sh
-git pull
-npx skillrepo init
+skillrepo add <@owner/name> [--global] [--ide <list>] [--json]
 ```
 
-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:
+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.
+
+### `remove` — remove a skill from your library
 
 ```sh
-echo 'SKILLREPO_ACCESS_KEY=sk_live_their_key' >> .env.local
+skillrepo remove <@owner/name> [--global] [--ide <list>] [--json]
 ```
 
-## Self-Hosted Usage
+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.
 
-If you run a self-hosted SkillRepo instance, pass the `--url` flag:
+### `session-sync` — auto-sync on Claude Code session start
 
 ```sh
-npx skillrepo init --url https://skillrepo.internal.company.com
+skillrepo session-sync enable [--global] [--json]
+skillrepo session-sync disable [--global] [--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.
+Installs (or removes) a Claude Code [SessionStart hook](https://docs.claude.com/en/docs/claude-code/hooks) that calls `skillrepo update` every time you open a Claude Code session — keeping your library current without you remembering to sync manually. The hook lives in `.claude/settings.local.json` (per-developer, gitignored by default) and runs your existing globally-installed `skillrepo` binary.
 
-You can also set the URL via the `SKILLREPO_URL` environment variable to avoid
-passing `--url` every time.
+By default `skillrepo init` prompts you to install this hook. If you said no (or passed `--no-session-sync`), run `session-sync enable` later to turn it on.
 
-## Troubleshooting
+**The hook cannot block your session.** The command it runs is `skillrepo update --session-hook 2>&1 || true`. That flag makes `update` exit 0 on every failure — network outage, revoked key, disk error, anything — and print a single-line failure message to your session. The `|| true` shell backstop catches anything that escapes. Session starts are never blocked by sync failures.
 
-### "Invalid key format. Keys start with sk_live_"
+**On 304 (nothing changed) the hook is silent.** You only see output when your library actually syncs or a failure happens. No "Syncing…" noise on every session.
 
-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.
+Flags:
 
-### "Cannot reach https://skillrepo.dev"
+- `--global` — operates on `~/.claude/settings.local.json` so the hook fires in every Claude Code session across all projects on your machine.
+- `--json` — emit structured JSON with `action`, `path`, and `command` fields for scripting.
 
-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.
+### `uninstall` — remove SkillRepo from a project
 
-### "Cannot parse .mcp.json -- invalid JSON"
+```sh
+skillrepo uninstall [--dry-run] [--yes] [--global] [--json]
+```
+
+Surgically removes every SkillRepo artifact from the current project:
+
+- `mcpServers.skillrepo` from `.mcp.json`, `.cursor/mcp.json`,
+  and `.vscode/mcp.json` (plus the matching `inputs` prompt in the
+  VS Code config)
+- `SKILLREPO_ACCESS_KEY=...` lines from `.env.local`
+- The SkillRepo section of `.gitignore`
+- The SkillRepo `SessionStart` hook from `.claude/settings.local.json`
+  (if present)
+- The `.claude/skills/` directory
+
+Non-SkillRepo entries in shared files are preserved. Runs offline — no
+server call required, so a revoked or missing access key is not a
+problem. Interactive by default: the command prints a full list of what
+will be removed and prompts for confirmation before touching anything.
+
+With `--global`, also removes:
+
+- `mcpServers.skillrepo` from `~/.codeium/windsurf/mcp_config.json`
+- The `~/.claude/skills/` global skill cache
+- The `~/.claude/skillrepo/` directory (stored credentials + sync cache)
+
+Flags:
+
+- `--dry-run` / `-n` — print what would be removed and exit without
+  touching any file.
+- `--yes` / `-y` — skip the confirmation prompt.
+- `--global` — also remove user-global state. By default the command
+  leaves your credential and other projects' integrations untouched.
+- `--json` — emit structured JSON instead of human output. The summary
+  includes `removed[]` and `errors[]` arrays suitable for scripting.
+
+The command is idempotent — a second run with nothing left to remove
+exits 0 and reports "Nothing to remove." If any artifact fails to
+remove (e.g. a file is read-only), the command continues processing
+the others, surfaces every error at the end, and exits with code 3
+(disk error).
+
+## Configuration
+
+### Credentials
+
+The CLI stores credentials at `~/.claude/skillrepo/config.json` (chmod
+0600 on POSIX):
+
+```json
+{
+  "schemaVersion": 1,
+  "apiKey": "sk_live_...",
+  "serverUrl": "https://skillrepo.dev",
+  "accountSlug": "alice",
+  "accountId": "acc_...",
+  "userId": "user_...",
+  "writtenAt": "2026-04-15T00:00:00Z"
+}
+```
 
-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.
+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:
 
-### "No IDEs detected"
+```sh
+skillrepo init --url https://skillrepo.internal.company.com
+```
 
-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.
+Or persist it via env var in your shell profile:
 
-### VS Code prompts for the access key every time
+```sh
+export SKILLREPO_URL=https://skillrepo.internal.company.com
+export SKILLREPO_ACCESS_KEY=sk_live_...
+```
+
+## 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).