sha256:0247c537bb3bb66e0da1e41a56676a5ebad05ad1cfc231fc1d03ae09d5b37b51
Last pushed
13 days by cdupuis
Type
Sandbox Kit
Manifest digest
sha256:0247c537bb3bb66e0da1e41a56676a5ebad05ad1cfc231fc1d03ae09d5b37b51
schemaVersion: "3"
displayName: Kit authoring skills
description: The v3 kit authoring and migration skills from docker/sandbox-kit-spec, on disk at /usr/share/kit-skills, with an agent-context entry pointing the agent at them. Layer it onto any workload.
sourceUrl: https://github.com/docker/sandbox-kit-spec
version: 3.0.0
licenses:
- Apache-2.0
kind: mixin
provides:
- kit-skills
capabilities:
- type: com.docker.sandbox/agent-skill@1
optional: true
config:
path: /usr/share/kit-skills/create-kit-v3
- type: com.docker.sandbox/agent-skill@1
optional: true
config:
path: /usr/share/kit-skills/migrate-kit-to-v3
- type: com.docker.sandbox/agent-context@1
optional: true
config:
content: |
## Kit authoring skills
This sandbox carries the Docker sandbox kit skills on disk at
`/usr/share/kit-skills/`. They are ordinary markdown — read them directly.
| Read this | When |
|---|---|
| `/usr/share/kit-skills/create-kit-v3/SKILL.md` | Writing a new kit. Covers workload vs mixin, the descriptor, capabilities, version pinning, and how to verify the result. |
| `/usr/share/kit-skills/create-kit-v3/RECIPES.md` | Writing a kit's content recipe, and the ownership rules an overlay has to satisfy. |
| `/usr/share/kit-skills/migrate-kit-to-v3/SKILL.md` | Porting a kit from the v2 `spec.yaml` grammar. |
| `/usr/share/kit-skills/migrate-kit-to-v3/FIELD-MAPPING.md` | The field-by-field v2 → v3 mapping, and the gotcha list. |
Start with the `SKILL.md` for the task at hand; each links to its own
reference files.
The skills link out to the spec itself — `docs/spec/SPEC-v3.md`, the
capability pages under `docs/spec/capabilities/`, `conformance.md`, and the
`examples/` kits. Those are not on disk, and this sandbox can reach exactly
one place to get them:
```sh
git clone https://github.com/docker/sandbox-kit-spec
```
**That describes this kit's own grant, not the sandbox you are in.** Allow
entries union across a composition, exactly as credentials do below, so
another kit layered in alongside may have opened more of github.com — or all
of it. Do not refuse a `git push` the user asked for on the strength of this
paragraph; try it and believe the boundary's answer. What this kit adds by
itself is reads of that one repository plus the fetch half of git, and its own
entry permits no push.
**This kit contributes no credential of its own**, so on a bare workload the
clone is unauthenticated: it works while the repository is public and fails on
authentication — not on egress — if it is not.
It may still end up authenticated, and that is not this kit's doing.
Credentials union across a composition, and an `inject` rule rewrites requests
at the outbound boundary by **domain** rather than by which process made them,
so another kit contributing a runtime GitHub credential covering `github.com`
authenticates this clone too. A git credential helper configured in the image
does the same. So treat authentication as a property of the composition you
are running in, not something to infer from this kit.
If the clone does fail, the files above remain authoritative for everything
they cover; what you lose is the material they link out to.
Follow the links when a skill defers to the spec rather than guessing at a
rule — the skills summarise, the spec decides.
They are not in an agent skills directory on purpose. A skills directory is
where the host mounts its own shared store, and content shipped there would be
hidden by that mount rather than merged with it — so these live at a path
nothing mounts over, and this note is how you find them.
Two things in them are worth knowing before you need them, because they are
the mistakes that cost the most time:
- **A build proves a recipe ran, not that a kit works.** For a mixin, compose
the built overlay onto a bare base and run the tool. `kit-tck validate` warns
about a symlink the overlay does not resolve by itself, which happens
whenever an installer relocates a launcher without its payload, but only the
composition shows whether the base supplies the target.
- **An overlay states ownership for every directory level it ships**, and its
entries override the base's. `/home` owned by uid 1000 hands away a
directory the kit does not own; `/home/agent` owned by root takes `$HOME`
from the agent user. `kit-tck validate` fails either.
- type: com.docker.sandbox/agent-context@2
optional: true
config:
content: |
## Kit authoring skills
This sandbox carries the Docker sandbox kit skills on disk at
`/usr/share/kit-skills/`. They are ordinary markdown — read them directly.
| Read this | When |
|---|---|
| `/usr/share/kit-skills/create-kit-v3/SKILL.md` | Writing a new kit. Covers workload vs mixin, the descriptor, capabilities, version pinning, and how to verify the result. |
| `/usr/share/kit-skills/create-kit-v3/RECIPES.md` | Writing a kit's content recipe, and the ownership rules an overlay has to satisfy. |
| `/usr/share/kit-skills/migrate-kit-to-v3/SKILL.md` | Porting a kit from the v2 `spec.yaml` grammar. |
| `/usr/share/kit-skills/migrate-kit-to-v3/FIELD-MAPPING.md` | The field-by-field v2 → v3 mapping, and the gotcha list. |
Start with the `SKILL.md` for the task at hand; each links to its own
reference files.
The skills link out to the spec itself — `docs/spec/SPEC-v3.md`, the
capability pages under `docs/spec/capabilities/`, `conformance.md`, and the
`examples/` kits. Those are not on disk, and this sandbox can reach exactly
one place to get them:
```sh
git clone https://github.com/docker/sandbox-kit-spec
```
**That describes this kit's own grant, not the sandbox you are in.** Allow
entries union across a composition, exactly as credentials do below, so
another kit layered in alongside may have opened more of github.com — or all
of it. Do not refuse a `git push` the user asked for on the strength of this
paragraph; try it and believe the boundary's answer. What this kit adds by
itself is reads of that one repository plus the fetch half of git, and its own
entry permits no push.
**This kit contributes no credential of its own**, so on a bare workload the
clone is unauthenticated: it works while the repository is public and fails on
authentication — not on egress — if it is not.
It may still end up authenticated, and that is not this kit's doing.
Credentials union across a composition, and an `inject` rule rewrites requests
at the outbound boundary by **domain** rather than by which process made them,
so another kit contributing a runtime GitHub credential covering `github.com`
authenticates this clone too. A git credential helper configured in the image
does the same. So treat authentication as a property of the composition you
are running in, not something to infer from this kit.
If the clone does fail, the files above remain authoritative for everything
they cover; what you lose is the material they link out to.
Follow the links when a skill defers to the spec rather than guessing at a
rule — the skills summarise, the spec decides.
They are not in an agent skills directory on purpose. A skills directory is
where the host mounts its own shared store, and content shipped there would be
hidden by that mount rather than merged with it — so these live at a path
nothing mounts over, and this note is how you find them.
Two things in them are worth knowing before you need them, because they are
the mistakes that cost the most time:
- **A build proves a recipe ran, not that a kit works.** For a mixin, compose
the built overlay onto a bare base and run the tool. `kit-tck validate` warns
about a symlink the overlay does not resolve by itself, which happens
whenever an installer relocates a launcher without its payload, but only the
composition shows whether the base supplies the target.
- **An overlay states ownership for every directory level it ships**, and its
entries override the base's. `/home` owned by uid 1000 hands away a
directory the kit does not own; `/home/agent` owned by root takes `$HOME`
from the agent user. `kit-tck validate` fails either.
- type: com.docker.sandbox/network-policy@2
config:
runtime:
allow:
- hosts:
- github.com
methods:
- GET
paths:
- /docker/sandbox-kit-spec/**
- /docker/sandbox-kit-spec.git/**
- hosts:
- github.com
methods:
- POST
paths:
- /docker/sandbox-kit-spec/git-upload-pack
- /docker/sandbox-kit-spec.git/git-upload-pack