跳到主内容
智客 ZICQ

技能库 智客分类:运维与云 docker-sandboxes-kits

Docker Sandboxes Kits

在写作,验证,包装,签名,或编译多克沙盒套件"spec.yaml"("sbx套件添加/检查/pack/pull/push/sign/validate/核查")时使用这种技能,即使用户只是说他们想要"在沙盒代理件上添加一个工具","建造一个可再使用的沙盒扩展","将套件放入一个登记册",或者"在自己的证书和网络访问中混合". 包括工具包 v2 语法( " 类型:沙盒 " 对 " 类型:混合 " 、 " 样本: " 组合 " 、 " 许可.网络 " 、 " 港口 " 、 " 证书 " apiKey/oath " 、 " 环境 " 、 " 安装 " 安装/启动/文件、 " 数量 " 、 " args " 、 " 扩展 " 、 " mixins " 、 " quires.agent " )、通过`-kit " / " sbx 工具包添加 " 和分配(包装/push/pull/ign/核实/证明).

1081 安装量

官方网址:skills.sh

技能介绍

先看中文介绍;官方 description 原文单独保留,不改写 SKILL.md。

做什么

在写作,验证,包装,签名,或编译多克沙盒套件"spec.yaml"("sbx套件添加/检查/pack/pull/push/sign/validate/核查")时使用这种技能,即使用户只是说他们想要"在沙盒代理件上添加一个工具","建造一个可再使用的沙盒扩展","将套件放入一个登记册",或者"在自己的证书和网络访问中混合". 包括工具包 v2 语法( " 类型:沙盒 " 对 " 类型:混合 " 、 " 样本: " 组合 " 、 " 许可.网络 " 、 " 港口 " 、 " 证书 " apiKey/oath " 、 " 环境 " 、 " 安装 " 安装/启动/文件、 " 数量 " 、 " args " 、 " 扩展 " 、 " mixins " 、 " quires.agent " )、通过`-kit " / " sbx 工具包添加 " 和分配(包装/push/pull/ign/核实/证明).

何时用

这个技能

代理如何加载

按 Agent Skills 渐进披露:启动时只加载 name 与 description(约 100 token);任务匹配后才读入整份 SKILL.md 正文;scripts/、references/、assets/ 仅在需要时再读。 本文件正文结构:Docker Sandboxes: Kits (spec.yaml)、Overview、When to use this skill、Do not use this skill when、Core guidance、`kind: sandbox` vs `kind: mixin` — pick the right one。

文件分析

文件分析:除 SKILL.md 外,正文引用了 references/spec-v2-fields.md、assets/spec-sandbox.yaml、references/kit-distribution-commands.md、references/sources.md、assets/spec-mixin.yaml,属于带资源的技能包,这些文件按需再读。

官方 description(原文)

Use this skill when authoring, validating, packaging, signing, or composing a Docker Sandboxes kit `spec.yaml` (`sbx kit add/inspect/pack/pull/push/sign/validate/verify`), even if the user just says they want to "add a tool to a sandbox agent", "build a reusable sandbox extension", "publish a kit to a registry", or "give a mixin its own credentials and network access". Covers the kit-spec v2 grammar (`kind: sandbox` vs `kind: mixin`, the `sandbox:` block, `permissions.network`, `ports`, `credentials` apiKey/oauth, `environment`, `setup` install/startup/files, `volumes`, `args`, `extends`, `mixins`, `requires.agent`), composition via `--kit`/`sbx kit add`, and distribution (pack/push/pull/sign/verify/provenance).

Docker Sandboxes: Kits (spec.yaml)OverviewWhen to use this skillDo not use this skill whenCore guidance`kind: sandbox` vs `kind: mixin` — pick the right oneThe `sandbox:` block (sandbox kits only)Egress: `permissions.network` — and the all-egress-declared rule`credentials` — what the kit needs, never how the user stores it`setup` — install (once) vs. startup (every start) vs. files (startup-time writes)`volumes` — creation-time only, every volume must set a size`args` — parameterizing a kit

兼容:Requires standalone sbx with sbx kit support and kit-spec schemaVersion "2", not the legacy docker sandbox wrapper. Verified against docker/sandboxes df5c96ba60484fa2c375469dbac912c205da6c37; installed-help version and provenance are in references/sources.md. docker_help does not cover standalone sbx. · 许可:Apache-2.0

来源分类:skills.sh agent-skill

SKILL.md 与 Agent 调用

官方规范 ↗
name
docker-sandboxes-kits
description
Use this skill when authoring, validating, packaging, signing, or composing a Docker Sandboxes kit `spec.yaml` (`sbx kit add/inspect/pack/pull/push/sign/validate/verify`), even if the user just says they want to "add a tool to a sandbox agent", "build a reusable sandbox extension", "publish a kit to a registry", or "give a mixin its own credentials and network access". Covers the kit-spec v2 grammar (`kind: sandbox` vs `kind: mixin`, the `sandbox:` block, `permissions.network`, `ports`, `credentials` apiKey/oauth, `environment`, `setup` install/startup/files, `volumes`, `args`, `extends`, `mixins`, `requires.agent`), composition via `--kit`/`sbx kit add`, and distribution (pack/push/pull/sign/verify/provenance).
compatibility
Requires standalone sbx with sbx kit support and kit-spec schemaVersion "2", not the legacy docker sandbox wrapper. Verified against docker/sandboxes df5c96ba60484fa2c375469dbac912c205da6c37; installed-help version and provenance are in references/sources.md. docker_help does not cover standalone sbx.
许可
Apache-2.0
  1. 发现技能客户端向 Agent 提供名称与描述目录。
  2. 匹配与调用用户指定或任务匹配后,载入 SKILL.md 指令。
  3. 按需加载按步骤读取参考文档、使用脚本与素材。
指令中引用的文件 · 5
  • references/spec-v2-fields.md
  • assets/spec-sandbox.yaml
  • references/kit-distribution-commands.md
  • references/sources.md
  • assets/spec-mixin.yaml

以下路径提取自原文;文件是否齐全请以来源仓库中的完整目录为准。

具体调用语法与可用工具以目标 Agent 客户端为准。 查看调用机制说明 ↗

安装这个技能

Skills CLI ↗

先选择目标 Agent 和安装范围,保留技能包的附属文件,安装后检查客户端能否发现该技能。

该技能引用了附属文件,请从来源获取完整目录;仅复制 SKILL.md 可能缺少依赖。

交给 Agent 安装

复制安装指令给支持 Agent Skills 的代理,确认其中的目标目录与客户端匹配。

把 Agent Skill「docker-sandboxes-kits」安装到我的项目:SKILL.md 原文与官方 description 见 https://zicq.com/zh/skills/skl-7b0adc8e29519bdf-%E5%B5%8C%E5%85%A5%E6%B2%99%E7%9B%92-%E5%A4%B9%E5%AD%90.html
请存为 .cursor/skills/docker-sandboxes-kits/SKILL.md 或 .claude/skills/docker-sandboxes-kits/SKILL.md,frontmatter 的 name 与 description 保持原样,不要改写。
该技能还带 scripts/、references/、assets/ 等文件,请从 https://github.com/docker/skills 取完整目录,不要只建一个 SKILL.md。

GitHub 完整包 ↗

终端安装 · Skills CLI

需要 Node.js 与 npx。先查看仓库技能列表,确认实际名称。

npx skills add 'https://github.com/docker/skills' --list

npx skills add 'https://github.com/docker/skills' --skill 'docker-sandboxes-kits'

CLI 会交互选择目标 Agent,默认安装到项目;用户级安装使用 -g。先通过查看命令核对仓库内容,再用 npx skills list 检查已安装技能。

阅读排版
--- name: docker-sandboxes-kits description: >- Use this skill when authoring, validating, packaging, signing, or composing a Docker Sandboxes kit `spec.yaml` (`sbx kit add/inspect/pack/pull/push/sign/validate/verify`), even if the user just says they want to "add a tool to a sandbox agent", "build a reusable sandbox extension", "publish a kit to a registry", or "give a mixin its own credentials and network access". Covers the kit-spec v2 grammar (`kind: sandbox` vs `kind: mixin`, the `sandbox:` block, `permissions.network`, `ports`, `credentials` apiKey/oauth, `environment`, `setup` install/startup/files, `volumes`, `args`, `extends`, `mixins`, `requires.agent`), composition via `--kit`/`sbx kit add`, and distribution (pack/push/pull/sign/verify/provenance). license: Apache-2.0 compatibility: Requires standalone sbx with sbx kit support and kit-spec schemaVersion "2", not the legacy docker sandbox wrapper. Verified against docker/sandboxes df5c96ba60484fa2c375469dbac912c205da6c37; installed-help version and provenance are in references/sources.md. docker_help does not cover standalone sbx. --- # Docker Sandboxes: Kits (spec.yaml) ## Overview A **kit** is a directory (or ZIP/OCI/git artifact) containing a `spec.yaml` plus an optional `files/` tree. `sbx` composes a kit into a running or about-to-be-created sandbox at `sbx create`/`sbx run --kit`/`sbx env` time or at `sbx kit add` time. This skill owns kit-spec v2 authoring, validation, and distribution — everything under `spec.yaml`'s own grammar — and defers what a kit's declarations *mean at runtime* (credential injection, network enforcement) to `docker-sandboxes-network-credentials`, and the sandboxes a kit is composed into to `docker-sandboxes-lifecycle`. ## When to use this skill Activate this skill when: - The user wants to write, validate, or pack a `spec.yaml` for a `kind: sandbox` (complete agent) or `kind: mixin` (extension) kit. - The user wants a mixin to add a tool, credential, network allowance, or files to an existing built-in agent. - The user wants to publish a kit to (or pull one from) an OCI registry, sign it, or verify a signature/provenance attestation. - The user is debugging a kit-validation error, an argument-substitution error, or `sbx kit add`'s recreate-aware requirement. ## Do not use this skill when Do not use this skill when: - The task is creating/running/removing the sandbox a kit is composed into, independent of the kit's own content — use `docker-sandboxes-lifecycle`. - The task is what a credential or network rule a kit declares actually does at runtime (proxy injection, allow/deny precedence, or what the CURRENT network/global policy already permits), or is about secrets/ policy that have nothing to do with a kit — use `docker-sandboxes-network-credentials`. - The task is the `sbxenv.yaml` file format that references kits via its own `kits:` block — use `docker-sandboxes-env` for that file's schema (this skill still owns what goes inside the referenced kit itself). ## Core guidance ### `kind: sandbox` vs `kind: mixin` — pick the right one - Exactly one `kind: sandbox` kit composes into any sandbox (a complete agent: base image + launch config). Any number of `kind: mixin` kits layer onto it (tools, credentials, network, files). A mixin **must not** declare a `sandbox:` block, `extends:`, or `mixins:`. - Every kit needs `schemaVersion: "2"` (the current clean grammar — no legacy shims), `kind`, and `name` matching `^[a-z0-9]([a-z0-9-]{0,62}[a-z0-9])?$`. **Decoding is strict**: any unrecognized field anywhere is a hard error (e.g. a typo like `permissions.netwrok:`), so a kit that validates has no silent typos. ```yaml schemaVersion: "2" kind: mixin name: extra-egress ``` - Do not redefine a base agent's credential in a mixin: declaring a new `apiKey.name` or `proxyManaged` for the same service fails composition. `shell`, `docker-agent`, and `opencode` already own `github`. An additive routing-only entry (`apiKey.inject`, no name/proxyManaged/oauth, and `required: false`) can extend the base credential instead. OAuth belongs on sandbox kits, never mixins. See `references/spec-v2-fields.md`. Inspect built-in definitions at `sandboxlib/agentkits/agents//spec.yaml` in the pinned source; `sbx kit inspect` takes artifact references, not built-in names. Standalone mixin validation does not test composition. ### The `sandbox:` block (sandbox kits only) - **Required** for `kind: sandbox` (unless the kit `extends:` a parent that already supplies it); **forbidden** for `kind: mixin`. - `image:` is the pre-built base image. `entrypoint:` is the fixed process prefix (`entrypoint[0]` is the binary); `command:` is the mode-specific argument tail — either a bare list (sets `default`, `interactive` falls back to it) or `{default: [...], interactive: [...]}`. For a complete minimal kit, use `assets/spec-sandbox.yaml`, which inherits the embedded shell definition rather than inventing an image or command. - `sandbox.build:` (Dockerfile build) is **accepted but not built by the runtime this release** — a kit that sets `build:` must still set `image:`, or it is rejected at load with an actionable error. - **`extends:` (below) is the simplest way to get a real, working image without inventing one.** A sandbox kit that extends a built-in agent (e.g. `extends: shell`) inherits that agent's real `sandbox.image` and may omit `sandbox:` entirely — see the minimal example asset, which does exactly this rather than naming a made-up image reference. ### Egress: `permissions.network` — and the all-egress-declared rule - `permissions.network.allow`/`deny` are the v2 home for what v1 spelled as top-level `network:`. Enforced shapes include exact host, exact host+port, single-label wildcards (`*.example.com`), multi-label wildcards (`**.example.com`), and CIDR prefixes. Port ranges are not supported by the runtime matcher; use separate exact ports. **Deny wins within domain rules or within CIDR rules.** A decisive domain decision is evaluated before CIDR rules: an allowed hostname is not checked against a CIDR deny for its resolved IP. Do not rely on a CIDR deny alone to block an already-allowed hostname. ```yaml permissions: network: allow: - registry.npmjs.org deny: - telemetry.example.com ``` - **`permissions.network.allow` is additive across a composition, and a kit's own allow list is not the only thing granting a sandbox egress.** The sandbox already carries the base agent's own allow list, plus whatever the *global* or *per-sandbox* network policy (`sbx policy`, independently of any kit) permits — see `docker-sandboxes-network- credentials`. **Removing a host from one kit's `allow` list does not by itself prove that host is blocked** — the global policy defaults (`balanced` allows common package registries and AI services; `allow-all` allows everything) or another composed kit may still permit it. Never claim a host is blocked without checking the actual effective decision with `sbx policy check network --sandbox ` on a real sandbox. - Declare the egress a kit requires explicitly for reproducibility. Credential injection does not itself grant network access. Omitting an allow entry leaves reachability dependent on the existing global/per-sandbox policy; it does not necessarily block the host. Check the effective decision. ### `credentials` — what the kit needs, never how the user stores it - Each entry declares a `service` identity and **where to inject** the resolved value (`apiKey` and/or `oauth`); it never declares *how* the user obtains or stores the credential — that lives in the user's own bindings file, wired through `sbx secret set` (see `docker-sandboxes-network-credentials`). - `apiKey.inject[]` needs a `domain` and either an explicit `header`+ `format` (`format` must contain exactly one `%s`) or the `scheme:` sugar: `scheme: bearer` expands to `Authorization: Bearer %s` (no `username`), `scheme: basic` requires `username` and is mutually exclusive with `format`. **Pick a `service` name no composed base agent already declares** (see the duplicate-service rule above) — see `references/spec-v2-fields.md` for a complete fragment. - `apiKey.proxyManaged: true` sets the in-container env var to the literal `proxy-managed` sentinel rather than leaving it unset; the real value is substituted only by the proxy, on the allow-listed inject domains. - `oauth` needs `tokenEndpoint.host`/`.path` and, unless `passthrough: true`, non-empty `sentinels.accessToken`/`.refreshToken`. `passthrough: true` is a **security downgrade** — the real token reaches the container instead of a sentinel — use it only when the kit's own design requires it and say so in `description`. ### `setup` — install (once) vs. startup (every start) vs. files (startup-time writes) | Block | Command shape | Runs | |---|---|---| | `setup.install[].command` | **string**, via `sh -c` | Once, synchronously, before the agent first launches. Runs for every kit, built-in or not. | | `setup.startup[].command` | **list**, exec-style (no shell) | On **every** container start (create, stop/start, daemon restart, host reboot) — **must be idempotent**. | | `setup.files[]` | file write via shell exec | At container startup; `path` absolute; only `${WORKDIR}` placeholder allowed in `content`. | Optional fragment for the shell kit in `assets/spec-sandbox.yaml`: ```yaml setup: startup: - command: ["sh", "-c", "mkdir -p ~/.my-kit"] files: - path: /home/agent/.my-kit/config.json content: '{"workdir": "${WORKDIR}"}' ``` - **`setup.files` is not the same mechanism as the `files/` directory tree (below).** `setup.files` entries are dynamic, `${WORKDIR}`- substituted writes performed at startup time; the `files/home/` and `files/workspace/` directory tree is a set of **static** files packed alongside `spec.yaml` and copied in at container-create time, and it is specifically the `files/workspace/` half of that tree — not `setup.files` — that is written **after** the workspace is populated (e.g. after an in-container `git clone` under `--clone`). Do not conflate the two: `setup.files` has no "after workspace population" timing guarantee of its own. - All three `setup:` lists **concatenate in `--kit` order** across composed kits. - Default execution users: install as root (`user: "0"`) unless overridden; startup/entrypoint as the agent user (uid `1000`) unless overridden. Root install steps writing under `/home/agent` **must** `chown` it back to `agent:agent`, or later agent-user writes there fail. ### `volumes` — creation-time only, every volume must set a size - Each entry needs an absolute `path:`, optional `type: tmpfs` (RAM-backed; omit/`""` for the default block-backed volume), optional `size:` (byte-size string) and `mode:` (octal). - **Volumes apply only at sandbox-create time** — `sbx kit add` (runtime injection) skips volume changes entirely; a kit that needs one must be present at creation. - **Always set `size:` on a block volume.** An unsized volume inherits a 50 GiB default and costs real host disk immediately (ext4 inode-table zeroing); 512 MiB is the practical floor — below it `mke2fs` switches inode density and the space savings mostly disappear. ### `args` — parameterizing a kit - Declare under top-level `args:` (v2 only — the frozen v1 grammar has no `args` block), each with exactly one of `default`/`required: true`, plus optional `description`/`enum`/`pattern`. Reference with `${{ kit.args.NAME }}` anywhere in `spec.yaml` or `files/`; substitution happens **before** the spec is decoded. Every reference **must** be declared, or loading fails — that is what makes the block a trustworthy list of a kit's inputs. **Quote a placeholder used in a string field** (`VERSION: "${{ kit.args.version }}"`), or an unquoted numeric-looking value decodes as a number and fails to decode into a string field. - Supply values with `--kit-arg name=value` (every kit) or `--kit-arg kitname.name=value` (one kit only), or `--kit-args-file`. **Never pass a secret this way** — `--kit-arg` values are not masked; see `docker-sandboxes-network-credentials`. ### `extends` and `mixins` — composition, not runtime injection - `extends:` resolves only built-in agent names at this pinned release (`shell`, `claude`, etc.). Remote git/OCI parents fail to resolve, even if pinned; the broader format specification is not an implementation guarantee. The minimal asset uses the supported `extends: shell`. - `mixins:` is accepted with a warning but is not applied by this runtime. Use `--kit` or `sbx kit add` for composition. The format's immutable-ref requirements do not make unimplemented remote inheritance work. - Prefer digest/commit-pinned CLI kit references for reproducibility. `--kit` and `sbx kit add` still accept mutable tags/branches; the CLI parser does not enforce this recommendation. - `requires.agent` (mixin-only; **rejected** on `kind: sandbox`) pins the single base agent a mixin is designed for (e.g. Claude-specific env vars). It is well-formedness-checked by the spec library; the actual agent-affinity mismatch is enforced by the composition consumer, not by `sbx kit validate` alone. ### Validating, packaging, and distributing | Command | Purpose | |---|---| | `sbx kit validate REFERENCE [--kit-arg ...]` | Local directory, ZIP, or git reference; OCI is rejected. Schema-only well-formedness check. **Never composes against a base agent** — cannot catch a duplicate-service credential collision or confirm any domain is reachable at runtime. | | `sbx kit inspect REFERENCE [--kit-arg ...] [--json]` | Loads and prints the decoded artifact before composing it, including `--kit-arg` substitution preview. | | `sbx kit pack DIRECTORY [-o OUTPUT.zip]` | Packages a validated directory as a ZIP. | | `sbx kit pull REFERENCE [-o OUTPUT]` | Pulls a kit's raw layer payload from an OCI registry without composing it. | | `sbx kit push DIRECTORY REGISTRY/REPO:TAG [--sign]` | Packages and pushes; every push attaches an unsigned-by-default SLSA provenance attestation. | | `sbx kit provenance REFERENCE [--certificate-identity ...]` | Prints the attestation `push` attached; marked UNSIGNED unless verified against a matching key/identity. | | `sbx kit sign REFERENCE` / `sbx kit verify REFERENCE` | Sigstore sign/verify (keyless by default); prefer `--identity-token-file` over `--identity-token`. | | `sbx kit add SANDBOX REFERENCE [--kit-arg ...]` | Injects a **mixin only** into an existing sandbox at runtime (recreate-aware label required); container-immutable settings (`security.privileged`, `volumes:`) cannot take effect this way. | See `references/kit-distribution-commands.md` for full flag lists and worked examples of each command above. ## Related skills - For the sandboxes a kit is composed into (`sbx create`/`run --kit`, `sbx kit add SANDBOX`), use `docker-sandboxes-lifecycle`. - For what a kit's `credentials:`/`permissions.network:` declarations mean at runtime — proxy injection, allow/deny precedence, the effective policy a sandbox actually has once global/per-sandbox policy is included, where the user stores the actual secret value — use `docker-sandboxes-network-credentials`. - For the `sbxenv.yaml` file whose `kits:`/`agent:` fields reference a kit by this schema, use `docker-sandboxes-env`. ## References - `references/sources.md` — provenance for every rule above (spec package, SPEC-v2.md, help captures, docs URLs). - `references/spec-v2-fields.md` — the complete v2 field table (common fields, sandbox-only fields, mixin-only fields, shared blocks) for lookup without re-reading the full spec. - `references/kit-distribution-commands.md` — full flags and worked examples for `sbx kit validate/inspect/pack/pull/push/provenance/sign/verify/add`. ## Assets - `assets/spec-sandbox.yaml` — a genuine minimal `kind: sandbox` kit that `extends: shell` to inherit a real, working image rather than inventing one. - `assets/spec-mixin.yaml` — a genuine minimal `kind: mixin` kit with no credentials at all (an egress-only extension), which composes cleanly with every built-in agent. ## Checks - `checks/verification.md` — Schema, composition, egress, and kit-add checks (unexecuted integration runbook; isolated `--app-name`, no registry publishing or signing).

相关技能

运维与云

Docker Essentials

用于容器管理,图像操作,调试的基本道克命令和工作流程.

运维与云

Find Skills

从开放的代理技能生态系统中发现并安装技能. 使用时:(1)用户问"我如何做X",X可能拥有现有技能,(2)用户说"为X找到技能"或"是否为X有技能",(3)用户问"你能否做X",X是专门能力,(4)用户想扩展代理能力,(5)用户想搜索工具,模板,或工作流程,(6)用户提到他们希望…

运维与云

Microsoft Foundry

构建,部署,评价,优化,微调,管理微软创始代理,模型,资源最终结束. 用法:铸造、azd ai代理、azd 提供/部署、托管代理脚手架/开发/运行/部署/拖放、即时代理创建、创建代理、更新代理、添加代理工具、援引代理、代理.yaml、评估代理、批量活化、连续活化、持续监测、代理C…

运维与云

Azure Deploy

执行已有.azure/部署计划.md和基础设施文件的ALREADY-PREPARED应用程序的Azure部署。 当用户向 CREATE 请求新应用程序时, 请不要使用此技能 。 这种技能运行了 azd上行, azd 部署, trarraform 应用, 和 az 部署命令带有内置…