Proposed spec to share SKILL and "loop"/"Workflow" by OCI registry

A proposed specification defines Agent Loops as portable YAML contracts for orchestrating agentic work, packaged and distributed via OCI Artifacts for versioned, signed, and reproducible execution across registries. The spec aims to replace fragile copy-paste workflows with a standard, registry-agnostic mechanism for sharing agent orchestration definitions.

Version: 0.1.0 Status: Draft Date: 2026-07-16 License: Apache-2.0 This document defines Agent Loops: portable YAML contracts for orchestrating agentic work through declared inputs, phases, actions, completion criteria, outputs, transitions, and escalation rules. It also specifies a standard method for packaging, distributing, signing, discovering, pinning, caching, and executing Agent Loop definitions using OCI Artifacts. It defines the loop document format, execution model, media types, manifest structure, config metadata, annotation conventions, collection indexes, project manifest files, lock files, local cache layout, and supply-chain security expectations required for interoperable loop sharing across any OCI-compliant registry. This specification is inspired by, and intentionally aligned with, the Agent Skills OCI Artifacts Specification. The agentkit CLI is one implementation of this specification; the specification is the source of truth. - Introduction - 1.1 Motivation - 1.2 Design Goals - 1.3 Relationship to Agent Skills OCI Artifacts - 1.4 Notational Conventions - Glossary - Agent Loop Document Format - 3.1 Top-Level Structure - 3.2 Metadata - 3.3 Inputs - 3.4 Dependencies - 3.5 Phases - 3.6 Transitions - 3.7 Escalation - 3.8 Execution Model - Media Types - Individual Loop Artifact - 5.1 OCI Manifest Structure - 5.2 Config Object Schema - 5.3 Layers - 5.4 Annotations - 5.5 Tagging Conventions - Loop Collection Artifact - 6.1 OCI Image Index Structure - 6.2 Collection Annotations - Loops Manifest File - 7.1 Purpose - 7.2 File Location - 7.3 Schema - Lock File - 8.1 Purpose - 8.2 File Location - 8.3 Schema - 8.4 Update Check Workflow - Local Cache and Execution Layout - Supply-Chain Security - Registry Compatibility - Reference Implementation - Future Considerations - Acknowledgments Agent Loops are reusable orchestration contracts for agentic work. A loop definition describes the objective, required inputs, phases, phase actions, completion criteria, outputs, transitions, and escalation policy an agent should follow. The loop format is intentionally file-based and human-readable, centered on a YAML document with apiVersion: agent-loops.dev/v1alpha1 and kind: AgentLoop . Without a standard distribution mechanism, loops are copied between repositories, pasted into prompts, or fetched from Git paths. That works for experimentation, but it becomes fragile once teams need versioned workflows, digest pinning, private registries, provenance, mirroring, and repeatable execution across projects. OCI Artifacts provide a registry-agnostic packaging layer for arbitrary content. They let loop authors publish small, non-container artifacts to registries that organizations already know how to operate, mirror, authenticate, scan, sign, and audit. A loop artifact does not require a container runtime. Clients can use ORAS-compatible libraries to push, pull, inspect, and verify loop packages. - Registry agnostic. Loop artifacts MUST be storable in and retrievable from any OCI-compliant registry without registry-specific extensions. - Content addressable. Every published loop artifact MUST be identifiable by an immutable digest. Tags are convenience pointers; digests are the source of reproducibility. - Transparent packaging. Pulling a loop artifact MUST yield a conforming Agent Loop YAML document. OCI packaging MUST NOT change the loop execution contract defined by this specification. - Inspectable before execution. Clients SHOULD be able to inspect loop metadata from the OCI manifest and config before downloading or executing the YAML layer. - Signable and attestable. It MUST be possible to sign loop artifacts and attach provenance, validation, evaluation, or security attestations using standard OCI referrers. - Deterministic execution. A lock file records the exact digest for each loop and skill dependency so a project can reproduce the same dependency set later. - Minimal client burden. A conforming client needs only OCI Distribution support plus YAML validation against the Agent Loop schema. This specification follows the same architectural pattern as Thomas Vitale's Agent Skills OCI Artifacts Specification https://github.com/ThomasVitale/agents-skills-oci-artifacts-spec : - define a portable agent-facing format first; - use OCI manifests and artifacts only as the distribution layer; - expose useful metadata through config blobs and annotations; - model collections as OCI image indexes; - use project-local manifest and lock files for repeatability; - rely on OCI referrers for signatures and attestations. Agent Loops and Agent Skills are complementary but different primitives. A skill teaches an agent how to perform a class of work. A loop orchestrates a bounded run through phases, inputs, outputs, transitions, and escalation rules. Because the payload semantics differ, loop artifacts SHOULD use their own media types, config schema, annotations, manifest file, and lock file. Clients MAY support both specifications side by side. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. Loop : A YAML document conforming to the Agent Loop schema defined by this specification. Loop Artifact : An OCI Artifact that packages one loop document and metadata. Loop Collection : An OCI Image Index that references a curated set of Loop Artifacts by digest. Loops Manifest : A project-local loops.json file declaring loop dependencies by OCI references. Lock File : A project-local loops.lock.json file recording resolved digests for deterministic pulls and update checks. Orchestrator : The agent or tool responsible for resolving inputs, running phases, recording outputs, following transitions, and escalating decisions. Referrers API : The OCI Distribution API mechanism used to discover signatures, attestations, and other artifacts attached to a loop artifact. An Agent Loop document is a YAML object that conforms to the structure in this section. JSON representations MAY be used by tooling, but YAML is the canonical authoring and interchange format for loop content layers. An Agent Loop document MUST contain: | Field | Type | Required | Description | |---|---|---|---| apiVersion | string | REQUIRED | MUST be agent-loops.dev/v1alpha1 for this specification version. | kind | string | REQUIRED | MUST be AgentLoop . | metadata | object | REQUIRED | Stable identity and human-facing metadata. | spec | object | REQUIRED | Loop objective and declared inputs. | phases | array | REQUIRED | Ordered phase definitions. MUST contain at least one phase. | escalation | object | OPTIONAL | Root escalation policy and required escalation inputs. | metadata MUST contain: | Field | Type | Required | Description | |---|---|---|---| name | string | REQUIRED | Stable machine-readable loop name. | version | string | REQUIRED | Loop version. Semantic versioning is RECOMMENDED. | title | string | REQUIRED | Human-readable title. | description | string | REQUIRED | Human-readable description of the loop purpose. | spec MUST contain: | Field | Type | Required | Description | |---|---|---|---| objective | string | REQUIRED | Overall loop objective. | inputs | object | REQUIRED | Named input definitions required or accepted by the loop. | dependencies | object | OPTIONAL | Other loops and Agent Skills required by this loop. | Each input definition MUST include: | Field | Type | Required | Description | |---|---|---|---| type | string or single-item array | REQUIRED | One of string , number , boolean , object , or an array containing one of those values. | required | boolean | REQUIRED | Whether the orchestrator must resolve the input before execution. | description | string | REQUIRED | Human-readable input description. | spec.dependencies declares external Agent Loops and Agent Skills the orchestrator must make available before executing the loop. Dependencies are part of the loop contract: they describe the capabilities or sub-loops the author expects the orchestrator to have, but they do not inline or vendor those dependencies into the loop document. spec.dependencies MAY contain: | Field | Type | Required | Description | |---|---|---|---| loops | array | OPTIONAL | Agent Loop artifacts required by this loop. | skills | array | OPTIONAL | Agent Skill artifacts required by this loop. | At least one of loops or skills MUST be present when dependencies is defined. Each loop dependency MUST contain: | Field | Type | Required | Description | |---|---|---|---| name | string | REQUIRED | Local dependency name used by the orchestrator. | ref | string | REQUIRED | OCI reference for the dependency. MUST use standard OCI reference syntax with a tag registry/repository:tag , digest registry/repository@<algorithm :<digest , or tag plus digest registry/repository:tag@<algorithm :<digest . | required | boolean | OPTIONAL | Whether execution MUST fail if the dependency cannot be resolved. Defaults to true . | description | string | OPTIONAL | Human-readable reason the dependency is needed. | Loop dependencies MUST resolve to artifacts with artifact type application/vnd.agentloops.loop.v1 . Each skill dependency MUST contain: | Field | Type | Required | Description | |---|---|---|---| name | string | REQUIRED | Local skill name used by the orchestrator. | ref | string | REQUIRED | OCI reference for the dependency. MUST use standard OCI reference syntax with a tag registry/repository:tag , digest registry/repository@<algorithm :<digest , or tag plus digest registry/repository:tag@<algorithm :<digest . | required | boolean | OPTIONAL | Whether execution MUST fail if the dependency cannot be resolved. Defaults to true . | description | string | OPTIONAL | Human-readable reason the skill is needed. | Skill dependencies MUST resolve to artifacts conforming to Thomas Vitale's Agent Skills OCI Artifacts Specification https://github.com/ThomasVitale/agents-skills-oci-artifacts-spec , including the application/vnd.agentskills.skill.v1 artifact type. Example: spec: objective: Deliver a feature safely. inputs: ticket: type: string required: true description: Ticket key or URL. dependencies: loops: - name: review loop engineering ref: ghcr.io/acme/loops/review loop engineering:0.2.0 description: Reusable engineering review loop invoked before publication. skills: - name: github-pr-review ref: ghcr.io/acme/agent-skills/github-pr-review:1.4.0@sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef description: Skill used to inspect and address pull request review feedback. Clients SHOULD resolve dependencies recursively, detect dependency cycles, and fail before execution when a required dependency cannot be resolved, verified, or installed. Resolved dependency digests MUST be recorded in loops.lock.json or an equivalent lock file. Each phase MUST contain: | Field | Type | Required | Description | |---|---|---|---| name | string | REQUIRED | Stable phase identifier. | title | string | REQUIRED | Human-readable phase title. | objective | string | REQUIRED | Phase objective. | actions | array of strings | REQUIRED | Ordered actions for the orchestrator or delegated agents. | completion | array of strings | REQUIRED | Conditions that must be satisfied before leaving the phase. | outputs | array of single-entry objects | REQUIRED | Structured outputs produced by the phase. | transitions | array | OPTIONAL | Conditional transitions to other phases. | Phase names SHOULD be unique within a loop. Clients SHOULD reject loops with duplicate phase names because transitions would be ambiguous. A transition MUST contain: | Field | Type | Required | Description | |---|---|---|---| to | string | REQUIRED | Target phase name. | condition | string | REQUIRED | Natural-language condition for taking the transition. | When a phase has no transition selected, the orchestrator SHOULD proceed to the next phase in declaration order. A transition MAY point to the same phase or an earlier phase to model iteration. escalation defines when and how the orchestrator asks for human input. It MUST contain: | Field | Type | Required | Description | |---|---|---|---| principle | string | REQUIRED | Escalation policy for the loop. | escalation inputs | array | REQUIRED | Structured fields the orchestrator must provide when escalating. | Each escalation input MUST contain name , type , and description . An orchestrator executing an Agent Loop MUST: - Validate the loop document against this specification. - Resolve, verify, and make available all required spec.dependencies , including loop dependencies and Agent Skill dependencies. - Resolve all required spec.inputs before entering the first phase, unless the loop explicitly permits deferred resolution. - Execute phases in declaration order, subject to selected transitions. - Treat phase actions as the work instructions for that phase. - Evaluate completion criteria before leaving a phase. - Record each phase's declared outputs . - Use escalation.principle to decide when a decision cannot be safely inferred. - Keep run evidence separate from the loop definition. The execution model is intentionally orchestration-oriented. The loop describes what an agent must accomplish and record; individual clients decide how to delegate actions to tools, sub-agents, or humans. All media types defined by this specification use the application/vnd.agentloops vendor tree. | Role | Media Type | |---|---| | Artifact type, individual loop | application/vnd.agentloops.loop.v1 | | Config, individual loop | application/vnd.agentloops.loop.config.v1+json | | Content layer, loop YAML | application/vnd.agentloops.loop.content.v1+yaml | | Artifact type, collection index | application/vnd.agentloops.loop.collection.v1 | Implementations MAY read earlier proof-of-concept media types for backwards compatibility, but conforming publishers MUST use the application/vnd.agentloops. media types. A Loop Artifact MUST be represented as an OCI Image Manifest with: mediaType : application/vnd.oci.image.manifest.v1+json artifactType : application/vnd.agentloops.loop.v1 config.mediaType : application/vnd.agentloops.loop.config.v1+json - exactly one required YAML content layer with media type application/vnd.agentloops.loop.content.v1+yaml Example: { "schemaVersion": 2, "mediaType": "application/vnd.oci.image.manifest.v1+json", "artifactType": "application/vnd.agentloops.loop.v1", "config": { "mediaType": "application/vnd.agentloops.loop.config.v1+json", "digest": "sha256:...", "size": 524 }, "layers": { "mediaType": "application/vnd.agentloops.loop.content.v1+yaml", "digest": "sha256:...", "size": 8123, "annotations": { "org.opencontainers.image.title": "implement feature.yml" } } , "annotations": { "io.agentloops.loop.name": "implement feature", "org.opencontainers.image.title": "implement feature", "org.opencontainers.image.description": "Implement Feature from Jira Ticket", "org.opencontainers.image.version": "0.1.0", "org.opencontainers.image.source": "https://github.com/example/loops" } } The config object contains normalized metadata extracted from the loop YAML. A client SHOULD validate that config values match the YAML layer before execution. | Field | Type | Required | Description | |---|---|---|---| schemaVersion | integer | REQUIRED | Config schema version. This document defines 1 . | apiVersion | string | REQUIRED | Loop API version, for example agent-loops.dev/v1alpha1 . | kind | string | REQUIRED | Loop kind, for example AgentLoop . | name | string | REQUIRED | Stable loop name from metadata.name . | version | string | REQUIRED | Loop version from metadata.version . | title | string | REQUIRED | Human-readable title from metadata.title . | description | string | REQUIRED | Description from metadata.description . | inputs | array | REQUIRED | Declared input names with required flags and type descriptors. | dependencies | object | OPTIONAL | Summary of declared loop and skill dependencies. | phases | array | REQUIRED | Phase names in declaration order. | hasEscalation | boolean | REQUIRED | Whether the loop declares root escalation policy. | annotations | object | OPTIONAL | Tool-specific metadata. | Example: { "schemaVersion": 1, "apiVersion": "agent-loops.dev/v1alpha1", "kind": "AgentLoop", "name": "implement feature", "version": "0.1.0", "title": "Implement Feature from Jira Ticket", "description": "Analyse a Jira ticket, implement the requested feature, and iterate until checks pass.", "inputs": { "name": "ticket", "type": "string", "required": true } , "dependencies": { "loops": { "name": "review loop engineering", "ref": "ghcr.io/acme/loops/review loop engineering:0.2.0" } , "skills": { "name": "github-pr-review", "ref": "ghcr.io/acme/agent-skills/github-pr-review:1.4.0@sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef" } }, "phases": "analyze-ticket", "prepare", "implement", "cyber review", "publish" , "hasEscalation": true } A Loop Artifact MUST contain one YAML content layer. The layer MUST be a valid Agent Loop document. The layer SHOULD be stored as the original .yml or .yaml file without archive wrapping so clients can fetch and cache it directly. Clients MUST reject artifacts with no YAML layer. Clients SHOULD reject artifacts with multiple loop YAML layers unless an implementation-specific selection policy is explicitly configured. Loop annotations use the io.agentloops. namespace. OCI image annotations SHOULD be used for generic metadata. | Annotation Key | Requirement Level | Description | |---|---|---| io.agentloops.loop.name | REQUIRED | Loop name. MUST match config name and YAML metadata.name . | io.agentloops.loop.apiVersion | REQUIRED | Loop API version. | io.agentloops.loop.kind | REQUIRED | Loop kind. | io.agentloops.loop.inputs | OPTIONAL | Comma-separated input names for lightweight discovery. | io.agentloops.loop.phases | OPTIONAL | Comma-separated phase names for lightweight discovery. | io.agentloops.loop.categories | OPTIONAL | Comma-separated categories for browsing. | org.opencontainers.image.title | REQUIRED | Human-readable artifact title. | org.opencontainers.image.description | RECOMMENDED | Loop description. | org.opencontainers.image.version | REQUIRED | Loop version. | org.opencontainers.image.source | RECOMMENDED | Source repository URL. | org.opencontainers.image.revision | RECOMMENDED | Source revision that produced the artifact. | org.opencontainers.image.created | RECOMMENDED | Creation timestamp. | org.opencontainers.image.licenses | OPTIONAL | License expression. | Published loop releases SHOULD be tagged with the loop version: ghcr.io/acme/loops/implement feature:0.1.0 The canonical reproducible reference is digest-pinned: ghcr.io/acme/loops/implement feature@sha256:<digest Tags such as latest , stable , or experimental MAY be used for human convenience, but clients MUST record resolved digests in lock files. A Loop Collection is an OCI Image Index whose manifests reference individual Loop Artifacts by digest. It enables discovery without downloading every loop YAML layer. { "schemaVersion": 2, "mediaType": "application/vnd.oci.image.index.v1+json", "artifactType": "application/vnd.agentloops.loop.collection.v1", "annotations": { "io.agentloops.collection.name": "engineering-loops", "org.opencontainers.image.title": "engineering-loops", "org.opencontainers.image.description": "Reusable engineering loops" }, "manifests": { "mediaType": "application/vnd.oci.image.manifest.v1+json", "artifactType": "application/vnd.agentloops.loop.v1", "digest": "sha256:...", "size": 0, "annotations": { "io.agentloops.loop.name": "implement feature", "io.agentloops.loop.ref": "ghcr.io/acme/loops/implement feature:0.1.0", "org.opencontainers.image.title": "implement feature", "org.opencontainers.image.version": "0.1.0", "org.opencontainers.image.description": "Implement a feature from a ticket." } } } | Annotation Key | Requirement Level | Description | |---|---|---| io.agentloops.collection.name | REQUIRED | Collection name. | org.opencontainers.image.title | REQUIRED | Human-readable title. | org.opencontainers.image.description | RECOMMENDED | Collection description. | org.opencontainers.image.version | RECOMMENDED | Collection version. | org.opencontainers.image.source | RECOMMENDED | Source repository URL. | The loops.json file declares the loop dependencies a project expects agents or tools to use. It is analogous to a dependency manifest. It records desired OCI references, which MAY be mutable tags, immutable digests, or tag plus digest references. The manifest file SHOULD live at the project root: my-project/ loops.json | Field | Type | Required | Description | |---|---|---|---| loops | array | REQUIRED | Declared loop dependencies. | Each loop entry has: | Field | Type | Required | Description | |---|---|---|---| name | string | REQUIRED | Local loop identifier. SHOULD match artifact metadata name. | ref | string | REQUIRED | OCI reference with tag, digest, or tag plus digest. | aliases | array | OPTIONAL | Alternate local names. | requiredInputs | object | OPTIONAL | Project-provided input defaults or bindings. | Example: { "loops": { "name": "implement feature", "ref": "ghcr.io/acme/loops/implement feature:0.1.0" }, { "name": "fix pr ci", "ref": "ghcr.io/acme/loops/fix pr ci:1.2.0@sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef", "aliases": "fix-ci" } } The lock file records exact digests for resolved loop and skill dependencies. Given the same lock file, a client MUST be able to pull the same loop artifacts and Agent Skill artifacts. The lock file SHOULD live beside loops.json : my-project/ loops.json loops.lock.json { "lockfileVersion": 1, "generatedAt": "2026-07-16T00:00:00Z", "loops": { "name": "implement feature", "path": ".agents/loops/implement feature/0.1.0/loop.yml", "compatibilityPath": ".agents/loops/implement feature/loop.yml", "source": { "registry": "ghcr.io", "repository": "acme/loops/implement feature", "tag": "0.1.0", "digest": "sha256:...", "ref": "ghcr.io/acme/loops/implement feature:0.1.0@sha256:..." }, "resolvedAt": "2026-07-16T00:00:00Z" } , "skills": { "name": "github-pr-review", "path": ".agents/skills/github-pr-review/1.4.0", "compatibilityPath": ".agents/skills/github-pr-review", "source": { "registry": "ghcr.io", "repository": "acme/agent-skills/github-pr-review", "tag": "1.4.0", "digest": "sha256:...", "ref": "ghcr.io/acme/agent-skills/github-pr-review:1.4.0@sha256:..." }, "resolvedAt": "2026-07-16T00:00:00Z" } } Clients SHOULD install loops and skills under the selected agent root, commonly .agents/ . When an artifact reference contains a tag, clients SHOULD use that tag as the local version directory: .agents/ loops/<loop-name /<version /loop.yml loops/<loop-name /loop.yml skills/<skill-name /<version /SKILL.md skills/<skill-name /SKILL.md The versioned paths are the authoritative paths for execution. The unversioned paths are compatibility mirrors of the latest pulled version for tools that expect the older layout. When a reference is digest-only, clients SHOULD use a filesystem-safe digest label such as sha256-<digest instead of <version . Lock files MUST record the exact installed path and resolved digest for each loop and skill dependency so orchestrators can select the version required by the loop being executed. - Read loops.lock.json . - Resolve the current digest for each loop or skill ref when the ref contains a tag. - Compare the resolved digest with the locked digest. - Report an available update when the digests differ. - Update the lock file only after pulling, validating, and accepting the new loop or skill artifact. Clients SHOULD cache pulled loop YAML by registry, repository, tag, and digest to avoid accidental reuse of mutable tags. Recommended project-local layout: my-project/ .loop/ cache/ ghcr.io/ acme/ loops/ implement feature/ 0.1.0/ sha256-<digest / loop.yml runs/ yyyy/ mm/ dd/ hh/ mm/ run.json An orchestrator MUST validate the cached YAML against the Agent Loop schema before execution. It SHOULD record run outputs separately from the loop artifact so replay evidence does not mutate the installed loop definition. Loop artifacts can influence agent behavior across repositories and systems. Consumers SHOULD verify provenance before execution, especially for loops that grant agents access to issue trackers, source control, cloud infrastructure, or deployment systems. Publishers SHOULD: - sign loop artifacts with Sigstore Cosign or an equivalent OCI-compatible signing mechanism; - attach provenance attestations describing source repository, revision, build workflow, and schema validation result; - attach optional evaluation attestations describing tested agent behavior; - publish immutable version tags and avoid retagging released versions. Consumers SHOULD: - prefer digest-pinned references for automation; - verify signatures before execution; - validate the YAML layer against the loop schema; - inspect required inputs and escalation policy before starting a run; - treat unsigned public loops as untrusted unless local policy permits them. Loop artifacts MUST be compatible with registries implementing OCI Distribution Spec v1.1 or compatible behavior for non-image artifacts. Implementations SHOULD work with GHCR, ECR, GAR, ACR, Docker Hub, Harbor, Zot, and local OCI registries when those registries permit arbitrary artifact media types. When a registry does not preserve unknown media types, a client MAY fall back to descriptor annotations and YAML file-name detection, but it SHOULD warn that the artifact is not fully conformant. The agentkit CLI is a reference implementation of this specification. It can: - validate Agent Loop YAML; - push a loop YAML file as an OCI artifact with agentkit loop push ; - pull and install a loop artifact with agentkit loop pull ; - render local or remote loop sources as a terminal flowchart; - print agent-facing prime instructions for loop execution. The CLI follows this specification as the source of truth for accepted document and artifact formats. Version constraints : A later revision may define semver ranges and compatibility rules for automatic loop updates. Collections and search : Collection artifacts may grow richer category, owner, compatibility, and quality metadata for registry browsing. Execution attestations : Completed runs may be published as separate referrer artifacts that point back to the loop digest used for the run. Policy gates : Organizations may define policy checks that block unsigned loops, loops with forbidden tools, or loops whose escalation model is too broad. Schema evolution : Future loop API versions should preserve validation and discovery behavior while allowing richer transition logic and typed outputs. This specification builds on the design pattern introduced by Thomas Vitale's Agent Skills OCI Artifacts Specification https://github.com/ThomasVitale/agents-skills-oci-artifacts-spec , the OCI Image and Distribution Specifications, the ORAS project, and Sigstore/Cosign.