A Claude Code Skill that teaches Claude how to use ConTree — Nebius's sandboxed container execution platform with Git-like branching — idiomatically and efficiently.
Tip
Install:
git clone https://github.com/opencolin/contree-skill ~/.claude/skills/contreeThen restart Claude Code. The skill auto-loads when ConTree-related tasks come up.
| File | What's in it |
|---|---|
SKILL.md |
The skill itself — ~400 lines of guidance loaded into Claude when ConTree tasks come up |
README.md (this file) |
Product Requirements Document — the why, who, and how |
references.md |
Every doc, repo, and source consulted during research |
strategy.md |
External market analysis and strategic use-case tiers |
| Product | ConTree Skill for Claude Code |
| Author | Colin (@opencolin) |
| Status | v0.1 — Alpha, seeking feedback from Nebius ConTree team |
| Last updated | 2026-04-16 |
- TL;DR
- The Problem
- Users & Jobs-to-be-Done
- Product Scope
- Solution Design
- Success Metrics
- Dependencies & Risks
- Rollout Plan
- Open Questions for Nebius
- Appendix
Claude Code users who connect the ConTree MCP server get 17 new tools and 10 prompts — but without guidance, Claude tends to misuse them in ways that waste compute and frustrate users (forgetting disposable=false, spawning VMs for ls, re-syncing unchanged files, etc.). This skill is a ~400-line instruction set that progressively discloses ConTree's mental model, workflow patterns, and gotchas to Claude only when the user's intent matches ConTree's use cases. It covers both the MCP server and the Python SDK.
Note
Goal: Make ConTree the default Claude-native answer to "I need to run this safely / in parallel / with rollback" — without the user having to hand-hold Claude through every invocation.
Nebius ships ConTree as three things:
- Managed service — microVM-isolated container runtime with git-like branching
- MCP server (
contree-mcp) — 17 tools + 10 prompts + 7 guides, bundled with a system prompt embedded inapp.pythat teaches the CHECK-PREPARE-EXECUTE pattern - Python SDK (
contree-sdk) — sync and async clients with image/session abstractions
The MCP server's embedded system prompt is excellent, but it only applies inside that MCP session's model context. And in practice, Claude Code users often:
- Don't read long system prompts carefully on every turn
- Confuse MCP tool patterns with generic shell/docker habits
- Miss the subtle distinctions (disposable vs persisted, sessions vs images,
mode="any"cancelling siblings)
Running Claude against the raw MCP tools with no skill, we observed:
| Failure mode | Frequency | Cost |
|---|---|---|
pip install without disposable=false → packages vanish |
🔴 Very common | 1 wasted VM + confused re-runs |
contree_run "ls /app" instead of contree_list_files |
🔴 Very common | 1 wasted VM per inspection |
Re-running contree_rsync before every contree_run |
🟠 Common | Wasted upload bandwidth |
contree_import_image without contree_list_images check |
🟠 Common | Duplicate imports, wasted import VM |
Chaining apt update && apt install && ... && run in one command |
🟠 Common | No rollback on failure, whole thing re-runs |
Mixing up files param direction (UUID vs path) |
🟡 Occasional | Hard-to-debug "file not found" |
wait_operations mode="any" silently cancelling siblings |
🟡 Rare but expensive | Lost work user didn't know was lost |
Important
These aren't Claude being dumb — they're the default behaviors of a model that's been trained on Docker/shell idioms and doesn't know ConTree's specific model.
Claude Code Skills are loaded progressively based on the user's intent:
| Level | Loaded when | Size |
|---|---|---|
| L1 — Description | Always in context | ~100 words |
| L2 — SKILL.md body | When skill triggers | ~500 lines |
| L3 — Bundled resources | On demand | Unlimited |
A well-tuned description triggers only when the user is actually going to use ConTree — so the full workflow guidance doesn't pollute unrelated conversations. This is the right fit for tool-specific expertise.
"I'm iterating on a coding agent. I need 7,000 preloaded environments, the ability to branch from the same checkpoint, and per-run metrics. My agent does MCTS over patches and I need sibling execution to be cheap."
JTBD: Run thousands of parallel, branchable, VM-isolated executions from a Claude-driven agent loop.
"I asked Claude to 'try a few approaches to fix this bug in parallel' and it made a mess of my working directory. I want it to do that in a sandbox."
JTBD: Get Claude to explore multiple solution paths without touching the host filesystem.
"I'm building an agent that generates untrusted code. I need hardware-level isolation and rollback. I want to write Python, not YAML."
JTBD: Use the ConTree SDK idiomatically from Python, with clear patterns for sessions vs branching.
- MCP guidance — all 17 tools, the CHECK-PREPARE-EXECUTE pattern, tool-cost reference table, parallel execution, branching
- SDK guidance — sync/async clients,
images.use()vs.oci()vs.import_from(), sessions vs images distinction, file handling (list/dict/UploadFileSpec), subprocess-likepopen - Anti-pattern coverage — all 7 failure modes from §2.2, plus
mode="any"cancellation - Setup instructions — for users who don't have ConTree configured yet
- Mental model upfront — the Git analogy is front-loaded so Claude's instincts map correctly
- REST API guidance — MCP and SDK cover 95% of Claude Code usage
- SWE-bench integration (
mini-swe-agentContreeEnvironment) — separate follow-up skill - Workflow-specific bundled scripts — save for v0.2 once we see repeated patterns in evals
- Registry auth UX polish — covered briefly, but a deep dive is separate
- Image lineage / rollback tree visualization
- Not a replacement for the MCP server's embedded system prompt. This skill layers on top of that, providing persistent guidance across model turns.
- Not a ConTree marketing page. The skill is for Claude, not for humans reading docs. The README (this file) is the marketing page.
flowchart TD
U[User message] --> H[Claude Code harness]
H --> L1{"L1: Skill description<br/>always in context"}
L1 -->|Intent match?| Match{Match?}
Match -->|no| Skip[Skip skill]
Match -->|yes| L2["L2: SKILL.md body loads<br/>mental model + patterns<br/>+ anti-patterns + SDK"]
L2 --> Calls["Claude calls contree_* tools<br/>with correct defaults"]
Calls --> MCP[(ConTree MCP server)]
MCP --> Nebius[(Nebius microVMs)]
style L1 fill:#e1f5ff,stroke:#0288d1
style L2 fill:#c8e6c9,stroke:#388e3c
style Calls fill:#fff9c4,stroke:#f57f17
style Skip fill:#ffcdd2,stroke:#c62828
Decision 1: Single SKILL.md, not domain-split references
ConTree's surface area is small enough (17 tools, ~10 concepts) that splitting into references/mcp.md and references/sdk.md would cost more context-switches than it saves. Revisit at v0.2 if the file exceeds 500 lines.
Decision 2: Description-first triggering
The skill description uses a "pushy" style (per skill-creator best practices) and lists specific MCP tool names. This catches both (a) users who explicitly mention ConTree and (b) users whose intent matches ("run this in a sandbox", "try N approaches in parallel") even without the brand name.
Decision 3: Git analogy front-loaded
Every ConTree concept maps cleanly to Git (image = commit, branch = branch, tag = tag, disposable = detached HEAD). Claude already has strong priors about Git, so we lean on them instead of inventing new vocabulary.
Decision 4: Tool-cost table as a memory aid
Claude's biggest non-obvious failure was spawning VMs for free operations. A compact table near the end of the MCP section makes this visually memorable.
Decision 5: Cover SDK even though most users will use MCP
The power-user persona (agent builder) will write Python directly. The SDK section adds ~100 lines but unlocks a separate high-value use case.
| Failure mode (from §2.2) | Skill intervention |
|---|---|
Forgetting disposable=false |
Called out in PREPARE step + top of Common Mistakes |
run for file inspection |
"Inspecting Images (Free, No VM)" section + cost table |
| Re-syncing unchanged files | "Reuse it" emphasized in rsync section |
| Re-importing without checking | CHECK step is step 1 of the core pattern |
| Chaining commands | Explicit anti-pattern in Common Mistakes with reasoning |
files param direction |
Highlighted in both MCP and SDK sections |
mode="any" cancellation |
Explicit callout in wait_operations section |
- Qualitative — Three test prompts (see
evals/) produce outputs where Claude follows CHECK-PREPARE-EXECUTE without prompting - Quantitative — Skill description triggers correctly on ≥90% of should-trigger queries and ≤10% of should-not-trigger queries (per
run_loop.pyoptimizer) - Feedback — Nebius ConTree team reviews and agrees the skill faithfully represents product intent
| Metric | Baseline | Target |
|---|---|---|
| VM-spawn rate per task | TBD | −30% (redirect to list_files/read_file) |
disposable=false correctness on installs |
<50% | ≥95% |
| Branching adoption on "try N" prompts | TBD | ≥80% (parallel wait=false + wait_operations) |
- Distribution — listed in an official Claude Code skill registry, ≥1k installs
- Co-marketing — Nebius links this skill from their Claude Code integration docs
- Telemetry partnership — (with user consent) anonymized metrics on which skill sections get loaded most, feeding back into both skill improvements and ConTree product decisions
- ConTree MCP server (
contree-mcpon PyPI, Apache 2.0) — the skill assumescontree_*tool names. If Nebius renames tools, the skill breaks. - ConTree SDK (
contree-sdkon PyPI, Apache 2.0, currently0.3.0.dev1) — the SDK is pre-alpha. API changes will require skill updates. - Claude Code Skills feature — production in Claude Code 1.x+
| Risk | Likelihood | Mitigation |
|---|---|---|
MCP tool signatures change (e.g., shell default flips) |
🟡 Medium | Version the skill; ship an updater when ConTree does breaking releases |
| SDK breaking API churn (it's pre-alpha) | 🔴 High | Version-pin the SDK section; consider splitting to a reference file that's easy to swap |
| Skill over-triggers on non-ConTree sandboxing (Docker, gVisor) | 🟡 Medium | Description tuning via run_loop.py trigger evals |
| Skill under-triggers when user's intent is obvious | 🟡 Medium | Same — optimize description against both positive and negative eval queries |
| Nebius changes tag prefix convention | 🟢 Low | The convention is advisory, not enforced. Easy to update. |
Phase 0 — Internal alpha (now)
- v0.1 draft pushed to github.com/opencolin/contree-skill
- MCP + SDK integration verified against live ConTree service
- 3 hand-crafted test prompts run against skill vs no-skill baseline
- Eval viewer review cycle with author
Phase 1 — Nebius review (this week)
- PRD (this doc) sent to ConTree PM
- Discussion: is framing accurate? Is there product roadmap this should align with?
- Any failure modes we missed from their internal testing?
Phase 2 — Public alpha (week 2)
- Description optimized with
run_loop.pyagainst 20-query trigger eval - Expand to 10+ test prompts covering edge cases
- Package as
.skillfile, publish release - Nebius links from their docs: "Using ConTree with Claude Code"
Phase 3 — GA (month 2)
- Telemetry on skill usage (opt-in)
- Bundled scripts for high-frequency patterns uncovered in evals
- SWE-bench/mini-swe-agent companion skill
Note
These are the questions I'd most like the ConTree team's input on. Happy to discuss any of them over email or a call.
- Tool naming stability — Is the
contree_*prefix guaranteed? Any plans to change tool names or signatures pre-GA? - SDK stability — When does
contree-sdkleave pre-alpha? Should the skill pin to a specific SDK version range? - Tag convention — Is
{scope}/{purpose}/{base}:{version}Nebius-endorsed or just the MCP server's house style? Would you prefer a different convention? - Anonymous access — Will
i_accept_that_anonymous_access_might_be_rate_limitedstay? Feels like a v0 UX wart we should help users avoid. - Registry auth flow — The browser-popup flow (
registry_token_obtain) is creative but brittle in headless environments. Is aCONTREE_REGISTRY_*env-var path coming? - MCP prompts vs skill — The MCP server already ships 10 prompts. Should the skill steer users toward those (
use the 'prepare-environment' prompt) or encode the same logic directly? Current draft does the latter — open to flipping. - Pricing signal for the model — Would Nebius share the approximate $ cost per VM-hour so the skill can give Claude better intuitions about when to branch aggressively vs. sequentially?
- Co-distribution — Interested in hosting this skill (or a forked/endorsed version) in a
nebius/contree-claude-skillrepo? Happy to transfer.
Click to expand the SKILL.md outline
- Mental model (Git analogy)
- Part 1: MCP usage
- CHECK-PREPARE-EXECUTE pattern
- Local files / rsync
- Free inspection
- Uploads, parallel execution, branching
runparameter reference- MCP prompts/guides pointer
- Tool cost table
- Part 2: SDK usage
- Async vs sync clients
images.use/.oci/.import_from- Sessions vs images
- File handling
- Tagging, subprocess, config
- Common mistakes (aggregated from both)
- Setup (MCP + SDK)
This skill was drafted in an afternoon using Anthropic's skill-creator skill, which scaffolded the structure, helped design test prompts, and will drive the eval/iterate loop.
Source material:
- contree.dev landing page + blog
- docs.contree.dev (MCP, SDK, main docs)
- github.com/nebius/contree-mcp — source read for exact tool signatures
- github.com/nebius/contree-sdk — source read for SDK API shape
Full bibliography in references.md. Discrepancies between docs and source (e.g., run default timeout: 30 in MCP tool vs 60 in backend model) were resolved in favor of the source.
Apache 2.0, matching Nebius's licensing on the underlying MCP server and SDK.
| Author | Colin — @opencolin |
| Issues | github.com/opencolin/contree-skill/issues |
| Nebius PMs | If you'd like to chat, I'm at collin@dabl.club |