claude-skills/skills/setup-interns/SKILL.md

---
name: setup-interns
version: 0.2.0
description: Installs and configures the local `interns` MCP server — a FastMCP stdio app at `<project-root>/.common/lib/interns-mcp/` that delegates bulk reads, transcript distillation, and other predictable I/O to cheap intern LLMs (DeepSeek / Kimi / Ollama) so Claude saves Anthropic quota. Procedure: detect the server source, `pip install -e` it, write `.common/secrets/interns.env` with the endpoint API keys, register `mcpServers.interns` in `~/.claude.json`. Use this skill when the user says "install interns", "set up interns", "configure interns", "настрой интернов", "установи интернов", "interns не работает", "interns isn't working", or whenever the `mcp__interns__*` tools are missing in a session that needs delegation. Cross-platform — Windows / Linux / macOS. Mutates user-level config and writes secrets; pauses for confirmation before every write.
---

# setup-interns

> One-time skill that gets the local `interns` MCP server running with the user's endpoint API keys and a registered `mcpServers.interns` entry in `~/.claude.json`. Stops at confirmation gates because the procedure runs `pip install`, writes a secret-bearing `.env` file, and edits user-level config.

Reference: full design lives in this repo at `.wiki/concepts/interns-design.md` (Layer 1/2/3 architecture, MVP catalog, always-ask paths, routing hints).

## When to use

- User explicitly asks: install / set up / configure interns.
- A `using-interns`-driven task fails because `mcp__interns__*` tools aren't available in the session.
- New machine in the user's multi-machine fleet — install once per machine that wants delegation.
- Migrating a stale install (endpoint key rotated, server source moved, broken `dist/` artifact) — same procedure, Phase 1 detects what's already in place.

## Out of scope

- Building or scaffolding the `.common/lib/interns-mcp/` source tree itself. The skill expects the source already in place per the inline `.common/` convention from the design (or a future Gitea repo when that branch lands). If the source is absent, Phase 1 stops with a clear message — initializing a fresh runtime is a separate task.
- Issuing or rotating endpoint API keys (Ollama Cloud, OpenRouter, etc.). The skill *uses* keys the user already has; if there is none, it points at the provider's settings page and stops.
- Running `interns-mcp` itself — the Claude Code harness spawns it on session start.
- Authoring new interns or editing `.common/config/interns/config.yaml` — that's a content task, not a setup task.
- Any other MCP server.

## Hard rule: don't auto-mutate config

The procedure runs `pip install`, writes `.common/secrets/interns.env` (carries endpoint API keys), and edits `~/.claude.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 grants permission to inspect, not to install or write secrets.

## Procedure

### Phase 0 — Environment sanity

- Confirm Claude Code is the current harness (need `mcpServers` registration in `~/.claude.json`).
- Confirm `python` ≥ 3.11 and `pip` are on `PATH`. Report the resolved interpreter path (`python -c "import sys; print(sys.executable)"`); the skill will pin this exact path in the MCP registration so a later `python` shadowed by another env doesn't silently take over.
- Confirm `node` is on `PATH` (`node --version`). The `repo_read` intern runs `npx repomix@latest` as a subprocess. If `node` is absent, the user must install Node.js 20+ before proceeding — `repo_read` calls will fail at runtime with a clear "node not found" error.
- (Optional, recommended) Pre-warm the repomix binary: `npx --yes repomix@latest --version`. This caches the package so the first real `repo_read` call is instant (5–10s first-run penalty avoided). Skip silently on failure — the call will just be slower the first time.
- Confirm network reachability to the configured endpoints (default: `https://ollama.com/v1`). On HTTP 401 / 403 later, the API key is dead — stop and ask for a new one.
- Pick paths: `<project-root>/.common/lib/interns-mcp/` (source), `<project-root>/.common/config/interns/config.yaml` (catalog), `<project-root>/.common/secrets/interns.env` (keys, gitignored), `~/.claude.json` (MCP registration). POSIX-style paths resolve correctly under git-bash on Windows.

### Phase 1 — Discovery (read-only)

Search, in order. Report only "found at <path>", never echo key values.

**Server source.** Check whether `<project-root>/.common/lib/interns-mcp/pyproject.toml` exists. If absent, **stop** — the runtime source must be in place before this skill runs. Report:

```
.common/lib/interns-mcp/ not found.
This skill expects the inline interns-mcp source per the
.common/ layout (see .wiki/concepts/interns-design.md). Initialize
the runtime first, then re-run setup-interns.
```

**Build artifact.** Run `python -c "import interns_mcp" 2>&1` against the candidate interpreter. If it fails with `ModuleNotFoundError`, Phase 4 will run `pip install -e .common/lib/interns-mcp/`. If it succeeds, capture the installed location and skip the install in Phase 4.

**Config catalog.** Read `<project-root>/.common/config/interns/config.yaml`. Extract the unique set of `endpoints.<name>.api_key_env` values — these are the env var names the runtime expects to find. Capture for Phase 2.

**Existing endpoint keys.** Look in priority order, per `api_key_env` name from the config:

1. `<project-root>/.common/secrets/interns.env` (`<NAME>=...` lines).
2. Process env (`os.environ[<NAME>]`).
3. `~/.config/projects-mcp/auth.toml` — only if the user has explicitly noted the key is shared with another local MCP server (rare).

The first hit wins per key. **Never echo key values in chat.**

**MCP registration.** Read `~/.claude.json` and check `mcpServers.interns`. Note the `command` and `args`. If args point at a stale interpreter, Phase 6 will fix it.

**Gitignore sanity.** Check `.gitignore` (project root). If `.common/secrets/` (or `.common/secrets/*.env`) is not listed, flag for Phase 2 — the skill will offer to add it before writing the file.

### Phase 2 — Plan + confirm

Present a single-block plan to the user:

```
Source:        <found at .common/lib/interns-mcp/ | NOT FOUND — STOP>
Module:        <interns_mcp importable | will pip install -e>
Config:        <found at .common/config/interns/config.yaml> — endpoints: <names>
Missing keys:  <list of <NAME> not yet present in interns.env | none>
Gitignore:     <covers .common/secrets/ | will add ".common/secrets/*.env">
MCP entry:     <present in ~/.claude.json | will add | will fix interpreter path>
Backups:       ~/.claude.json.bak-<ts>, .common/secrets/interns.env.bak-<ts> (if exists)
```

Wait for explicit confirmation ("ok", "go", "поехали"). Anything else → stop.

For each missing key, ask: "Paste a value for `<NAME>` (endpoint: `<endpoint_name>` — provider settings page: `<url-from-config-or-known-list>`), or skip and we'll leave the entry blank for you to fill later." Don't proceed past Phase 2 without resolving every required key — the runtime won't start with a missing API key.

### Phase 3 — Backup

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

```bash
TS=$(date +%Y%m%d-%H%M%S)
[ -f ~/.claude.json ] && cp ~/.claude.json ~/.claude.json.bak-$TS
[ -f .common/secrets/interns.env ] && cp .common/secrets/interns.env .common/secrets/interns.env.bak-$TS
```

Confirm both backups exist (when their source existed) before any further edit.

### Phase 4 — Install Python module

```bash
# from project root
python -m pip install -e .common/lib/interns-mcp/
```

Capture the resolved `python` from Phase 0; use the same interpreter for both `pip install` and the later MCP `command:` field. Verify post-install:

```bash
python -c "import interns_mcp; print(interns_mcp.__file__)"
```

If import fails — abort. Ask the user to paste the `pip install` output so the failure mode is visible.

### Phase 5 — Write `interns.env` + gitignore

If Phase 1 flagged a missing `.gitignore` rule, append it first:

```
# interns endpoint API keys
.common/secrets/*.env
```

Then write `.common/secrets/interns.env`. Per-key behavior:

- Existing key in the file with a non-empty value — leave it alone.
- Missing key — append `<NAME>=<value-from-Phase-2>` if the user pasted one, or `<NAME>=` (blank) if the user skipped. A blank entry will fail at runtime with a clear `KeyError`; that's acceptable for the "I'll fill it later" path.

Permissions: on Linux / macOS run `chmod 600 .common/secrets/interns.env`. On Windows the default ACL is per-user, no extra step.

### Phase 6 — Register in `~/.claude.json`

Edit `~/.claude.json`. Add or update the `mcpServers.interns` block:

```json
{
  "mcpServers": {
    "interns": {
      "command": "<ABSOLUTE_PATH_TO_PYTHON>",
      "args": ["-m", "interns_mcp.server"],
      "cwd": "<ABSOLUTE_PATH_TO_PROJECT_ROOT>"
    }
  }
}
```

`cwd` is set so the runtime resolves `.common/config/interns/config.yaml` and `.common/secrets/interns.env` relative to project root regardless of where Claude Code was launched.

Absolute interpreter path comes from Phase 0 (`sys.executable`). Forward slashes work in JSON on Windows without escaping.

After each edit, validate JSON:

```bash
# Windows (git-bash)
powershell.exe -NoProfile -c "Get-Content '<file>' -Raw | ConvertFrom-Json | Out-Null"
# Linux / macOS
jq empty <file>
# fallback
python -c "import json; json.load(open('<file>'))"
```

If validation fails → restore from `.bak-*` and abort.

### Phase 7 — Smoke test (best-effort)

Best-effort: ask the user to call `mcp__interns__bulk_text_read` against a tiny benign input (e.g. read this file's `Phase 7` section, ask "what is this section about?"). A response that is structurally valid (text + usage) means the server is reachable.

**Important caveat to relay to the user:** in the *same* session that just ran setup, the active MCP connection was bound at session start. So a passing in-session smoke test only proves "an interns server is alive" — not "the registration we just wrote is what's serving it". The real test is after Claude Code restart.

If `mcp__interns__*` tools aren't registered in this session at all, skip the smoke test and rely on Phase 8.

### Phase 8 — Restart guidance + final report

Tell the user:

```
✅ Setup complete. Restart Claude Code so the new mcpServers.interns
   registration binds to a fresh stdio session.

After restart:
  • mcp__interns__* tools serve from <python> -m interns_mcp.server
  • Endpoint keys live in .common/secrets/interns.env (gitignored)
  • Config catalog at .common/config/interns/config.yaml
  • Backups saved at ~/.claude.json.bak-<ts> (and interns.env.bak-<ts>
    if it existed before)

Runtime policy lives in `using-interns`. CLAUDE.md trigger:
  delegate to interns when allowed
project-bootstrap 1.6.0+ adds it to new projects automatically.

If something breaks after restart:
  • Restore from .bak-* 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 `.common/secrets/interns.env`.
3. `cp <file>.bak-<ts> <file>` for each.
4. Optional: `pip uninstall interns-mcp` if you want to remove the editable install.
5. Restart Claude Code.
6. Confirm `mcp__interns__*` is gone (or back to its pre-existing version).
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 | Permissions on `.env` |
|---|---|---|---|
| Windows (git-bash) | `powershell.exe -NoProfile -c "Get-Content '<f>' -Raw \| ConvertFrom-Json \| Out-Null"` | `cp` | per-user ACL by default |
| Linux | `jq empty <f>` (or `python -c "import json; json.load(open('<f>'))"`) | `cp` | `chmod 600` |
| macOS | same as Linux | `cp` | `chmod 600` |

POSIX-style paths (`.common/...`, `~/.claude.json`) work on all three.

## Common mistakes

- **Skipping Phase 1.** "User just said 'install interns' — let's go." No — find existing source / module / keys first; clobbering an existing `.env` over a working one loses keys you can't recover.
- **Echoing endpoint keys.** They're secrets. Edit / Write tool calls inevitably contain them (that's how they land in `.env`), but no chat output should.
- **Pinning `python` instead of `<sys.executable>`.** A bare `python` in the MCP `command:` resolves to whatever interpreter is first on `PATH` at session start — often a different env without the `interns_mcp` module. Always use the absolute interpreter path captured in Phase 0.
- **Forgetting `cwd:`.** Without it the runtime can't find `.common/config/interns/config.yaml` and bombs at startup with a config-not-found error that looks like a Claude Code bug.
- **Writing `.env` with `0644` perms on Linux/macOS.** Token leak. Always `chmod 600` after write.
- **Missing the gitignore rule.** Tokens commit to the repo on the next `git add .`. Always check `.gitignore` covers `.common/secrets/*.env` before writing — Phase 5 does it but it's worth double-checking.
- **Treating in-session smoke test as proof.** Same as the context7 / projects-meta caveat — the active MCP connection was bound at session start. Real verification happens after restart.
- **Auto-running on every "use interns".** This skill is intrusive. Trigger only on explicit "install / set up / configure interns", or when MCP tools are missing and the user is blocked.