dev-environment

Routes repository commands through devcontainer exec and diagnoses port and worktree failures.

Updated Jan 12, 2026
One-click install
npx skills add https://github.com/brandonarbini/arbini.family --skill dev-environment-brandonarbini
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: dev-environment
Source: https://github.com/brandonarbini/arbini.family/tree/main/.agents/skills/dev-environment
Command: npx skills add https://github.com/brandonarbini/arbini.family --skill dev-environment-brandonarbini

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Developers in this repository run commands in the wrong environment or hit opaque failures: containers built from stale definitions, ports published on the wrong service, worktrees colliding over port ranges, and commits rejected by lint-staged in linked worktrees. This Skill defines exactly where each command runs and how to recover from each named failure. ## Core Features & Use Cases - Command routing: package, build, test, lint, and database commands run via devcontainer exec --workspace-folder ., while git and gh run on the host. - Container lifecycle management: start with devcontainer up, and recreate with --remove-existing-container whenever .devcontainer/ changes or port bindings go stale. - Per-worktree port allocation: initialize.sh derives a host port base from DEV_ENV_PORT, CONDUCTOR_PORT, or a workspace path hash so multiple worktrees run concurrently. - Failure diagnosis: covers EAI_AGAIN on registry requests, "port is already published by", ports that answer nothing, and lint-staged stash failures in linked worktrees. - Use Case: A published port answers nothing after you edited the compose file — the Skill explains that Docker fixes bindings at container creation and tells you to recreate with --remove-existing-container. ## Quick Start Ask the assistant to run the test suite for this repository and it will execute it inside the devcontainer using devcontainer exec.

Frequently Asked Questions about dev-environment

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I run tests or builds inside a devcontainer?▼

Run commands through devcontainer exec --workspace-folder . followed by the command, such as pnpm test or pnpm build. Start the environment first with devcontainer up --workspace-folder ., and never use raw docker compose, which creates conflicting containers.

Why does devcontainer up not pick up my .devcontainer changes?▼

A plain devcontainer up runs docker compose up -d --no-recreate, reusing a container built from the old definition. Recreate it with devcontainer up --workspace-folder . --remove-existing-container whenever anything under .devcontainer/ changed.

Why is my published port not responding in a devcontainer?▼

Docker fixes port bindings at container creation, so an existing container keeps old bindings while the override file claims new ones. Also, the app service uses network_mode service:db, so all host ports publish on the db service, not app.

How do I run multiple git worktrees without port conflicts?▼

The initialize.sh script derives a host port base from DEV_ENV_PORT, then CONDUCTOR_PORT, then a hash of the workspace path, publishing every port at a fixed offset. Set DEV_ENV_PORT to pin a base when another compose project already occupies the range.

Why does every registry request fail with EAI_AGAIN in the container?▼

This happens when a port base was unavailable at startup: Docker rolls back the network endpoint, leaving a running container with no interfaces. Resolve the port conflict or set DEV_ENV_PORT, then recreate the container.

Why does lint-staged reject commits in a linked worktree?▼

lint-staged stashes unstaged changes, and that stash backup fails in a linked worktree with cannot save the current index state. Run pnpm format:write on the changed files yourself, then commit with --no-verify.