You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Add native discovery for skills supplied by Kit image layers. A skill mixin declares com.docker.sandbox/agent-skill@1 with an in-image config.path; its basename becomes the skill-store directory name unless config.name overrides it. Agent workloads and mixins declare discovery destinations with com.docker.sandbox/agent-skills-directory@1. Every selected destination receives every selected bundled skill before workload launch. Filesystem assembly remains the runtime's responsibility.
The new types include Go config readers, strict validation, JSON Schemas, composition rules, artifact checks, and runtime conformance fixtures with fake-adapter mutations. Identical source/name requests collapse, different sources claiming the same effective name fail composition, and existing image or host-store entries cannot be overwritten. Required skills without a destination fail; optional ones are skipped and recorded. Source paths must be literal after publication so the artifact can be checked, while discovery names may use create-time arguments. Registration preserves supporting files and executable permissions and does not execute bundled scripts.
The review-skill example demonstrates a name override and relative reference file. Existing agent examples declare optional discovery directories, and the repository's authoring/migration skills request native registration optionally while retaining their context fallback. Authoring and migration guidance explain the new contracts.
This is additive under RELEASES.md: it introduces new capability types, changes no existing fields or capability versions, and leaves agent-skills@1 host-sharing semantics and schemaVersion: "3" intact. An older runtime refuses a required new capability and skips an optional one under the existing extension rules. Runtimes must implement the new contracts to provide native discovery; this repository supplies the specification, library, publishing validation, and conformance suite.
The Go skill reader exposes the entry label as DisplayName, keeping the embedded skill config's Name unshadowed. The YAML example shows both names and the basename fallback. The existing SPEC-v3 §7/name-display-only statement now explicitly says capability-entry names; its contract and existing coverage are unchanged. Reader tests check that labels do not supply a missing skill-name override.
Normative accounting (all new anchors are covered; no new waivers):
agent-skill@1/name-valid and agent-skill@1/source-literal: descriptor-valid artifact check through Go validation, with schema, expansion, and group tests.
agent-skill@1/content-present: agent-skill-content artifact check, including optional groups and missing/non-file content.
agent-skill@1/exposed: runtime probes for basename naming, explicit override, multiple destinations, content, relative references, and executable permissions; mutations remove, rename, truncate, or corrupt those results, including trailing-newline-only changes to both skill files and supporting content.
agent-skill@1/before-launch: workload-entrypoint snapshot and a late-exposure mutation.
agent-skill@1/no-execution: script side-effect marker and an execution mutation.
agent-skill@1/unavailable: required refusal, optional skip records, and mutations accepting, refusing, or dropping records incorrectly.
agent-skill@1/existing-conflict: image-content collision check plus agent-skill@1/host-conflict, each with an overwrite mutation.
agent-skills-directory@1/destination: bundled and host-shared skills coexist at both discovery paths; a mutation drops the second destination. Host-sharing-off exposure is covered separately by agent-skill@1/exposed.
Validation: task validate, task lint, task test, task test:e2e, and task kit:dev KIT=review-skill / task kit:dev KIT=skills. Runtime behavior is verified against the fake adapter; the Docker Sandboxes runtime suite was not run. Validation at 4a77b65: task validate, task lint, task test:unit, and task test:tck all passed. Mutation tests run their asserted checks through the same runner setup, claim gating, and cleanup, while the conforming baseline still runs every check. This removes repeated unrelated checks that caused the CI ten-minute timeout; the local sandbox suite completed in 29 seconds with all mutation assertions retained. The unclaimed-skill refusal probe now supplies a discovery destination and explicitly skips that branch when destination support is not claimed; a regression verifies the skill-specific refusal independently of other types.
Release note
Kits can declare bundled agent skills with an optional discovery-name override and expose them through agent-declared skill directories.
Declare bundled skill sources separately from agent discovery directories so skills can compose across agents without requesting host-store access. Default discovery names to source basenames and allow an explicit override, while keeping content validation and collision outcomes testable across publishers and runtimes.
Signed-off-by: Christian Dupuis <cd@docker.com>
Reconcile the fixture inventory and mutation maps with environment expansion. Keep bundled source paths literal at publication while allowing final-container environment values to choose discovery names and directories.
Signed-off-by: Christian Dupuis <cd@docker.com>
A create-time discovery name must not hide a malformed source path from authored or published validation. Check the literal source shape before deferring parameterized values, including declarations in optional groups.
Signed-off-by: Christian Dupuis <cd@docker.com>
Check the sentinel script as content at both discovery destinations without executing it. Mutations for missing, corrupted, and non-executable copies prove the exposure check rejects incomplete skill trees.
Signed-off-by: Christian Dupuis <cd@docker.com>
Avoid shadowing AgentSkill.Name with display label
spec/agent_skill.go:27
AgentSkillCapability.Name shadows the embedded AgentSkill.Name, so request.Name returns the display label rather than the effective-name override. This makes the new public reader API easy to consume incorrectly despite embedding the config type; expose the entry label as DisplayName (or store the config under a named field) so the two meanings have distinct selectors.
Command substitution strips trailing newlines from both files, so a runtime can truncate or add trailing newlines in either SKILL.md and still pass the exact-content requirement. Compare the files byte-for-byte, as the probe already does for register.sh.
This issue also appears on line 17 of the same file.
Addressed the latest review summary’s name-shadowing concern in 7ea326a. The two names have distinct roles: entry name is a human-readable capability label; config.name overrides the skill directory basename and participates in skill identity.
The Go reader now exposes the entry label as request.DisplayName, so request.Name is the unshadowed skill config override. AgentSkillName(request.AgentSkill) computes the effective directory name, including the basename fallback. Tests cover an override and an omitted override with a display label present. The capability example now shows both YAML names and the resulting destination path, and SPEC-v3 explicitly scopes its display-only rule to capability-entry names. No descriptor fields or runtime semantics changed.
Validation: task validate, task lint, all unit packages, and focused skill, bundled-skill mutation, and normative-accounting tests passed. The full task test rerun hit the 10-minute sandbox-suite timeout while other suites were active on the host; this is recorded in the PR description. The concern was posted only in the review summary, so there is no new inline thread to resolve; both existing threads remain resolved.
Addressed the review-summary comment about command substitution in 425881a. The exposure probe now uses byte-for-byte comparisons for both SKILL.md files, the reference file, and read.sh, alongside the existing register.sh comparison. The execution check for relative references remains. Added four fake-adapter mutations that append a trailing newline, one per file; all four escaped detection before the fix and are now caught.
Validation at 425881a: task validate, task lint, and the full task test all passed, including the sandbox conformance suite and every fake-adapter mutation. The unclaimed-skill regression also passed, and its inline review thread is resolved.
Each fake-adapter mutation reran the entire conformance suite even though it only asserted failures for its listed requirements. The extra bundled-skill cases pushed the CI job past the default ten-minute Go test timeout. Run each mutation against those checks through the same claim gating, sentinel environment, and cleanup path, and keep the complete conforming baseline and partial-runtime tests.
Signed-off-by: Christian Dupuis <cd@docker.com>
Fixed the CI timeout in 4a77b65. Each mutation had been rerunning the entire conformance suite while asserting only its listed requirements. Mutation runs now select those checks through the same runner setup, claim gating, sentinel environment, and cleanup; the full conforming baseline and all mutation assertions remain. No timeout increase was needed.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Add native discovery for skills supplied by Kit image layers. A skill mixin declares
com.docker.sandbox/agent-skill@1with an in-imageconfig.path; its basename becomes the skill-store directory name unlessconfig.nameoverrides it. Agent workloads and mixins declare discovery destinations withcom.docker.sandbox/agent-skills-directory@1. Every selected destination receives every selected bundled skill before workload launch. Filesystem assembly remains the runtime's responsibility.Closes #79.
The new types include Go config readers, strict validation, JSON Schemas, composition rules, artifact checks, and runtime conformance fixtures with fake-adapter mutations. Identical source/name requests collapse, different sources claiming the same effective name fail composition, and existing image or host-store entries cannot be overwritten. Required skills without a destination fail; optional ones are skipped and recorded. Source paths must be literal after publication so the artifact can be checked, while discovery names may use create-time arguments. Registration preserves supporting files and executable permissions and does not execute bundled scripts.
The
review-skillexample demonstrates a name override and relative reference file. Existing agent examples declare optional discovery directories, and the repository's authoring/migration skills request native registration optionally while retaining their context fallback. Authoring and migration guidance explain the new contracts.This is additive under
RELEASES.md: it introduces new capability types, changes no existing fields or capability versions, and leavesagent-skills@1host-sharing semantics andschemaVersion: "3"intact. An older runtime refuses a required new capability and skips an optional one under the existing extension rules. Runtimes must implement the new contracts to provide native discovery; this repository supplies the specification, library, publishing validation, and conformance suite.The Go skill reader exposes the entry label as
DisplayName, keeping the embedded skill config'sNameunshadowed. The YAML example shows both names and the basename fallback. The existingSPEC-v3 §7/name-display-onlystatement now explicitly says capability-entry names; its contract and existing coverage are unchanged. Reader tests check that labels do not supply a missing skill-name override.Normative accounting (all new anchors are covered; no new waivers):
agent-skill@1/name-validandagent-skill@1/source-literal:descriptor-validartifact check through Go validation, with schema, expansion, and group tests.agent-skill@1/content-present:agent-skill-contentartifact check, including optional groups and missing/non-file content.agent-skill@1/exposed: runtime probes for basename naming, explicit override, multiple destinations, content, relative references, and executable permissions; mutations remove, rename, truncate, or corrupt those results, including trailing-newline-only changes to both skill files and supporting content.agent-skill@1/before-launch: workload-entrypoint snapshot and a late-exposure mutation.agent-skill@1/no-execution: script side-effect marker and an execution mutation.agent-skill@1/unavailable: required refusal, optional skip records, and mutations accepting, refusing, or dropping records incorrectly.agent-skill@1/existing-conflict: image-content collision check plusagent-skill@1/host-conflict, each with an overwrite mutation.agent-skills-directory@1/destination: bundled and host-shared skills coexist at both discovery paths; a mutation drops the second destination. Host-sharing-off exposure is covered separately byagent-skill@1/exposed.Validation:
task validate,task lint,task test,task test:e2e, andtask kit:dev KIT=review-skill/task kit:dev KIT=skills. Runtime behavior is verified against the fake adapter; the Docker Sandboxes runtime suite was not run. Validation at4a77b65:task validate,task lint,task test:unit, andtask test:tckall passed. Mutation tests run their asserted checks through the same runner setup, claim gating, and cleanup, while the conforming baseline still runs every check. This removes repeated unrelated checks that caused the CI ten-minute timeout; the local sandbox suite completed in 29 seconds with all mutation assertions retained. The unclaimed-skill refusal probe now supplies a discovery destination and explicitly skips that branch when destination support is not claimed; a regression verifies the skill-specific refusal independently of other types.Release note