Building an E2B Skill Using the Skill-Builder Methodology

Starting Point

User requested: "use the skill builder skill to build an e2b skill for us"

The onbook codebase already had extensive E2B integration — templates, sandbox lifecycle, AI agent tools. The goal was to create a general E2B skill (not onbook-specific) that could guide future E2B work in any project.

Phase 1: Scoped via AskUserQuestion

Before diving in, clarified three key decisions:

1. Purpose: Both general E2B usage AND AI agent integration patterns
2. Languages: TypeScript/JavaScript only (matches current stack)
3. Templates: Yes, include template building workflows

This gave clear boundaries: SDK fundamentals, template building, AI tool patterns — all TypeScript.

Phase 2: Parallel Research Agents

Spawned three background research agents simultaneously to gather current E2B information:

// Agent 1: SDK API
Task(subagent_type="general-purpose", run_in_background=true,
  prompt="Research the current E2B TypeScript/JavaScript SDK API...")

// Agent 2: Template patterns
Task(subagent_type="general-purpose", run_in_background=true,
  prompt="Research E2B template definition and building patterns...")

// Agent 3: AI integration
Task(subagent_type="general-purpose", run_in_background=true,
  prompt="Research how E2B sandboxes integrate with AI agent frameworks...")

While agents ran, read the skill-builder methodology files:

• references/phase-1-discovery.md
• references/phase-2-research.md
• references/phase-3-workflow-design.md
• references/design-patterns.md

Direct E2B Docs Fetch — URL Structure Changed

Tried to fetch E2B docs directly while agents worked:

WebFetch: https://e2b.dev/docs/getting-started/overview → 404
WebFetch: https://e2b.dev/docs/sandbox/overview → 404
WebFetch: https://e2b.dev/docs/template-builder/template-api → 404

All returned 404s. The E2B docs structure had changed. Had to find the current structure:

WebFetch: https://e2b.dev/docs → SUCCESS

Extracted the actual navigation:

• /docs/sandbox (not /docs/sandbox/overview)
• /docs/template/quickstart (not /docs/template-builder/template-api)
• /docs/filesystem/read-write (separate from sandbox)
• /docs/commands/streaming

Existing Codebase as Research Source

Read onbook's E2B implementation while waiting for agents:

// tooling/sandbox/template.ts — Template builder pattern
export const template = Template()
  .fromImage('oven/bun')
  .setEnvs({ ... })
  .runCmd('apt-get install -y git ripgrep fd-find', { user: 'root' })
  .skipCache()
  .gitClone(...)
  .setWorkdir('/home/user/code')
  .runCmd('bun install')
  .setStartCmd('...', waitForPort(6006));

// packages/ai/src/tools/bash/bash.ts — AI tool pattern
execute: async ({ command, run_in_background }, { experimental_context }) => {
  const { sandbox } = experimental_context as AgentContext;
  const result = await sandbox.commands.run(command, {
    background: run_in_background,
    cwd: SANDBOX_WORKDIR,
  });
  return { stdout: result.stdout, stderr: result.stderr, exit_code: result.exitCode };
}

The existing trace file .traces/e2b.md was comprehensive — mental models, lifecycle diagrams, all the key patterns.

Successfully Fetched Docs

Found the correct URLs:

/docs/sandbox → Lifecycle, timeout, auto-pause
/docs/template/quickstart → Build System 2.0, fluent builder API
/docs/filesystem/read-write → sandbox.files.read/write
/docs/commands/streaming → onStdout/onStderr callbacks
/docs/commands/background → background: true, handle.kill()
/docs/sandbox/connect → Sandbox.connect(sandboxId)

Key findings from docs:

Timeout units differ by language:

// JavaScript: milliseconds
const sandbox = await Sandbox.create({ timeoutMs: 60_000 });

// Python: seconds
sandbox = Sandbox.create(timeout=60)

Auto-pause is beta:

const sandbox = await Sandbox.betaCreate(templateId, {
  autoPause: true,
  timeoutMs: 86_400_000, // 24 hours
});

Agent Results

All three agents completed with substantial findings:

Agent abc5469 (SDK API): Complete Sandbox class API, Files API, Commands API, Template builder methods, configuration options, error types.

Agent a1b3ab7 (Templates): Build System 2.0 fluent API, e2b.toml format (legacy), ready conditions (waitForPort, waitForTimeout), versioning limitations (no built-in version control).

Agent a0cd8c7 (AI Integration): experimental_context pattern, tool definitions with Vercel AI SDK, streaming patterns, error handling, sandbox lifecycle in agent context.

Key insight from template research: no version control for templates. Rebuilding overwrites. Workaround is different aliases (my-template-v1, my-template-v2) or storing template IDs in database.

Skill Structure Decision

Following skill-builder methodology:

• Build locally first (./e2b-skill/), copy to ~/.claude/skills/ at end
• SKILL.md under 500 lines
• References for deep API details
• Third-person descriptions

Created:

e2b-skill/
├── SKILL.md              # Main skill file (243 lines)
└── references/
    ├── sandbox-api.md    # Files, commands, lifecycle
    ├── template-api.md   # Builder pattern, build process
    └── ai-integration.md # Vercel AI SDK patterns

SKILL.md Key Sections

Quick Reference table:

| Package | Use Case |
|---------|----------|
| `e2b` | Core SDK - sandbox, files, commands, templates |
| `@e2b/code-interpreter` | Adds `runCode()` for Jupyter-style execution |

Decision tree:

Need code execution? ──► E2B sandbox
         │
         ├─ Custom environment? ──► Build template first
         ├─ Jupyter-style execution? ──► @e2b/code-interpreter
         ├─ AI agent tools? ──► experimental_context pattern
         └─ Multiple sessions? ──► betaCreate with autoPause

Common errors table:

| Error | Cause | Fix |
|-------|-------|-----|
| `TimeoutError` | Sandbox expired | Extend timeout or recreate |
| `NotFoundError` | Sandbox killed/expired | Recreate from template |
| `context deadline exceeded` | Command timeout | Set `timeoutMs: 0` for no limit |

Installation

cp -r /Users/joel/Code/onbook/e2b-skill /Users/joel/.claude/skills/
rm -rf /Users/joel/Code/onbook/e2b-skill  # Clean up local build

Verified: ~/.claude/skills/e2b-skill/SKILL.md exists, 243 lines.

Where We Landed

E2B skill installed at ~/.claude/skills/e2b-skill/ with:

• Core SKILL.md with workflows for setup, sandbox ops, templates, AI integration
• Three reference files for deep API details
• Trigger phrases documented
• Quality checklist for verification

Takeaways

E2B docs URL structure: Don't assume paths. The actual structure is /docs/sandbox, /docs/template/quickstart, etc. — not nested like /docs/sandbox/overview.

Timeout units: JavaScript SDK uses milliseconds (timeoutMs: 60_000), Python uses seconds (timeout=60). Easy to mess up.

Auto-pause is betaCreate: Not a flag on regular create(). Separate method: Sandbox.betaCreate().

Template versioning doesn't exist: No rollback, no tags. Use aliases or store template IDs in database for version management.

Parallel research agents work well: Three agents researching different aspects simultaneously saved significant time vs sequential research.

Build local, copy at end: Following skill-builder advice — building in ./e2b-skill/ then copying to ~/.claude/skills/ meant single permission prompt instead of many.