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 <noreply@anthropic.com>

Author: dvdksn

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

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).

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.