How to load Claude Code plugins (skills/agents) in sandbox sessions?

[Crunchyman-ralph]

Question

We're using sandbox-agent (v0.4.2) with the Claude agent in E2B sandboxes. We have Claude Code plugins installed (via enabledPlugins in ~/.claude/settings.json), and the plugin files are present on disk at ~/.claude/plugins/marketplaces/, but the skills from those plugins are not available to the Skill tool when we create a session.

What we've tried

1. enabledPlugins in ~/.claude/settings.json — The plugins are listed and the SKILL.md files exist at ~/.claude/plugins/marketplaces/<plugin>/skills/<skill>/SKILL.md, but they don't appear as invocable skills in the session's system prompt.

2. claude plugins install <plugin> via the CLI binary at ~/.local/share/sandbox-agent/bin/claude — This registers the plugin, but by the time we run it (after SandboxAgent.start()), the session may have already loaded its skill list.

3. sdk.setSkillsConfig() — We tried this but it appears the skills config is separate from the Claude Code plugin system.

4. Symlink workaround — Symlinking plugin skills into the workspace .claude/skills/ directory works because workspace skills are always loaded at session creation. But this feels like a workaround.

What we observed

When asking Claude directly inside the sandbox:

• Only workspace skills (from <cwd>/.claude/skills/) are exposed to the Skill tool
• Plugin marketplace skills (from ~/.claude/plugins/marketplaces/) exist on disk but are NOT injected into the system prompt
• claude plugins list shows "No plugins installed" — the enabledPlugins config is not the same as the plugin install registry

Questions

1. Is there a recommended way to pre-install Claude Code plugins so they're available when createSession() is called?
2. Does the ACP adapter (claude-agent-acp) support Claude Code's plugin loading lifecycle, or does it only support workspace skills?
3. Should we be using sdk.setSkillsConfig() instead of the Claude Code plugin system? If so, does it support GitHub sources for skills?
4. Is there a way to trigger plugin sync/reload after SandboxAgent.start() but before createSession()?

Environment

• sandbox-agent SDK: v0.4.2
• @agentclientprotocol/sdk: v0.16.1
• Agent: claude
• Sandbox: E2B (Firecracker)
• Claude Code binary: ~/.local/share/sandbox-agent/bin/claude

Workaround

Currently we symlink plugin skills into the workspace .claude/skills/ directory after provisioning and before session creation. This works but bypasses the plugin system entirely.

[linear]

RVT-6184

[Crunchyman-ralph]

Update: Found a workaround + root cause

We figured out the full picture. Sharing in case it helps others or informs a fix.

Root cause

The ACP adapter (claude-agent-acp) only initializes ~/.claude/plugins/ when a session is created — it does NOT run Claude Code's plugin install/sync lifecycle. So even with enabledPlugins in settings.json and extraKnownMarketplaces pointing to the right GitHub repos, the plugins are never actually registered in installed_plugins.json. The skills from those plugins are invisible to the Skill tool.

What we tried (didn't work)

• enabledPlugins in ~/.claude/settings.json — Creates marketplace dirs on some templates but doesn't register plugins
• sdk.setSkillsConfig() — Stores config in .sandbox-agent/config/skills.json but doesn't affect Claude Code's skill loading
• Copying SKILL.md files into <cwd>/.claude/skills/ — Works as a fallback but bypasses the plugin system entirely (no agents, hooks, or MCP servers from the plugin)
• claude plugins install before session creation — Fails because ~/.claude/plugins/ doesn't exist yet

What works: Bootstrap session → Plugin install → Real session

// 1. Write valid settings.json with enabledPlugins + extraKnownMarketplaces
await sdk.writeFsFile(
  { path: '/home/user/.claude/settings.json' },
  JSON.stringify(settings, null, 2),
);

// 2. Create a throwaway session — this triggers the ACP adapter to
//    initialize ~/.claude/plugins/ (creates the directory, 
//    known_marketplaces.json, installed_plugins.json)
await sdk.createSession({ agent: 'claude', cwd: '/workspace' });

// 3. NOW the CLI can install plugins — the directory exists
await sdk.runProcess({
  command: '/home/user/.local/share/sandbox-agent/bin/claude',
  args: ['plugins', 'install', 'my-plugin@my-marketplace'],
  cwd: '/home/user',
});

// 4. Create the real session — picks up the installed plugin's
//    skills, agents, hooks, MCP servers
const session = await sdk.resumeOrCreateSession({
  id: 'my-session',
  agent: 'claude',
  sessionInit: { cwd: '/workspace', mcpServers: [] },
});

// Plugin skills are now available as "my-marketplace:skill-name"
await session.prompt([{ type: 'text', text: '/my-marketplace:my-skill args' }]);

Suggestions for the project

1. Docs: Document that ~/.claude/plugins/ is created on first session creation, not on server boot. This is the key timing gotcha — anyone trying to install plugins before session creation will hit the same wall.

2. API improvement: Consider adding a sdk.installPlugin('plugin@marketplace') method that handles the bootstrap internally — create a throwaway session if needed, run the CLI install, then clean up. This would hide the workaround behind a clean API.

3. Alternative: Have the sandbox-agent server create ~/.claude/plugins/ during startup (alongside ~/.claude/settings.json) so claude plugins install works immediately without needing a session first.

Happy to submit a PR for docs or a code change if there's a preferred approach.