skills/skills/setup-context7/SKILL.md

name, author, version, description

name	author	version	description
setup-context7	ours	2.0.0	Installs and configures the agent-neutral `ctx7` CLI (npm) for Context7 docs — CLI-first, no MCP registration. Reuses an existing Context7 API key or offers the OAuth flow, and migrates off the legacy context7 MCP plugin (`context7@claude-plugins-official`): uninstalls the plugin, cleans `mcpServers.context7` entries from `~/.claude.json` / `~/.claude/settings.json`. Use when the user says «настрой context7», «установи context7», «context7 не работает», "set up context7", "install context7", "context7 isn't working", or when a session needs library docs and the `ctx7` CLI is missing. Cross-platform — Windows / Linux / macOS. Mutates user-level config; pauses for confirmation before writing.

setup-context7

One-time skill that gets the ctx7 CLI running with the user's existing Context7 key, and migrates off the legacy MCP plugin. Agent-neutral: any harness (pi / claude / hermes / codex) calls ctx7 in bash — no MCP registration, no harness-specific tools. 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 the ctx7 CLI isn't on PATH.
• Migrating an existing plugin/MCP-based context7 install to the CLI (legacy cleanup).

Out of scope

• Creating a new API key. This skill reuses a key the user already has or offers the OAuth flow (ctx7 login); if the user has no key and no account, offer OAuth and stop.
• Rolling back from CLI to the plugin (not supported — CLI is the canonical path, idea 16 claude-to-agents).
• Any non-context7 MCP server.

Hard rule: don't auto-mutate config

The procedure modifies ~/.claude.json, ~/.claude/settings.json and the plugin install state. 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.

Prerequisites

• Node.js / npm on PATH (the CLI is an npm package). Check with node -v; if missing, install Node first.
• Git Bash gotcha (Windows): library IDs start with / and Git Bash path-converts them — using-context7 documents the //owner/repo double-slash workaround.

Procedure

Phase 0 — Environment sanity

• Check whether ctx7 is already installed: ctx7 --version. Installed → skip Phase 4 (install), proceed to Phase 5 (auth) / cleanup as needed.
• Pick paths: ~/.claude/ and ~/.config/projects-secrets/ work 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 ".

Existing API key. Look in priority order:

1. ~/.config/projects-secrets/ctx7.env → CONTEXT7_API_KEY= (our secrets convention, cf. interns.env / auth.toml)
2. Env var CONTEXT7_API_KEY
3. ~/.claude/settings.json → mcpServers.context7.headers.CONTEXT7_API_KEY
4. ~/.claude.json → top-level mcpServers.context7.headers.CONTEXT7_API_KEY
5. ~/.claude/settings.local.json if present

The first hit wins. Capture the key value internally for Phase 5; never echo it in chat.

Legacy MCP/plugin state (migration targets — report locations, don't touch yet):

• Manual mcpServers.context7 blocks in ~/.claude.json and ~/.claude/settings.json (top-level and project-scoped).
• Plugin installed: ~/.claude/plugins/installed_plugins.json contains context7@claude-plugins-official?
• Plugin cache/data dirs: ~/.claude/plugins/cache/claude-plugins-official/context7/, ~/.claude/plugins/data/context7*.

Phase 2 — Plan + confirm

Present a single-block plan to the user:

ctx7 CLI:       <installed vX.Y.Z | will npm i -g ctx7>
API key:        <found-at | NOT FOUND — will ask / offer OAuth>
Legacy to clean:
  plugin:       <installed | not installed>
  manual MCP:   <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 ctx7 login (OAuth, interactive)?" Don't proceed past Phase 2 without a key.

Phase 3 — Backup

Copy each file we will modify to <file>.bak-YYYYMMDD-HHMMSS:

TS=$(date +%Y%m%d-%H%M%S)
cp ~/.claude.json ~/.claude.json.bak-$TS
cp ~/.claude/settings.json ~/.claude/settings.json.bak-$TS
cp ~/.config/projects-secrets/ctx7.env ~/.config/projects-secrets/ctx7.env.bak-$TS 2>/dev/null || true

Confirm backups exist before any further edit.

Phase 4 — Install the CLI

npm install -g ctx7
ctx7 --version   # verify

If the user prefers no global install: npx -y ctx7 ... works per-call (no install) — but for a standing setup, the global install is one-time and cheaper per call.

Phase 5 — Auth (key or OAuth)

• Key found (Phase 1): write ~/.config/projects-secrets/ctx7.env:

  CONTEXT7_API_KEY=<KEY>
  

  (if the file exists, merge the key in; never clobber sibling entries).

• No key: run ctx7 login (interactive OAuth, one-time, human runs it) or ask the user to paste a key.

Verify: ctx7 library Nuxt "config" должен вернуть ID библиотеки — это функциональный smoke (работает анонимно; env-ключ даёт повышенные лимиты, но не меняет вывод). Примечание: ctx7 whoami отвечает "Not logged in" даже с env-ключом — это OAuth-идентичность (ctx7 login), не проверка ключа; не считать ошибкой setup.

Phase 6 — Clean legacy MCP/plugin (migration)

For each legacy item found in Phase 1:

• Plugin installed → uninstall via CLI:

  claude plugin uninstall context7@claude-plugins-official
  

  Then remove leftover cache/data dirs if any remain: ~/.claude/plugins/cache/claude-plugins-official/context7/, ~/.claude/plugins/data/context7*.

• Manual mcpServers.context7 in settings.json / .claude.json (top-level) → 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:

# 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

Call the CLI with a benign query:

ctx7 library Nuxt "Nuxt 4 config and route rules"

If it returns library IDs / snippets — context7 works via CLI in any harness. (ctx7 whoami — OAuth-идентичность, отвечает "Not logged in" при env-ключе; не смоук-критерий.)

Phase 8 — Restart guidance + final report

Tell the user:

✅ Setup complete. ctx7 CLI is agent-neutral — no MCP registration, no restart needed for other agents.

  • Usage: ctx7 library <name> / ctx7 docs <libraryId> "<question>" (see using-context7)
  • Key:    ~/.config/projects-secrets/ctx7.env (CONTEXT7_API_KEY)
  • Legacy: context7 plugin + mcpServers.context7 entries removed (single source = CLI)
  • Backups saved at ~/.claude.json.bak-<ts> and ~/.claude/settings.json.bak-<ts>.

If something breaks after cleanup:
  • Restore from .bak-* files and tell me — we'll roll back together.

Rollback procedure

If a problem surfaces (now or later):

1. Stop. Don't try to fix forward.
2. Find the most recent .bak-YYYYMMDD-HHMMSS next to the modified files.
3. cp <file>.bak-<ts> <file> for each.
4. Optional: reinstall the plugin via /plugin install context7@claude-plugins-official if the user wants the MCP path back.
5. Restart Claude Code.
6. Confirm mcp__context7__* is back via the legacy path.
7. Report what went wrong so we can fix the procedure.

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/..., ~/.config/projects-secrets/...) 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.
• Leaving the legacy plugin installed. The point of the CLI migration is one agent-neutral path; a stale plugin means two sources of truth. Clean it in Phase 6.
• Auto-running on every "use context7". This skill is intrusive. Trigger only when explicitly invoked or when the CLI is missing and the user is blocked.

Why CLI-first (design note)

Context7 is an HTTP MCP server + npm CLI. The MCP path (context7@claude-plugins-official) is harness-specific glue (claude-plugins-official); pi doesn't see it (the claude-mcp-bridge only reads ~/.claude.json, and even then it's fragile). Per the sovereign-catalog principle "что можно сделать CLI — делаем CLI и оборачиваем в скил; MCP только там, где нужен структурированный/интерактивный протокол" — the CLI is the canonical path (idea 16, claude-to-agents running record).