Run work inside a dev container. Builds a dev container from a workspace's .devcontainer/ config, executes an AI tool (Copilot, Claude, or AMP) inside the container, and cleans up. Triggers on: dev container, run in container, devcontainer, containerized work.
How this skill is triggered — by the user, by Claude, or both
Slash command
/worktree-devcontainer:dev-containerThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Run work inside a dev container. This skill manages the full lifecycle: container build → AI tool execution → cleanup.
Run work inside a dev container. This skill manages the full lifecycle: container build → AI tool execution → cleanup.
A sub-agent (Copilot, Claude, or AMP) runs inside the dev container to do the actual work. The parent session (you) manages the container lifecycle around it.
When this skill is invoked, gather the following from the user or calling agent:
| Input | Required | Default | Description |
|---|---|---|---|
| Workspace folder | Yes | — | Path to the repo/worktree directory containing .devcontainer/ config |
| Prompt | No | — | Inline instructions for the sub-agent. Free-form text describing the work to do. |
| Plan file | No | — | Path to a file in the repo that describes the work (e.g., a PRD, a plan, a design doc). The sub-agent reads it and executes it. |
| Tool | No | copilot | AI backend to run inside the container: copilot, claude, or amp. |
| Container name | No | Auto-derived from workspace | Name for the dev container instance. |
| Port offset | No | — | Integer for parallel port isolation (API = 3001 + N, Web = 3000 + N). |
| Auto-merge | No | true | Whether to enable auto-merge on the created PR. |
| Create PR | No | true | Whether to create a PR at the end. Set to false if the sub-agent handles PR creation itself. |
At least one of Prompt or Plan file must be provided. They can also be used together — the plan file provides the specification and the prompt provides additional context or instructions.
Validate the workspace folder exists and contains a .devcontainer/ directory:
WORKSPACE_FOLDER="<workspace-folder>"
PROJECT_NAME="$(basename "$WORKSPACE_FOLDER")"
TOOL="<tool>" # copilot, claude, or amp — default: copilot
Auto-derive container name if not provided:
BRANCH_SUFFIX=$(cd "$WORKSPACE_FOLDER" && git rev-parse --abbrev-ref HEAD | sed 's|.*/||')
CONTAINER_NAME="${PROJECT_NAME}-${BRANCH_SUFFIX}"
Validate inputs:
WORKSPACE_FOLDER must exist and contain a .devcontainer/ directory (or .devcontainer.json at root)copilot, claude, ampRun the setup script to build and start the dev container.
On Linux/macOS (bash):
SCRIPT_DIR="${CLAUDE_PLUGIN_ROOT}/skills/dev-container/scripts"
CONTAINER_ID=$("$SCRIPT_DIR/devcontainer-up.sh" \
--workspace "$WORKSPACE_FOLDER" \
--name "$CONTAINER_NAME")
On Windows (PowerShell):
$ScriptDir = "${CLAUDE_PLUGIN_ROOT}\skills\dev-container\scripts"
$ContainerId = & "$ScriptDir\devcontainer-up.ps1" `
-Workspace $WorkspaceFolder `
-Name $ContainerName
The script outputs the container ID as its last line. Capture it for diagnostics.
Construct the prompt for the AI tool running inside the container. The prompt structure depends on whether a plan file, inline prompt, or both are provided.
Base context (always included):
You are working inside a dev container.
The workspace is mounted at /workspaces/<PROJECT_NAME>.
All file paths are relative to this directory.
Port configuration (if port offset provided):
Use these ports for any dev servers:
- API port: <3001 + PORT_OFFSET>
- Web port: <3000 + PORT_OFFSET>
Plan file (if provided):
## Your Plan
Your plan is in the file: <plan_file>
Read it and execute all instructions in it.
Inline prompt (if provided):
## Your Task
<user's original prompt>
If both plan_file and prompt are provided, include both sections. The plan file is the primary specification; the prompt provides additional context.
Closing instructions (always included):
## When Done
- Commit all changes with conventional commit messages
- Push to origin: `git push`
<PR instructions if create_pr is true>
- When everything is complete, output: WORKTREE-COMPLETE
PR instructions (if create_pr is true):
- Create a PR: gh pr create --base main --title "<title>" --body "<body>"
- Enable auto-merge: gh pr merge --auto --squash --delete-branch
On Linux/macOS (bash):
"$SCRIPT_DIR/devcontainer-exec.sh" \
--workspace "$WORKSPACE_FOLDER" \
--tool "$TOOL" \
--prompt "$CONSTRUCTED_PROMPT"
On Windows (PowerShell):
& "$ScriptDir\devcontainer-exec.ps1" `
-Workspace $WorkspaceFolder `
-Tool $Tool `
-Prompt $ConstructedPrompt
The exec script runs the appropriate AI tool command inside the container:
| Tool | Command |
|---|---|
copilot | copilot -p "<prompt>" --allow-all |
claude | claude -p "<prompt>" --allowedTools "edit,write,bash,computer,mcp" --dangerouslySkipPermissions |
amp | amp -p "<prompt>" |
Wait for the exec script to complete. Check:
WORKTREE-COMPLETE signal (confirms the sub-agent finished its work successfully)Always run cleanup, regardless of whether the sub-agent succeeded or failed.
On Linux/macOS (bash):
"$SCRIPT_DIR/devcontainer-down.sh" --workspace "$WORKSPACE_FOLDER" --name "$CONTAINER_NAME"
On Windows (PowerShell):
& "$ScriptDir\devcontainer-down.ps1" -Workspace $WorkspaceFolder -Name $ContainerName
The cleanup script is best-effort — it always exits 0 even if removal partially fails.
<promise>WORKTREE-COMPLETE</promise>| File | Purpose |
|---|---|
scripts/devcontainer-up.sh | Build and start the dev container using @devcontainers/cli |
scripts/devcontainer-up.ps1 | PowerShell equivalent of devcontainer-up.sh |
scripts/devcontainer-exec.sh | Execute an AI tool (copilot/claude/amp) inside the running container |
scripts/devcontainer-exec.ps1 | PowerShell equivalent of devcontainer-exec.sh |
scripts/devcontainer-down.sh | Stop and remove the container (best-effort, always exits 0) |
scripts/devcontainer-down.ps1 | PowerShell equivalent of devcontainer-down.sh |
User says: Run in container: fix the flaky test in tests/integration/auth.test.ts
You would:
.devcontainer/ existsmyapp-maincopilot (default tool) with the fix prompt inside the containerAn orchestrator invokes with:
../myapp-task-status/ (a worktree)docs/prds/prd-2026-03-15-task-status.mdclaudeYou would:
.devcontainer/claude inside the containerThe worktree skill creates a branch and worktree, then the dev-container skill runs the work:
feat/new-api and worktree at ../myapp-new-api/../myapp-new-api/claudemyapp-new-api.devcontainer/ config.devcontainer/ directory (or .devcontainer.json at root). Without it, devcontainer up will fail.copilot, claude, or amp is installed in the dev container's Dockerfile or features.npx claudepluginhub patelr3/agents --plugin worktree-devcontainerCreates and manages multi-repo workspaces for AI coding assistants (Claude Code, Codex) by unifying configs from sibling git repos and supporting worktree-based feature branches.
Configures dev containers and GitHub Codespaces with devcontainer.json schema, features, lifecycle hooks, port forwarding, and VS Code customizations.
Defines standardized development environments or onboards developers by generating setup scripts, container configs, CI workflows, toolchain pins, and dev-setup documents.