From 1a1d4f15bea2b2109be271c2ef75442cc968a471 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Fri, 21 Aug 2026 16:29:48 +0000 Subject: [PATCH 1/2] docs: document repository-managed sandbox skills The Sandbox skills workflow only covered importing skills from host agent directories. Document adding, listing, updating, and removing repository-managed skills and clarify how imports affect repository updates. Co-Authored-By: Claude --- content/manuals/ai/sandboxes/faq.md | 10 ++- .../manuals/ai/sandboxes/workflows/_index.md | 5 +- .../ai/sandboxes/workflows/agent-skills.md | 81 ++++++++++++++++--- 3 files changed, 80 insertions(+), 16 deletions(-) diff --git a/content/manuals/ai/sandboxes/faq.md b/content/manuals/ai/sandboxes/faq.md index b02ddfb783a..d4a1ff04a02 100644 --- a/content/manuals/ai/sandboxes/faq.md +++ b/content/manuals/ai/sandboxes/faq.md @@ -149,10 +149,12 @@ 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. -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/agent-skills.md) for the -supported directories, mount behavior, and per-sandbox opt-out. +Shared agent skills are the exception. Use `sbx skills add` to install skills +from a Git repository, or run `sbx skills import` to copy skills from supported +host directories. `sbx` keeps the skills in a persistent store shared with +sandboxes. See [Share agent skills](workflows/agent-skills.md) for repository +management, supported host directories, mount behavior, and per-sandbox +opt-out. Keep project-specific skills and other agent configuration in the project itself. This versions the configuration alongside the code. Don't use symlinks diff --git a/content/manuals/ai/sandboxes/workflows/_index.md b/content/manuals/ai/sandboxes/workflows/_index.md index f0b24191ab1..d440602f60a 100644 --- a/content/manuals/ai/sandboxes/workflows/_index.md +++ b/content/manuals/ai/sandboxes/workflows/_index.md @@ -39,8 +39,9 @@ the agent, workspaces, tools, resources, credentials, and ports so contributors can start a consistent environment without reproducing CLI flags and setup steps. See [Sandbox environment files](../configuration/environment-files.md). -You can also import skills from supported host agents into a persistent store -shared with new sandboxes. See [Share agent skills](agent-skills.md). +You can also add skills from Git repositories or import them from supported +host agents into a persistent store shared with new sandboxes. See +[Share agent skills](agent-skills.md). For unattended jobs, use headless authentication and manage the sandbox lifecycle from scripts. See [Run sandboxes in CI](automation.md). diff --git a/content/manuals/ai/sandboxes/workflows/agent-skills.md b/content/manuals/ai/sandboxes/workflows/agent-skills.md index 8efaf6069e1..062aaca9b04 100644 --- a/content/manuals/ai/sandboxes/workflows/agent-skills.md +++ b/content/manuals/ai/sandboxes/workflows/agent-skills.md @@ -2,18 +2,74 @@ title: Share agent skills linkTitle: Agent skills weight: 40 -description: Import skills from supported host agents into a persistent store shared with Docker Sandboxes. -keywords: docker sandboxes, sbx, agent skills, shared skills, claude code, codex, copilot, cursor, droid +description: Add skills from Git repositories or import them from supported host agents into a store shared with Docker Sandboxes. +keywords: docker sandboxes, sbx, agent skills, shared skills, git repository, claude code, codex, copilot, cursor, droid --- -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. +Shared agent skills let you install skills from Git repositories or import +skills from supported agents on your host. `sbx` keeps installed skills in 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. +## Add skills from a repository + +Add every skill from a Git repository: + +```console +$ sbx skills add anthropics/skills +``` + +The repository must contain one or more valid `SKILL.md` files. You can use +GitHub `owner/repository` shorthand or a Git URL, including HTTPS and SSH URLs. + +To add specific skills, use `--skill` with each name or pass a comma-separated +list: + +```console +$ sbx skills add https://github.com/anthropics/skills --skill frontend-design --skill pdf +``` + +When a skill with the same name is already installed, `sbx` prompts before +replacing it. Use `--force` to replace existing skills without prompts. + +## Manage installed skills + +List the skills in the shared store: + +```console +$ sbx skills ls +``` + +Update every skill installed from a repository: + +```console +$ sbx skills update +``` + +To update specific skills, pass one or more names: + +```console +$ sbx skills update frontend-design pdf +``` + +`sbx skills update` only refreshes skills installed with `sbx skills add`. +Skills imported from the host must be imported again or added from a +repository before they can be updated. + +Remove one or more installed skills: + +```console +$ sbx skills rm frontend-design pdf +``` + +Because running agents may be reading installed skills, `sbx` prompts before +removing them. Use `--force` to skip the prompt in scripts. + +## Import skills from the host + Preview the skills that `sbx` finds without copying them: ```console @@ -56,12 +112,17 @@ On Linux, `sbx` uses `$XDG_STATE_HOME/sandboxes/sandboxes/agent-skills` when 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. +again when you want to copy updates from the host. If an import replaces a +repository-installed skill, the imported copy becomes authoritative and +`sbx skills update` no longer refreshes it from the repository. + +## Shared store behavior + +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 +current contents of the store each time they start, so you can install skills before or after creating them. To create a sandbox without the shared store, use `--no-share-skills`: @@ -83,5 +144,5 @@ the option. > 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 +Some agents scan for skills when a session starts. If installed skills don't appear in an existing session, start another agent session. From 45e51b75a8da23a81b70ea03004178e71452a58a Mon Sep 17 00:00:00 2001 From: Codex Date: Thu, 27 Aug 2026 11:39:14 +0000 Subject: [PATCH 2/2] docs: clarify shared skills management --- .../manuals/ai/sandboxes/workflows/agent-skills.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/content/manuals/ai/sandboxes/workflows/agent-skills.md b/content/manuals/ai/sandboxes/workflows/agent-skills.md index 062aaca9b04..2a0bab83928 100644 --- a/content/manuals/ai/sandboxes/workflows/agent-skills.md +++ b/content/manuals/ai/sandboxes/workflows/agent-skills.md @@ -55,9 +55,9 @@ To update specific skills, pass one or more names: $ sbx skills update frontend-design pdf ``` -`sbx skills update` only refreshes skills installed with `sbx skills add`. -Skills imported from the host must be imported again or added from a -repository before they can be updated. +`sbx skills update` only refreshes skills installed with `sbx skills add`. To +refresh a skill imported from the host, run `sbx skills import` again. To manage +it with `sbx skills update`, install it from a repository instead. Remove one or more installed skills: @@ -65,8 +65,8 @@ Remove one or more installed skills: $ sbx skills rm frontend-design pdf ``` -Because running agents may be reading installed skills, `sbx` prompts before -removing them. Use `--force` to skip the prompt in scripts. +`sbx` asks for confirmation before removing skills that running agents may be +using. Use `--force` to skip confirmation in scripts. ## Import skills from the host @@ -113,8 +113,8 @@ 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. If an import replaces a -repository-installed skill, the imported copy becomes authoritative and -`sbx skills update` no longer refreshes it from the repository. +repository-installed skill, `sbx` no longer associates that skill with its +repository, so `sbx skills update` won't refresh it. ## Shared store behavior