Agent Skills

A coding agent needs a machine where it can clone a repository, install dependencies, run commands, and return the result. An agent skill gives it a repeatable workflow for doing that on a Devbox. Namespace publishes Devbox skills in namespacelabs/agent-skills. A skill is an instruction pack for coding agents. It gives the agent a repeatable workflow for creating Devboxes, loading source code, running commands, and cleaning up after the task. For a worked example, see Testing with Devboxes and agent skills.

Install the skill

Install the skill in a project when you want the repository to carry the same agent instructions for everyone. Install it globally when you want to use the skill across projects from your own machine.

Project
Global

Run this from the project directory:

npx skills add namespacelabs/agent-skills

Run this once for your local agent setup:

npx skills add namespacelabs/agent-skills --global

Get started with an agent

If you have never used a Devbox before, hand your agent the prompt below. It installs the skill first, so it works even if you skipped the step above, then walks the whole setup: CLI, login, a first Devbox, and how to open a shell in it. You will need to complete the login in your browser when the agent reaches that step.

Agent Prompt

Install the Namespace devboxes agent skill, then use it to set me up:

  npx skills add namespacelabs/agent-skills

Following that skill:

1. Install the Devbox CLI for my operating system, then confirm it works.
2. Log me in to Devbox, then verify that the login succeeded.
3. Create a Devbox for me at size `m`. If we are working in a git repository,
   check that repository out in the Devbox so my code is already there.
4. List my Devboxes, then report the new one's name, its state, and how I can
   open a shell in it.

Do not delete or stop any Devbox that already exists in my workspace.

Use the skill

Once the skill is installed, ask your agent for what you want in plain language and the skill supplies the commands. For anything that acts on your code, start the agent from the repository so it can see the files. The exact behavior depends on the agent and the project.

Log me in
Create a Devbox
Run a command
Run tests
Copy local changes

Agent Prompt

log me in to devbox

Logging in opens a browser. The agent hands that step to you, waits for the command to finish, then verifies the credential.

Agent Prompt

create a devbox for this repo

The agent picks an image and size, checks the repository out, and reports the Devbox name.

Agent Prompt

run `go build ./...` in my devbox and show me the output

The agent uses devbox exec, which retains the output so it can be read again later with devbox logs.

Agent Prompt

run the test suite in a devbox

For larger suites, ask the agent to split the work across multiple Devboxes:

Agent Prompt

run the tests in parallel devboxes

In a typical run, the agent creates one or more Devboxes, copies the relevant source state into them, runs the requested commands, reports the result, and deletes or releases the Devboxes it used.

Agent Prompt

copy my local changes to my devbox

A Devbox with a repository checked out holds the default branch, so the agent aligns it to the same commit as your working tree before applying your uncommitted changes as a patch. Untracked files are uploaded separately, since a diff does not include them.

What the skill covers

The skill instructs the agent on the whole Devbox workflow:

Installing the Devbox CLI and logging in
Creating a Devbox, including picking an image and size
Loading source code and installing toolchains
Running commands with devbox exec, including detached runs and their logs
Sharing web work through devbox.so URLs
Tearing the Devbox down, or leaving it running when work continues

Next Steps

Devbox CLI

Install and authenticate the CLI the skill drives.

Executing Commands

Run commands and read their retained output.

Long Running Tasks

Keep a Devbox alive while an agent works.

Products

Platform

Administration

Install the skill

Get started with an agent

Use the skill

What the skill covers

Next Steps

Devbox CLI

Executing Commands

Long Running Tasks

​Install the skill

​Get started with an agent

​Use the skill

​What the skill covers

​Next Steps

Devbox CLI

Executing Commands

Long Running Tasks

Install the skill

Get started with an agent

Use the skill

What the skill covers

Next Steps