`sbx skills add` and `skills: true`

You keep a pdf skill under ~/.claude/skills on your laptop. Inside a sandbox the agent has its own home directory and never sees it. The shared skills store is the one place you fill, and every sandbox for a supported agent reads it.

When you finish this section, you can fill the store, choose how each sandbox mounts it, and turn the same skills on for docker-agent.

The store

Skill: a directory with a SKILL.md whose metadata an agent reads into its system prompt, and whose body it loads when a task matches.

Shared skills store: the host directory that sbx links into every sandbox for a supported agent. On the recording host it was empty:

{
  "store": "$HOME/Library/Application Support/com.docker.sandboxes/sandboxes/agent-skills",
  "skills": []
}

On Linux the store is ~/.local/state/sandboxes/sandboxes/agent-skills, and on Windows %LOCALAPPDATA%\DockerSandboxes\sandboxes\state\agent-skills. sbx reset clears the shared store.

add, import, ls, rm, and update

sbx skills add <repository> installs from a Git URL or a GitHub owner/repository, and the repository must hold at least one valid SKILL.md file. --skill NAME picks skills by name, repeatable or comma-separated, so sbx skills add anthropics/skills --skill pdf installs one. The capture kit did not record an add, because the step needs GitHub. sbx skills update refreshes only skills that add installed, and sbx skills rm asks before it removes one.

sbx skills import copies skills already installed on the host, checking six directories in order, and the first copy of a duplicate name wins:

The order comes from the help text and the mount targets from the docs. Claude, Codex, Copilot, Cursor, Droid, and OpenCode can use the imported skills. sbx skills import arrived in v0.37.0, and add, update, and rm in v0.42.0.

How a sandbox sees the store

By default, the entries of the store are linked read-only into the skills directory of the agent. The directory itself stays writable, so kits can install skills beside them. The links are made when the container starts. So an edit to an existing skill is live, while a new store entry reaches a running sandbox only on its next start. Removing a skill breaks its link at once.

--skills off|readonly|readwrite on sbx run or sbx create chooses the mode per sandbox, and readwrite mounts the store over the directory so the sandbox's writes are shared. The default is readonly, or the skills.defaultMode setting, which the recording host had at its default (the capture). The three-way flag replaced --no-share-skills in v0.43.0. The capture kit did not list that directory from inside a sandbox, so the link form is not shown.

In a v3 kit the agent declares the path itself, with agent-skills@1, because a runtime cannot know where any agent reads its skills. When mode is left out, a runtime must use readonly. The effective access is the narrower of the host setting and the kit's mode. Raising a path to readwrite is a widening that stops for approval, as the capabilities section explains.

docker-agent and skills: true

docker-agent does not read the store. It scans its own directories, and two of them, ~/.claude/skills/ and ~/.agents/skills/, are also import sources. Docker Agent scans standard directories for SKILL.md files. It adds the name and the description of each skill to the system prompt:

In the agent file, skills: true loads every discovered skill, a list restricts it, and false turns it off. A list item that is local or an http:// or https:// URL is a source, and any other string is a skill name. A name that matches no discovered skill produces a warning at startup and is otherwise ignored. The agent needs the filesystem toolset to read skill files, as the toolsets section lists. context: fork in the front matter of a skill tells the agent to run the skill in an isolated sub-agent.

In a docker-agent sandbox

With docker-agent run --sandbox, the host paths above are invisible from the VM. Docker Agent builds a kit before the sandbox starts and mounts it read-only into the VM at the same path. It copies every SKILL.md that it finds on the host under <kit>/skills/<skill-name>/. Every text file passes a secret redaction step, and --no-kit turns the staging off. The end-to-end section shows the printed summary of what was staged.