feat: setup-context7 skill + using-context7 prerequisites pointer

Split context7 concerns into two skills:
- using-context7 (policy, every-time): when to call, how to query well
- setup-context7 (infrastructure, one-time): install plugin, inject API
  key, clean manual MCP entries, with confirmation gates

setup-context7 reuses an existing CONTEXT7_API_KEY by searching, in order:
~/.claude/settings.json → ~/.claude.json (top-level + project-scoped) →
~/.claude/settings.local.json → env. Asks the user only if nothing found.
Cross-platform (paths identical on Win/Linux/macOS; only JSON validator
differs). Phase-2 confirmation gate before any write; per-edit JSON
validation; rollback procedure documented.

using-context7 gets a small Prerequisites section pointing at
setup-context7 when MCP tools are missing.

Bonus fix: scripts/build.sh PS multi-arg bug. Comma-joined -Names didn't
split into [string[]] when build.ps1 was invoked via -File. Now the bash
side loops one PS invocation per skill.

Wiki: extended .wiki/concepts/context7-setup.md with the design rationale
(why split policy from setup) — template for future "X plugin + how to
use X" pairs. index.md and log.md updated.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

.tasks/STATUS.md

@@ -3,6 +3,16 @@ _Updated: 2026-04-28_
 
 ## Done
 
+### Create `setup-context7` skill
+- [x] Drafted `skills/setup-context7/SKILL.md` — 8 phases (discovery → plan → backup → install → inject → clean → smoke-test → restart) + rollback + cross-platform notes
+- [x] API-key discovery in priority order: `settings.json` → `.claude.json` (top-level + project-scoped) → `settings.local.json` → env → ask
+- [x] Phase 2 confirmation gate (no mutations without explicit "ok"); Phase 6 validates JSON after each edit
+- [x] Documented `/plugin update` gotcha
+- [x] Added Prerequisites section in `using-context7` pointing at `setup-context7`
+- [x] Built + installed both skills (`setup-context7` already in `available_skills`)
+- [x] Updated `.wiki/concepts/context7-setup.md` with "Now captured as a skill" section explaining the policy/setup split rationale
+- [x] **Bonus fix:** `scripts/build.sh` PS multi-arg bug — comma-joined `-Names` wasn't splitting into `[string[]]` when called via `-File`. Now loops in bash, one PS invocation per skill.
+
 ### Switch context7 from manual MCP config to official plugin
 - [x] Backup `~/.claude.json` and `~/.claude/settings.json` (suffix `.bak-20260428-114532`)
 - [x] User installed `context7@claude-plugins-official`

.wiki/concepts/context7-setup.md

@@ -71,3 +71,20 @@ Manual MCP entries in `~/.claude.json` / `settings.json` are easy to:
 - drift from the canonical version
 
 The plugin centralizes the registration and gets versioned through the marketplace. The price is a single edit-after-update for the API key.
+
+## Now captured as a skill
+
+The procedure above is now formalized as the **`setup-context7`** skill ([`skills/setup-context7/SKILL.md`](../../skills/setup-context7/SKILL.md)). It runs the same algorithm with confirmation gates and key-discovery logic (search `settings.json` → `.claude.json` → env, reuse what's there, never invent). `using-context7` got a small **Prerequisites** section pointing at it.
+
+### Why split into two skills
+
+Two distinct concerns:
+
+- **Policy** (every-time, short-running): when to call resolve-library-id, query budget, how to phrase queries — this lives in `using-context7`.
+- **Setup** (one-time, mutates user config): install plugin, inject key, clean manual entries — this lives in `setup-context7`.
+
+Mixing them would make the policy skill ~2× larger, dilute its description (worse triggering), and make every library question pull setup procedure into context. The split is also a template for future "X plugin + how-to-use-X" skill pairs.
+
+### Cross-platform
+
+The setup skill is platform-agnostic. Only the JSON validator differs (PowerShell on Windows, `jq` / Python on Linux/macOS). Paths (`~/.claude/...`) are identical.

.wiki/index.md

@@ -14,7 +14,7 @@ Catalog of all wiki pages. One line per page, organized by type. Updated on ever
 
 - [active-platform-decision.md](concepts/active-platform-decision.md) — why `active-platform` is a skill (not a memory entry); why default = Windows; how it's wired into `project-bootstrap`
 - [build-notes.md](concepts/build-notes.md) — why `build.ps1` exists alongside `build.sh`; PS 5.1 backslash-in-zip gotcha; how to extract a `.skill`
-- [context7-setup.md](concepts/context7-setup.md) — switched context7 from manual MCP entries to the official plugin; API key now lives in the plugin's `.mcp.json` as `--api-key`; re-apply after `/plugin update`
+- [context7-setup.md](concepts/context7-setup.md) — switched context7 from manual MCP entries to the official plugin; API key in `.mcp.json` as `--api-key`; now also captured as `setup-context7` skill (one-time install/migrate flow with key discovery)
 - [repo-layout.md](concepts/repo-layout.md) — flat `skills/`, committed `dist/`, bash + PowerShell scripts; install model
 - [wiki-realignment.md](concepts/wiki-realignment.md) — fixing `project-bootstrap` to create the Karpathy-canonical wiki layout
 

.wiki/log.md

@@ -19,3 +19,4 @@ Parseable: `grep "^## \[" .wiki/log.md | tail -20`.
 ## [2026-04-28] refactor | wiki-realignment — fixed project-bootstrap Step 3 to create Karpathy-canonical layout
 ## [2026-04-28] refactor | this repo's `.wiki/` migrated to canonical layout (SUMMARY.md→index.md, source/→concepts/, added log.md/overview.md/CLAUDE.md schema, raw/README.md)
 ## [2026-04-28] decision | context7-setup — switched to official plugin; --api-key injected into plugin's .mcp.json; three manual MCP entries removed
+## [2026-04-28] decision | setup-context7 skill — formalized the install/migrate algorithm; using-context7 gets a Prerequisites pointer; build.sh PS multi-arg bug fixed (loop instead of comma-joined -Names)

scripts/build.sh

@@ -36,14 +36,16 @@ if command -v zip >/dev/null 2>&1; then
   done
 elif command -v powershell.exe >/dev/null 2>&1; then
   # Windows fallback: delegate to build.ps1 (proper ZIP via .NET API).
+  # PS array binding via -File is fragile (commas don't always split into [string[]]),
+  # so call build.ps1 once per skill and let the bash loop do the work.
   ps1="$SCRIPT_DIR/build.ps1"
+  ps1_win="$(cygpath -w "$ps1" 2>/dev/null || echo "$ps1")"
   if [ "$#" -eq 0 ]; then
-    powershell.exe -NoProfile -ExecutionPolicy Bypass -File "$(cygpath -w "$ps1" 2>/dev/null || echo "$ps1")"
+    powershell.exe -NoProfile -ExecutionPolicy Bypass -File "$ps1_win"
   else
-    # PS array via -File: comma-separated, no extra quoting (bash arg becomes one PS token).
-    joined=$(printf ",%s" "$@")
-    joined="${joined:1}"
-    powershell.exe -NoProfile -ExecutionPolicy Bypass -File "$(cygpath -w "$ps1" 2>/dev/null || echo "$ps1")" -Names "$joined"
+    for name in "$@"; do
+      powershell.exe -NoProfile -ExecutionPolicy Bypass -File "$ps1_win" -Names "$name"
+    done
   fi
 else
   echo "error: need either 'zip' (Linux/macOS) or PowerShell (Windows) to build .skill archives" >&2

skills/setup-context7/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: setup-context7
+description: Installs and configures the official context7 MCP plugin (`context7@claude-plugins-official`), reuses the user's existing Context7 API key, and cleans out any manual `mcpServers.context7` entries from `~/.claude.json` and `~/.claude/settings.json`. Use this skill when the user says "install context7", "set up context7", "configure context7", "настрой context7", "установи context7", "context7 не работает", "context7 isn't working", or whenever the `mcp__context7__resolve-library-id` / `mcp__context7__query-docs` tools are missing in a session that needs library docs. Cross-platform — Windows / Linux / macOS. Mutates user-level config; pauses for confirmation before writing.
+---
+
+# setup-context7
+
+> One-time skill that gets the official context7 plugin running with the user's existing API key, with manual MCP entries cleaned up. Stops at confirmation gates because the procedure modifies user-level config files.
+
+## When to use
+
+- User explicitly asks: install / set up / configure context7.
+- A `using-context7`-driven task fails because `mcp__context7__*` tools aren't available.
+- Migrating an existing manually-configured context7 to the official plugin.
+
+## Out of scope
+
+- Creating a *new* API key. This skill *reuses* a key the user already has; if there's no key, offer the OAuth flow (`npx ctx7 setup`) and stop.
+- Rolling back from the official plugin to manual config.
+- Any non-context7 MCP server.
+
+## Hard rule: don't auto-mutate config
+
+The procedure modifies `~/.claude.json` and `~/.claude/settings.json`. **Always pause for explicit confirmation between Phase 1 (discovery, read-only) and Phase 2 (plan), and again before Phase 3 (backup + writes).** A trigger phrase is permission to run discovery, not permission to overwrite config.
+
+## Procedure
+
+### Phase 0 — Environment sanity
+
+- Confirm Claude Code is the current harness (need `/plugin install` capability).
+- Confirm `npx` is on `PATH` (the plugin spawns `npx -y @upstash/context7-mcp`). If missing, install Node.js first.
+- Pick paths: `~/.claude/` works on all three OSes. In git-bash on Windows, `~` resolves correctly.
+
+### Phase 1 — Discovery (read-only)
+
+Search, in order. Stop reporting verbatim values for keys; report only "found at <path>".
+
+**Existing API key.** Look in priority order:
+
+1. `~/.claude/settings.json` → `mcpServers.context7.headers.CONTEXT7_API_KEY`
+2. `~/.claude.json` → top-level `mcpServers.context7.headers.CONTEXT7_API_KEY`
+3. `~/.claude.json` → `projects.<any>.mcpServers.context7.headers.CONTEXT7_API_KEY`
+4. `~/.claude/settings.local.json` if present
+5. Env var `CONTEXT7_API_KEY`
+
+The first hit wins. Capture the key value internally for Phase 5; **never echo it in chat**.
+
+**Manual context7 MCP entries.** Find every `mcpServers.context7` block in `~/.claude.json` and `~/.claude/settings.json` (top-level and project-scoped). Note all locations.
+
+**Plugin install state.** Read `~/.claude/plugins/installed_plugins.json` and check for `context7@claude-plugins-official`.
+
+**Plugin's `.mcp.json` state** (only if plugin is installed). Path:
+```
+~/.claude/plugins/cache/claude-plugins-official/context7/<version>/.mcp.json
+```
+`<version>` is often `unknown` for un-tagged marketplace plugins. List the cache dir to find it. Check whether `--api-key` is already in `args`.
+
+### Phase 2 — Plan + confirm
+
+Present a single-block plan to the user:
+
+```
+API key:        <found-at | NOT FOUND — will ask>
+Plugin:         <installed | will ask user to /plugin install>
+Manual entries: <list of paths to remove>
+Backups:        ~/.claude.json.bak-<ts>, ~/.claude/settings.json.bak-<ts>
+```
+
+Wait for explicit confirmation ("ok", "go", "поехали"). Anything else → stop.
+
+If no API key was found in Phase 1 — first ask: "Paste a Context7 API key, or run `npx ctx7 setup` to get one (OAuth)?" Don't proceed past Phase 2 without a key.
+
+### Phase 3 — Backup
+
+Copy each file we will modify to `<file>.bak-YYYYMMDD-HHMMSS`:
+```bash
+TS=$(date +%Y%m%d-%H%M%S)
+cp ~/.claude.json ~/.claude.json.bak-$TS
+cp ~/.claude/settings.json ~/.claude/settings.json.bak-$TS
+```
+Confirm both backups exist before any further edit.
+
+### Phase 4 — Plugin install (if needed)
+
+If the plugin is **not** in `installed_plugins.json`:
+1. Ask the user to run `/plugin install context7@claude-plugins-official` in Claude Code (we can't run interactive slash commands).
+2. Wait for "поставил" / "installed".
+3. Verify by re-reading `installed_plugins.json`.
+
+If the plugin **is** already installed: skip this phase.
+
+### Phase 5 — Inject `--api-key`
+
+Find the live plugin file:
+```
+~/.claude/plugins/cache/claude-plugins-official/context7/<version>/.mcp.json
+```
+
+If the file's `args` already contains `--api-key`, skip. Otherwise edit `args` to append `"--api-key", "<KEY>"`. Final shape:
+
+```json
+{
+  "context7": {
+    "command": "npx",
+    "args": ["-y", "@upstash/context7-mcp", "--api-key", "<KEY>"]
+  }
+}
+```
+
+Per Upstash's client-config docs (<https://context7.com/docs/resources/all-clients>), `--api-key` is the recommended form for stdio transport. Header form is for HTTP transport (which the plugin doesn't use).
+
+### Phase 6 — Clean manual entries
+
+For each manual entry found in Phase 1:
+
+- **Top-level `mcpServers.context7`** in `settings.json` or `.claude.json` → remove the `context7` key. Preserve sibling MCP servers and JSON validity (watch for trailing commas).
+- **Project-scoped `projects.<path>.mcpServers.context7`** in `.claude.json` → remove. If the parent `mcpServers` becomes empty, leave it as `{}` (don't delete the key — Claude Code may rely on its presence).
+
+After each edit, validate JSON. On any platform:
+```bash
+# Windows (PowerShell)
+powershell.exe -NoProfile -c "Get-Content '<file>' -Raw | ConvertFrom-Json | Out-Null"
+# Linux / macOS (jq) — install via brew/apt if missing
+jq empty <file>
+# fallback: python (always available)
+python -c "import json,sys; json.load(open('<file>'))"
+```
+
+If validation fails → restore the just-edited file from its `.bak-*` and abort with a clear report. Do not continue editing.
+
+### Phase 7 — Smoke test (best-effort)
+
+Call `mcp__context7__resolve-library-id` with a benign query (e.g. `libraryName: "Nuxt"`, `query: "smoke test"`). If it returns library IDs — context7 is reachable in *this* session.
+
+**Important caveat to relay to the user:** in the *same* session that just ran setup, the MCP server is still the legacy connection bound at session start. So a passing smoke test only proves "context7 still works" — not "the plugin is what's serving it". The real test is after Claude Code restart.
+
+### Phase 8 — Restart guidance + final report
+
+Tell the user:
+
+```
+✅ Setup complete. Restart Claude Code to pick up the plugin's stdio transport.
+
+After restart:
+  • mcp__context7__* tools will be served by `npx @upstash/context7-mcp --api-key …`
+  • Manual entries are gone — single source of truth is the plugin's .mcp.json.
+  • Backups saved at ~/.claude.json.bak-<ts> and ~/.claude/settings.json.bak-<ts>.
+
+If something breaks after restart:
+  • Restore from .bak-* files and tell me — we'll roll back together.
+```
+
+## Rollback procedure
+
+If a problem surfaces (now or after restart):
+
+1. Stop. Don't try to fix forward.
+2. Find the most recent `.bak-YYYYMMDD-HHMMSS` next to `~/.claude.json` and `~/.claude/settings.json`.
+3. `cp <file>.bak-<ts> <file>` for both.
+4. Optional: `/plugin uninstall context7@claude-plugins-official`.
+5. Restart Claude Code.
+6. Confirm `mcp__context7__*` is back via the legacy HTTP path.
+7. Report what went wrong so we can fix the procedure.
+
+## Plugin-update gotcha
+
+`/plugin update context7@claude-plugins-official` (or any reinstall) re-fetches the plugin's `.mcp.json` from the marketplace cache. That file is upstream-canonical and **does not** contain `--api-key` — the marketplace doesn't ship secrets. After any plugin update:
+
+- Run this skill again. Phase 1 will detect the missing flag, Phase 5 will re-inject. Phases 4 and 6 are no-ops.
+- Or manually re-add `--api-key` to `args` in the live `.mcp.json`.
+
+The marketplace upstream is at `anthropics/claude-plugins-official/external_plugins/context7/.mcp.json`. It's two lines and rarely changes — the `--api-key` re-injection is the only ongoing maintenance cost.
+
+## Cross-platform notes
+
+The procedure is platform-agnostic. Only auxiliary tooling differs:
+
+| | JSON validate | Backup |
+|---|---|---|
+| Windows (git-bash) | `powershell.exe -NoProfile -c "Get-Content '<f>' -Raw \| ConvertFrom-Json \| Out-Null"` | `cp` |
+| Linux | `jq empty <f>` (or `python -c "import json; json.load(open('<f>'))"`) | `cp` |
+| macOS | same as Linux | `cp` |
+
+Path forms (`~/.claude/...`) are identical on all three.
+
+## Common mistakes
+
+- **Skipping Phase 1.** "User just said 'install context7' — let's go." No — find the existing key first; making the user paste a key when they already have one is rude.
+- **Echoing the key.** It's a secret. The Edit / Write tool calls inevitably contain it (that's how it gets into the file), but no chat output should.
+- **Mutating `.claude.json` without backup.** That file holds *all* of the user's per-project Claude Code state. Losing it is bad.
+- **Treating in-session smoke test as proof.** It isn't — the active MCP connection is bound at session start.
+- **Auto-running on every "use context7".** This skill is intrusive. Trigger only when explicitly invoked or when MCP tools are missing and the user is blocked.

skills/using-context7/SKILL.md

@@ -11,6 +11,10 @@ description: Use when answering questions about a specific library, framework, S
 
 Your training data has a cutoff. Library APIs change. If a question names a library, **reach for context7 before answering from memory**, even for libraries you "know" — your recall may be one or two majors behind.
 
+## Prerequisites
+
+This skill assumes `mcp__context7__resolve-library-id` and `mcp__context7__query-docs` are available. If they aren't (the tools are missing from the session, or calls fail with a connection error), the context7 MCP server isn't running for this session. Trigger the **`setup-context7`** skill to install/configure the official plugin (`context7@claude-plugins-official`) and inject the user's API key. It's a one-time procedure with confirmation gates.
+
 ## When to use
 
 Use when the user asks about any of these in the context of a specific library: