feat(interns-skills-mvp): ship setup-interns + using-interns v0.1.0; project-bootstrap 1.5.0 -> 1.6.0
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:
191
skills/using-interns/SKILL.md
Normal file
191
skills/using-interns/SKILL.md
Normal file
@@ -0,0 +1,191 @@
|
||||
---
|
||||
name: using-interns
|
||||
version: 0.1.0
|
||||
description: Use when delegating predictable bulk reads or summarization to cheap intern LLMs via the local `interns` MCP server (`mcp__interns__bulk_text_read`, `mcp__interns__transcript_distill`, etc.) so Claude saves Anthropic quota. Activated by `delegate to interns when allowed` in CLAUDE.md or explicit phrases like "use interns", "delegate to an intern", "разреши интернов", "allow interns". Per-session permission grant mirrors `project-discipline` Rule 4: ask-mode default, conversational grant / revoke, always-ask paths for `.env` / secrets / keys / SSH / credentials even with active grant, transitive rule (Claude can't bypass by reading the file itself and forwarding content), session-end reset. Skip for architecture, debugging, auth / payments, final commit messages, or final user-facing text.
|
||||
---
|
||||
|
||||
# Using the `interns` MCP server
|
||||
|
||||
## Overview
|
||||
|
||||
`interns` is a local stdio MCP server that exposes a catalog of cheap-LLM "interns" — DeepSeek, Kimi, Ollama-hosted models, etc. — so Claude can delegate predictable bulk I/O and summarization tasks instead of paying Anthropic quota for them. The pattern (~23× cheaper end-to-end on summarization, ~125× per-call on bulk reads) is sourced from a Reddit thread + Medium follow-up; see `.wiki/concepts/interns-design.md` for the full design and the cost numbers.
|
||||
|
||||
Two MVP interns:
|
||||
|
||||
| Tool | What it does | When to call |
|
||||
|---|---|---|
|
||||
| `mcp__interns__bulk_text_read` | Reads N files end-to-end and answers a focused question with file:line citations. | Claude was about to read 3+ files or one file > 400 lines just to extract context. |
|
||||
| `mcp__interns__transcript_distill` | Compresses a session transcript / log into a structured action list (decisions / open questions / next steps). | Before updating `.wiki/log.md` or producing a session summary. |
|
||||
|
||||
Both currently run on Ollama Cloud (`deepseek-v4-flash`, ~$0.002 / call). Adding a new intern is a config-only change — see `.wiki/concepts/interns-design.md` § "Как добавить нового интерна".
|
||||
|
||||
## Prerequisites
|
||||
|
||||
This skill assumes `mcp__interns__*` tools are available. If they aren't (tools missing from the session, or calls fail with a connection error), the server isn't running for this session. Trigger the **`setup-interns`** skill to `pip install -e` the runtime, write `.common/secrets/interns.env`, and register `mcpServers.interns` in `~/.claude.json`. It's a one-time procedure with confirmation gates.
|
||||
|
||||
## When to use
|
||||
|
||||
- A read that's **bulky and not central to editing**: scanning long config files, log dumps, transcript files, generated docs — anything where Claude would burn input tokens summarizing for itself.
|
||||
- A read across **3+ files** to assemble context.
|
||||
- A read of **one file > 400 lines** that won't be edited.
|
||||
- **Transcript / session distillation** before writing a wiki log entry, summary, or post-mortem.
|
||||
- Any future intern documented in `.common/config/interns/config.yaml` (PDF extraction via Marker, repo packaging via Repomix, JS-rendered web fetches via Firecrawl, etc.) — same trigger / grant rules apply.
|
||||
|
||||
## When NOT to use
|
||||
|
||||
- **Architecture / design decisions.** Cheap models miss subtle trade-offs.
|
||||
- **Debugging.** Cheap models hallucinate in ways that turn a 5-minute fix into a 1-hour wild goose chase.
|
||||
- **Auth / payments / PII / production data / deletion.** Recommendation, not enforced — but obvious.
|
||||
- **Final commit messages, PR descriptions, user-facing answers.** The task explicitly delegated *to* Claude. Don't sub-delegate the deliverable.
|
||||
- **Anything that fits into Claude's own working context cheaply.** A 50-line file to skim is not a delegation candidate; it's just a Read.
|
||||
|
||||
## Per-session permission grant (mirrors `project-discipline` Rule 4)
|
||||
|
||||
The grant mechanism is identical in shape to the push-grant in `project-discipline`. Reuse the same vocabulary so the user doesn't have to learn two policies.
|
||||
|
||||
### Default — ask-mode
|
||||
|
||||
Every session starts in ask-mode. Before the first `mcp__interns__*` call, ask:
|
||||
|
||||
> Я бы делегировал чтение `<files>` интерну `bulk_text_read` (DeepSeek Flash via Ollama Cloud, ~$0.002 за вызов). Ок?
|
||||
|
||||
(or its English equivalent if the user is communicating in English) and wait for explicit `yes` / `да` / `go` / `поехали`. Without confirmation — don't call.
|
||||
|
||||
### Conversational grant
|
||||
|
||||
When the user says any of:
|
||||
|
||||
- "разреши интернов" / "разреши интерна" / "разреши делегировать"
|
||||
- "allow interns" / "use interns freely" / "go ahead with interns"
|
||||
|
||||
— grant the right to call `mcp__interns__*` without further confirmation **for the rest of the session**, subject to always-ask paths below. Acknowledge the grant in one short line ("ок, делегирую интернам без подтверждения, кроме secrets-путей" / "got it, free delegation except secrets").
|
||||
|
||||
### Conversational revoke
|
||||
|
||||
When the user says any of:
|
||||
|
||||
- "отзови интернов" / "снова спрашивай" / "делай сам"
|
||||
- "revoke interns" / "stop using interns" / "ask me again every time"
|
||||
|
||||
— return to ask-mode for the rest of the session. Acknowledge in one short line.
|
||||
|
||||
### Session-end reset
|
||||
|
||||
The next session starts in ask-mode regardless of prior grants. Same reasoning as `project-discipline` Rule 4: a grant is given for the current context (user nearby, attention available), and should not survive a context switch.
|
||||
|
||||
### Always-ask paths (even with active grant)
|
||||
|
||||
These never go to an intern silently, even when delegation is granted:
|
||||
|
||||
- `**/.env`, `**/.env.*`
|
||||
- `**/secrets/**` (including `.common/secrets/`, `~/.config/projects-mcp/`)
|
||||
- `**/credentials*`, `**/credentials.json`
|
||||
- `**/*.key`, `**/*.pem`
|
||||
- `**/.ssh/**`
|
||||
- `**/.aws/credentials`, `**/.aws/config`
|
||||
- `**/.netrc`, `**/.npmrc`, `**/.pypirc`
|
||||
|
||||
The `interns` MCP server enforces this server-side: matched paths return `BlockedByPolicy{path, pattern, reason}` instead of going out to the endpoint. Claude's job: **don't try to bypass** by reading the file with the local `Read` tool and forwarding the content as a string argument. The transitive rule applies — once a file matched, its content stays out of every intern call for the rest of the session unless the user explicitly grants per-path.
|
||||
|
||||
When a path is blocked, ask the user explicitly:
|
||||
|
||||
> Файл `<path>` matched always-ask pattern `<pattern>` (reason: `<reason>`). Передавать интерну на endpoint `<endpoint>` несмотря на это?
|
||||
|
||||
Wait for an explicit per-path "yes". Don't generalize the answer to other paths in the same call.
|
||||
|
||||
### Cost-based always-ask
|
||||
|
||||
Any call with estimated cost > $0.10 (per the `tokens × price_per_M` config in `.common/config/interns/config.yaml`) goes to ask-mode regardless of grant state. Sanity bound — catches a misrouted huge-payload request before it bills.
|
||||
|
||||
## Routing hints (when to pick which intern)
|
||||
|
||||
| Situation | Intern |
|
||||
|---|---|
|
||||
| File > 400 lines, not editing it | `bulk_text_read` |
|
||||
| Need to read 3+ files for context | `bulk_text_read` |
|
||||
| Updating `.wiki/log.md` or session-summary doc | `transcript_distill` |
|
||||
| Compressing a long brainstorm transcript before quoting in a design doc | `transcript_distill` |
|
||||
| (Future interns in `config.yaml`) | per the description in the catalog |
|
||||
|
||||
## Workflow
|
||||
|
||||
```
|
||||
1. Identify the candidate task (read-heavy, bulk, predictable).
|
||||
2. Pick the intern from the routing table.
|
||||
3. Check grant state:
|
||||
• ask-mode → ask before calling
|
||||
• granted → check always-ask paths; if any matched, ask per-path
|
||||
4. Call the intern with `paths` (list of file paths — the server reads them)
|
||||
and `question` (focused, specific).
|
||||
5. Cite the response (file:line refs come from the intern's reply).
|
||||
```
|
||||
|
||||
Don't pass file *contents* as arguments — only paths. The MCP server reads and applies the always-ask matcher before any path content reaches an endpoint. If you forward content yourself, the gate is bypassed and the user can't trust the policy.
|
||||
|
||||
## Tool quick reference
|
||||
|
||||
| Tool | Required args | Optional | Purpose |
|
||||
|---|---|---|---|
|
||||
| `mcp__interns__bulk_text_read` | `paths: list[str]`, `question: str` | `max_tokens: int` | Read N files end-to-end, answer the question with citations. |
|
||||
| `mcp__interns__transcript_distill` | `paths: list[str]`, `question: str` | `max_tokens: int` | Distill transcript / log into structured action list. |
|
||||
|
||||
(Future interns expose tools at `mcp__interns__<intern_id>` as the catalog grows.)
|
||||
|
||||
## Examples
|
||||
|
||||
### Read-bulk delegation
|
||||
|
||||
User: "summarize what these four config files do for the build pipeline."
|
||||
|
||||
```
|
||||
1. Routing → bulk_text_read (4 files, context only).
|
||||
2. Grant state → ask-mode (session start).
|
||||
3. Ask: "Bulk-read these 4 files via bulk_text_read (~$0.002)? Ок?"
|
||||
4. User: "ok"
|
||||
5. Call mcp__interns__bulk_text_read
|
||||
paths: ["build/config.ts", "build/plugins.ts", "build/env.ts", "build/output.ts"]
|
||||
question: "What does each file contribute to the build pipeline? Cite file:line."
|
||||
6. Cite the response. Done.
|
||||
```
|
||||
|
||||
### Always-ask path triggered
|
||||
|
||||
User: "scan all `.env*` files in the repo and tell me which keys are duplicated."
|
||||
|
||||
```
|
||||
1. Routing → bulk_text_read.
|
||||
2. Grant state → granted (user said "allow interns" earlier).
|
||||
3. Path matcher → every input matches `**/.env`. Server returns BlockedByPolicy.
|
||||
4. Ask user: "These are .env files (always-ask). Pass them to bulk_text_read despite the secrets exposure?"
|
||||
5. Wait for explicit per-path yes/no.
|
||||
```
|
||||
|
||||
### Transcript distill
|
||||
|
||||
User: "compress this brainstorm transcript into action items before I ingest it into the wiki."
|
||||
|
||||
```
|
||||
1. Routing → transcript_distill.
|
||||
2. Call mcp__interns__transcript_distill
|
||||
paths: [".meeting-room/.brainstorm/foo.md"]
|
||||
question: "Extract decisions, open questions, and next steps. Output structured markdown."
|
||||
3. Quote the result in the wiki ingest commit.
|
||||
```
|
||||
|
||||
## Common mistakes
|
||||
|
||||
| Mistake | Fix |
|
||||
|---|---|
|
||||
| Calling an intern in ask-mode without asking first | Ask before the first call every session, even for trivial reads. |
|
||||
| Forwarding file *content* instead of *path* | Pass paths. The server reads. The matcher only sees paths. |
|
||||
| Trying to bypass always-ask by reading the file with `Read` and pasting content | Transitive rule — that path stays out of intern calls for the session unless user says otherwise per-path. |
|
||||
| Sub-delegating final deliverables (commit messages, user-facing answers) | Those are Claude's job. Interns are for predictable bulk I/O, not for the answer that ships. |
|
||||
| Using an intern for debugging | Cheap models miss subtle bugs. Pay the Anthropic call for debugging — the savings aren't worth a wrong fix. |
|
||||
| Persistent grant across sessions | The next session resets to ask-mode. By design — same as project-discipline Rule 4. |
|
||||
|
||||
## Red flags
|
||||
|
||||
- "I'll just paste the content as a string arg" → no. The matcher only sees paths. If you're tempted to bypass it, you're about to leak a secret.
|
||||
- "This grant should survive the session" → no. The next session asks again. The grant is bound to the current context where the user is paying attention.
|
||||
- "It's just a small file, why ask?" → small files don't need an intern. Read them yourself. The ask is *because* the call goes to a third-party endpoint, not because of size.
|
||||
- "Estimated cost is fine, $0.08 < $0.10" → still ask if the call is novel or the file set is unfamiliar. The cost gate is a hard ceiling, not the only signal.
|
||||
Reference in New Issue
Block a user