Document shared agent skills

content/manuals/ai/sandboxes/architecture.md

@@ -31,9 +31,11 @@ When you create a sandbox, everything inside it persists until you remove it:
 Docker images and containers built or pulled by the agent, installed packages,
 agent state and history, and workspace changes.
 
-Sandboxes are isolated from each other. Each one maintains its own Docker
-daemon state, image cache, and package installations. Multiple sandboxes don't
-share images or layers.
+Each sandbox maintains its own Docker daemon state, image cache, and package
+installations. Multiple sandboxes don't share images or layers. The
+[shared agent skills store](workflows.md#share-agent-skills) is an exception:
+supported agents mount the same host-side store read-write unless you opt out
+when creating the sandbox.
 
 Each sandbox consumes disk space for its VM image, Docker images, container
 layers, and volumes, and this grows as you build images and install packages.

content/manuals/ai/sandboxes/faq.md

@@ -134,9 +134,9 @@ $ echo $BRAVE_API_KEY
 The sandbox itself is the safety boundary. Because agents run inside an
 isolated microVM with [network policies](governance/),
 [credential isolation](security/credentials.md), and no access to your host
-system outside the workspace, the usual reasons for approval prompts (preventing
-destructive commands, network access, file modifications) are handled by the
-sandbox isolation layers instead.
+system outside explicitly shared paths, the usual reasons for approval prompts
+(preventing destructive commands, network access, file modifications) are
+handled by the sandbox isolation layers instead.
 
 If you prefer to re-enable approval prompts, change the permission mode
 inside the session. Most agents let you switch permission modes after
@@ -173,24 +173,19 @@ in-progress task:
 
 ## Why doesn't the sandbox use my user-level agent configuration?
 
-Sandboxes don't pick up user-level agent configuration from your host. This
-includes directories like `~/.claude` for Claude Code or `~/.codex` for Codex,
-where hooks, skills, and other settings are stored. Only project-level
-configuration in the working directory is available inside the sandbox.
+Sandboxes don't import your complete user-level agent configuration. Hooks,
+settings, and other files under directories such as `~/.claude` remain on the
+host. Project-level configuration in the working directory remains available
+inside the sandbox.
 
-To make configuration available in a sandbox, copy or move what you need into
-your project directory before starting a session:
+Shared agent skills are the exception. Run `sbx skills import` to copy skills
+from supported host directories into a persistent store shared with
+sandboxes. See [Share agent skills](workflows.md#share-agent-skills) for the
+supported directories, mount behavior, and per-sandbox opt-out.
 
-```console
-$ cp -r ~/.claude/skills .claude/skills
-```
-
-Don't use symlinks — a sandboxed agent can't follow symlinks to paths outside
-the sandbox.
-
-Collocating skills and other agent configuration with the project itself is a
-good practice regardless of sandboxes. It's versioned alongside the code and
-evolves with the project as it changes.
+Keep project-specific skills and other agent configuration in the project
+itself. This versions the configuration alongside the code. Don't use symlinks
+to host paths because a sandboxed agent can't follow them outside the sandbox.
 
 ## Can I paste images into an agent?
 

content/manuals/ai/sandboxes/security/_index.md

@@ -26,17 +26,23 @@ What crosses the boundary into the VM:
   outbound HTTP requests. The raw credential values never enter the VM.
 - **Network access:** HTTP and HTTPS requests to
   [allowed domains](defaults/) are proxied through the host.
+- **Shared agent skills:** a persistent host-side store is mounted read-write
+  at the agent's skills directory unless you opt out when creating the
+  sandbox. Supported agents in other sandboxes mount the same store.
 
 What crosses the boundary back to the host:
 
 - **Workspace file changes:** visible on your host in real time with the
   default direct mount.
 - **HTTP/HTTPS requests:** sent to allowed domains through the host proxy.
+- **Shared skill changes:** written to the host-side store and visible to other
+  sandboxes that share it.
 
-Everything else is blocked. The agent cannot access your host filesystem
-(outside the workspace), your host Docker daemon, your host network or
-localhost, other sandboxes, or any domain not in the allow list. Raw TCP, UDP,
-and ICMP are blocked at the network layer.
+Outside the workspace and shared skills store, the agent cannot access your
+host filesystem. It also cannot access your host Docker daemon, your host
+network or localhost, or any domain not in the allow list. Sandboxes cannot
+communicate directly over the network. Raw TCP, UDP, and ICMP are blocked at
+the network layer.
 
 ![Sandbox security model showing the hypervisor boundary between the sandbox VM and the host system. The workspace directory is shared read-write. The agent process, Docker Engine, packages, and VM filesystem are inside the VM. Host filesystem, processes, Docker Engine, and network are outside the VM and not accessible. A proxy enforces allow/deny policies and injects credentials into outbound requests.](../images/sbx-security.png)
 
@@ -91,6 +97,14 @@ supply-chain risk, `sbx` restricts kit installs to an allowlist of sources
 that defaults to Docker Hub only. See
 [Restrict kit sources](../customize/kits.md#restrict-kit-sources).
 
+Shared agent skills create a narrow exception to cross-sandbox isolation. The
+store is mounted read-write, so one sandbox can modify instructions or scripts
+that an agent later uses in another sandbox. This doesn't expose the rest of
+the host filesystem or create a direct network path between sandboxes, but it
+does put participating sandboxes in the same trust boundary. See
+[Share agent skills](../workflows.md#share-agent-skills) for details and the
+per-sandbox opt-out.
+
 ## Organization-wide control
 
 On a single developer's machine, security and policy are configured locally —

content/manuals/ai/sandboxes/security/defaults.md

@@ -3,7 +3,7 @@ title: Default security posture
 linkTitle: Defaults
 weight: 15
 description: What a sandbox permits and blocks before you change any settings.
-keywords: docker sandboxes, security defaults, network policy, credentials, sbx
+keywords: docker sandboxes, security defaults, network policy, credentials, shared skills, sbx
 ---
 
 A sandbox created with `sbx run` and no additional flags has the following
@@ -31,6 +31,14 @@ including hidden files, configuration files, build scripts, and Git hooks.
 See [Workspace isolation](isolation.md#workspace-isolation) for what to
 review after an agent session.
 
+## Shared skills defaults
+
+Sandboxes for supported agents mount a persistent shared skills store
+read-write by default. Every sandbox that uses the store can change skills that
+other participating sandboxes may load. Use `--no-share-skills` when creating a
+sandbox to keep it outside this shared trust boundary. See
+[Share agent skills](../workflows.md#share-agent-skills).
+
 ## Credential defaults
 
 No credentials are available to the sandbox unless you provide them using
@@ -52,17 +60,18 @@ The agent runs with full control inside the sandbox VM:
 Everything the agent installs or creates inside the VM, including packages,
 Docker images, and configuration changes, persists across stop and restart
 cycles. When you remove the sandbox with `sbx rm`, the VM and its contents
-are deleted. Only workspace files remain on the host.
+are deleted. Workspace files and the shared skills store remain on the host.
 
 ## What is blocked by default
 
 The following are blocked for all sandboxes and cannot be changed through
 policy configuration:
 
-- Host filesystem access outside the workspace directory
+- Host filesystem access outside explicitly mounted workspaces and the shared
+  skills store
 - Host Docker daemon
 - Host network and localhost
-- Communication between sandboxes
+- Direct network communication between sandboxes
 - Raw TCP, UDP, and ICMP connections
 - Traffic to private IP ranges and link-local addresses
 

content/manuals/ai/sandboxes/security/isolation.md

@@ -20,10 +20,11 @@ processes, files, or resources outside its defined boundaries.
 
 - **Process isolation:** separate kernel per sandbox; processes inside the VM
   are invisible to your host and to other sandboxes
-- **Filesystem isolation:** only your workspace directory is shared with the
-  host. The rest of the VM filesystem persists across restarts but is removed
-  when you delete the sandbox. Symlinks pointing outside the workspace scope
-  are not followed.
+- **Filesystem isolation:** your workspace directory and, for supported agents
+  that haven't opted out, the dedicated [shared skills
+  store](../workflows.md#share-agent-skills) are shared with the host. The rest
+  of the VM filesystem persists across restarts but is removed when you delete
+  the sandbox. Symlinks pointing outside the workspace scope are not followed.
 - **Full cleanup:** when you remove a sandbox with `sbx rm`, the VM and
   everything inside it is deleted
 
@@ -189,7 +190,7 @@ The practical guarantees:
   into your working tree.
 - Concurrent `git` commands on the host and inside the sandbox cannot
   race on a shared `.git/index` or shared refs — there is no shared
-  writable state.
+  writable Git state.
 - Credentials, signing keys, and any settings in your repository's
   `.git/config` stay on the host. The agent's clone has its own
   independent configuration.

content/manuals/ai/sandboxes/usage.md

@@ -187,8 +187,8 @@ shared libraries the agent shouldn't modify:
 $ sbx run claude ~/project-a ~/shared-libs:ro ~/docs:ro
 ```
 
-Each sandbox is completely isolated, so you can also run separate projects
-side-by-side. Remove unused sandboxes when you're done to reclaim disk space:
+You can also run separate projects side-by-side. Remove unused sandboxes when
+you're done to reclaim disk space:
 
 ```console
 $ sbx run claude ~/project-a
@@ -254,6 +254,7 @@ dev server and host-service recipes, see
 
 While a sandbox exists, installed packages, Docker images, configuration
 changes, and command history all persist across stops and restarts. When you
-remove a sandbox, everything inside is deleted — only your workspace files
-remain on your host. To preserve a configured environment, create a
-[custom template](customize/templates.md) or use a [kit](customize/kits.md).
+remove a sandbox, everything inside is deleted. Your workspace files and the
+[shared agent skills store](workflows.md#share-agent-skills) remain on your
+host. To preserve a configured environment, create a [custom
+template](customize/templates.md) or use a [kit](customize/kits.md).

content/manuals/ai/sandboxes/workflows.md

@@ -2,14 +2,96 @@
 title: Workflow patterns
 linkTitle: Workflows
 weight: 30
-description: Workflow patterns for Docker Sandboxes, covering git strategies, local services, authenticated tools, commit signing, and CI integration.
-keywords: docker sandboxes, sbx, workflows, clone mode, git, branches, commit signing, github cli, local services, ci, headless
+description: Workflow patterns for Docker Sandboxes, covering shared agent skills, git strategies, local services, authenticated tools, and CI integration.
+keywords: docker sandboxes, sbx, workflows, agent skills, shared skills, clone mode, git, branches, commit signing, github cli, local services, ci, headless
 ---
 
 Use this page when you need to choose an approach for a specific way of working
 with sandboxes. For command syntax and lifecycle basics, see
 [Usage](usage.md).
 
+## Share agent skills
+
+Shared agent skills make skills from supported agents on your host available
+inside your sandboxes. Importing copies the skills into a persistent store that
+survives sandbox deletion and is shared by default with new sandboxes that run
+a supported agent.
+
+> [!NOTE]
+> Shared agent skills are experimental.
+
+Preview the skills that `sbx` finds without copying them:
+
+```console
+$ sbx skills import --dry-run
+```
+
+The command scans the following directories in order and copies each skill
+subdirectory into the shared store. When the sandbox starts, `sbx` mounts the
+store at the path the agent reads inside the sandbox.
+
+| Agent       | Host source         | Sandbox mount target          |
+| ----------- | ------------------- | ----------------------------- |
+| Claude Code | `~/.claude/skills`  | `/home/agent/.claude/skills`  |
+| Codex       | `~/.agents/skills`  | `/home/agent/.agents/skills`  |
+| Copilot     | `~/.copilot/skills` | `/home/agent/.copilot/skills` |
+| Cursor      | `~/.cursor/skills`  | `/home/agent/.cursor/skills`  |
+| Droid       | `~/.factory/skills` | `/home/agent/.factory/skills` |
+
+All imported skills go into the same store, regardless of their source. If
+more than one source contains a skill with the same directory name, the skill
+from the first source in the table wins and `sbx` warns about the others.
+
+Import the skills:
+
+```console
+$ sbx skills import
+```
+
+The final output reports the shared store path. The default locations are:
+
+| Platform | Shared store path                                                           |
+| -------- | --------------------------------------------------------------------------- |
+| macOS    | `~/Library/Application Support/com.docker.sandboxes/sandboxes/agent-skills` |
+| Linux    | `~/.local/state/sandboxes/sandboxes/agent-skills`                           |
+| Windows  | `%LOCALAPPDATA%\DockerSandboxes\sandboxes\state\agent-skills`               |
+
+On Linux, `sbx` uses `$XDG_STATE_HOME/sandboxes/sandboxes/agent-skills` when
+`XDG_STATE_HOME` is set.
+
+When a skill already exists in the store, `sbx` prompts before replacing it.
+Use `--force` to replace existing skills without prompts. Importing replaces
+the complete skill directory rather than merging files. Run the import command
+again when you want to copy updates from the host. Running `sbx reset` clears
+the shared store.
+
+Sandboxes created with `sbx` version 0.37.0 or later for a supported agent are
+configured to mount the store read-write by default. These sandboxes mount the
+current contents of the store each time they start, so you can import skills
+before or after creating them. To create a sandbox without the shared store,
+use `--no-share-skills`:
+
+```console
+$ sbx run --no-share-skills claude
+```
+
+Upgrading `sbx` does not enable shared skills for sandboxes created with an
+earlier version. Remove and recreate those sandboxes after upgrading. The
+`--no-share-skills` option also only applies when the sandbox is created. To
+turn off shared skills for an existing sandbox, remove it and recreate it with
+the option.
+
+> [!WARNING]
+> The shared skills store is mounted read-write. A sandbox can modify any skill
+> in the store, and another sandbox can later load the modified instructions or
+> run the modified scripts. The store is dedicated sandbox state, so this does
+> not by itself execute the modified skill on your host. It does put every
+> sandbox that shares the store in the same trust boundary. Use
+> `--no-share-skills` to keep a sandbox outside that boundary.
+
+Some agents scan for skills when a session starts. If imported skills don't
+appear in an existing session, start another agent session.
+
 ## Git workflows
 
 Sandboxes support three approaches for working with Git repositories. The