OpeItcLoc03/claude-skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(interns-skills-mvp): ship setup-interns + using-interns v0.1.0; project-bootstrap 1.5.0 -> 1.6.0

Browse Source 
setup-interns (v0.1.0) — 8-phase install of the local `interns` MCP server:
detect `.common/lib/interns-mcp/` source, `pip install -e`, write
`.common/secrets/interns.env` with endpoint API keys (gitignored), register
`mcpServers.interns` in `~/.claude.json` with absolute Python interpreter
path + `cwd` so the runtime resolves config relative to project root.
Mirrors setup-projects-meta / setup-context7 confirmation-gate shape.
Description 899 chars (under the 900 budget per
feedback_skill_description_length_limit).

using-interns (v0.1.0) — runtime policy for `mcp__interns__*`. Per-session
permission grant mirrors project-discipline Rule 4: ask-mode default,
conversational grant ("разреши интернов" / "allow interns"), conversational
revoke, always-ask paths for `**/.env`, `**/secrets/**`, `**/*.key`,
`**/.ssh/**`, `**/.aws/credentials` etc with transitive rule (Claude can't
bypass by reading the file with the local Read tool and forwarding content),
cost-cap >$0.10 always asks, session-end automatic reset. Routing hints for
`bulk_text_read` (3+ files or one file >400 lines) and `transcript_distill`
(before .wiki/log.md updates / session summaries). Description 814 chars.

project-bootstrap (1.5.0 -> 1.6.0, MINOR — capability added):
* assets/CLAUDE.md.template: insert `delegate to interns when allowed`
  between `follow project discipline` and `we're on Windows`.
* SKILL.md Step 5: same insertion in inline template + new commentary
  paragraph explaining the trigger, no-op semantics, install pointer.
* SKILL.md Step 5.5: bootstrap-manifest table extended with
  `setup-interns`, `using-interns`, `project-discipline` rows.
* README.md: Workflow Step 5.5 description + See also section both pick up
  the new skills.

Root CLAUDE.md dogfood: `delegate to interns when allowed` line added.
.wiki/log.md decision entry. .tasks/STATUS.md task moved to 🟢 done.
.tasks/interns-skills-mvp.md per-task file with goal / key-files /
decisions log / open questions.

Build + install verified: `dist/{setup-interns,using-interns,
project-bootstrap}.skill` rebuilt; `bash scripts/install.sh ...` succeeded;
harness skill listing shows full descriptions for all three (no H1
fallback) — confirms the description budget held.

Versioning per project-discipline Rule 3:
* setup-interns: 0.1.0 (first edit of unversioned artifact, MAJOR=0).
* using-interns: 0.1.0 (first edit of unversioned artifact, MAJOR=0).
* project-bootstrap: 1.5.0 -> 1.6.0 (MINOR — adds capability without
  breaking existing CLAUDE.md merge or manifest consumers).

Server runtime itself (`.common/lib/interns-mcp/`) is out of scope for this
task — the skills land lifecycle, policy, and bootstrap integration so any
machine where the MCP server is later installed already has Claude's
policy in place.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
vitya
2026-05-05 17:41:11 +03:00
parent 7464ae4bc4
commit 0eb7dd1d7c
14 changed files with 632 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

74
skills/setup-interns/README.md Normal file
View File

@@ -0,0 +1,74 @@
# setup-interns
One-time skill that brings up the local `interns` MCP server on a new (or freshly broken) machine. Detects the runtime source at `<project-root>/.common/lib/interns-mcp/`, runs `pip install -e`, writes `.common/secrets/interns.env` with the endpoint API keys, and registers `mcpServers.interns` in `~/.claude.json`.
The runtime policy for *using* the resulting tools lives in [`using-interns`](../using-interns/) — `setup-interns` is the only place that touches user-level config or the project's secrets directory.
Full design (Layer 1 / 2 / 3, MVP catalog, always-ask paths, routing hints):
`.wiki/concepts/interns-design.md` (in this repo).
## When it triggers
- User says: "install interns", "set up interns", "configure interns",
"настрой интернов", "установи интернов", "interns не работает",
"interns isn't working".
- [`using-interns`](../using-interns/) detects missing `mcp__interns__*` tools and delegates here via its Prerequisites section.
- A new machine in the multi-machine fleet — install once per machine that wants delegation.
## What it touches
| Path | Role |
|---|---|
| `<project-root>/.common/lib/interns-mcp/` | server source (must already exist; not created here) |
| `<project-root>/.common/config/interns/config.yaml` | catalog of interns + endpoints (read-only here) |
| `<project-root>/.common/secrets/interns.env` | endpoint API keys (gitignored) |
| `~/.claude.json` (`mcpServers.interns`) | MCP registration |
| `pip` site-packages | editable install of `interns_mcp` |
## Hard rules
- **Never auto-mutate.** Phase 1 (discovery) and Phase 2 (plan) always pause for explicit confirmation. A trigger phrase grants permission to inspect, not to run `pip install` or write secrets.
- **Never echo endpoint API keys in chat.** Edit / Write tool calls inevitably contain them (that's how they land in `.env`); chat output must not.
- **Never run on absent source.** If `.common/lib/interns-mcp/pyproject.toml` is missing, stop and tell the user — initializing a fresh runtime is a separate task.
- **Always `chmod 600` `.env` on Linux / macOS.** Token leak otherwise.
- **Pin the absolute Python interpreter path** in `mcpServers.interns.command`. A bare `python` resolves to whatever shadows it on `PATH` at session start.
## Procedure (high-level)
1. **Phase 0** — environment sanity (`python` ≥ 3.11, `pip`, network to endpoints).
2. **Phase 1** — discovery (source / module / config / keys / MCP registration / `.gitignore`).
3. **Phase 2** — plan + confirm. Wait for explicit "ok" / "go" / "поехали".
4. **Phase 3** — backup (`~/.claude.json`, existing `.common/secrets/interns.env`).
5. **Phase 4** — `pip install -e .common/lib/interns-mcp/`.
6. **Phase 5** — write `.common/secrets/interns.env` (per-key, missing-only) + ensure `.gitignore` rule.
7. **Phase 6** — register `mcpServers.interns` in `~/.claude.json` with absolute interpreter path + `cwd`.
8. **Phase 7** — best-effort smoke test (in-session caveat: real verification is after restart).
9. **Phase 8** — restart guidance + final report.
Full procedure with shell snippets and templates lives in [`SKILL.md`](SKILL.md).
## Rollback
1. Stop. Don't fix forward.
2. `cp <file>.bak-<ts> <file>` for `~/.claude.json` and `.common/secrets/interns.env`.
3. Optional: `pip uninstall interns-mcp` to undo the editable install.
4. Restart Claude Code.
5. Confirm `mcp__interns__*` tools are gone (or back to the prior version).
## Install
From the repo root:
```bash
bash scripts/install.sh setup-interns
```
Works on Windows under git-bash, Linux, macOS.
## See also
- [`using-interns`](../using-interns/) — runtime policy + per-session permission grant for the `mcp__interns__*` tools.
- [`setup-projects-meta`](../setup-projects-meta/) — companion pattern, similar 8-phase shape.
- [`setup-context7`](../setup-context7/) — sister setup-skill for the context7 MCP plugin.
- [`project-discipline`](../project-discipline/) — Rule 4 (per-session push grant) is the prior art for the grant mechanism in `using-interns`.
- `.wiki/concepts/interns-design.md` — full architecture spec.