[melmennaoui]

Summary

Updates the experimental docker-sandboxes-env skill (0.1.0 → 0.2.0) by adapting sbxenv from docker/sandbox-kit-spec at 75b2696a. docker-sandboxes-env already owns sbxenv.yaml, so this extends that skill instead of adding a second one for the same file.

• Create/update workflow: workspace signals → kit search → composition → kit and environment args → credentials and bindings → pin → checklist. The summary is in SKILL.md; the full procedure is in references/authoring-workflow.md.
• scripts/kits.py (copied unchanged; SHA-256 1ca05d5f…): a live Docker Hub helper for searching kits, summarizing descriptors, upgrading by version order and pinning digests.
• Refreshed for sbx v0.51.0 and the published environment files docs:
  • -f/--force replaces -y/--auto-approve; it approves one run without recording consent.
  • env exec offers to create a missing sandbox interactively, and fails non-interactively.
  • Documents ~/.sbxenv.yaml user defaults, MCP command approval, which changes need a recreate, recovery after lost environment state, and per-command flags.
  • Removes the v2-era "kit spec.yaml" wording.
• references/env-schema-fields.md now covers every top-level field.
• Safety guidance kept: the env-file rename gap, never force-approving untrusted content, no literal secrets, the rememberHostCommands caution, and the destroy-plan recheck after preRemove.
• Evals: Prompt 7 now uses --force. New prompts cover scaffolding (8), upgrading kits (9) and non-interactive exec (10). Prompt 9 has static checks against the helper.
• Offline tests: scripts/test_kits_helper.py covers release ordering, the prerelease gate, update and pin behavior, local-source handling and failure exits. Breaking the version ordering or forcing exit 0 makes the tests fail.

Why a minor bump: owns and use_when gain kit selection and pinning inside sbxenv.yaml. That adds scope; existing routing doesn't change, and the sibling skills already send sbxenv.yaml work here. Maintainers may prefer a major bump.

Verification

• VERSION_CHECK_BASE_SHA=56001ac5… task: 250 unit tests OK; 270 eval checks pass, 0 fail, 23 skipped; version policy and DCO OK; links and verification scripts OK.
• Helper run against live Docker Hub on 2026-11-10 with Python 3.9: search, describe, update, pin, plus missing-repository and connection-failure exits.
• sbx env plan on the asset with sbx v0.51.0 and an isolated app name: the plan renders with the documented <agent>-<workspace-basename> name.

Not verified / limitations

• The runtime steps in checks/verification.md were not run; they need a signed-in sbx and create sandboxes. The env exec exit status 125 for a missing sandbox comes from the help text only.
• No live model evals.
• Known limits of the helper, inherited from the source and documented in references/sources.md:
  • it doesn't check the scheme of URLs the server returns;
  • it treats any reference ending in .zip as local;
  • date-style tags would outrank dotted releases.
• Some kit-side rules (one workload per composition, create-phase-only args on published kits) come from the source skill and helper, not the environment-file docs.
• Some cross-checks used docker/sandboxes 7d55286d, which is internal; public readers can only verify claims against the docs and the help output.

Follow-ups

• docker-sandboxes-lifecycle and docker-sandboxes-network-credentials still mention "kit spec.yaml" (v2 wording). They are not changed here.

[melmennaoui]

Superseded by #130: same commit (789162a) pushed to an upstream branch so the scenario jobs receive the repository secrets (fork PRs don't). Closing.