{"slug": "proposed-spec-to-share-skill-and-loop-workflow-by-oci-registry", "title": "Proposed spec to share SKILL and \"loop\"/\"Workflow\" by OCI registry", "summary": "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.", "body_md": "Version: 0.1.0 Status: Draft Date: 2026-07-16 License: Apache-2.0\n\nThis document defines Agent Loops: portable YAML contracts for orchestrating agentic work through declared inputs, phases, actions, completion criteria, outputs, transitions, and escalation rules.\n\nIt 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.\n\nThis specification is inspired by, and intentionally aligned with, the Agent\nSkills OCI Artifacts Specification. The `agentkit`\n\nCLI is one implementation of\nthis specification; the specification is the source of truth.\n\n- Introduction\n- 1.1 Motivation\n- 1.2 Design Goals\n- 1.3 Relationship to Agent Skills OCI Artifacts\n- 1.4 Notational Conventions\n\n- Glossary\n- Agent Loop Document Format\n- 3.1 Top-Level Structure\n- 3.2 Metadata\n- 3.3 Inputs\n- 3.4 Dependencies\n- 3.5 Phases\n- 3.6 Transitions\n- 3.7 Escalation\n- 3.8 Execution Model\n\n- Media Types\n- Individual Loop Artifact\n- 5.1 OCI Manifest Structure\n- 5.2 Config Object Schema\n- 5.3 Layers\n- 5.4 Annotations\n- 5.5 Tagging Conventions\n\n- Loop Collection Artifact\n- 6.1 OCI Image Index Structure\n- 6.2 Collection Annotations\n\n- Loops Manifest File\n- 7.1 Purpose\n- 7.2 File Location\n- 7.3 Schema\n\n- Lock File\n- 8.1 Purpose\n- 8.2 File Location\n- 8.3 Schema\n- 8.4 Update Check Workflow\n\n- Local Cache and Execution Layout\n- Supply-Chain Security\n- Registry Compatibility\n- Reference Implementation\n- Future Considerations\n- Acknowledgments\n\nAgent Loops are reusable orchestration contracts for agentic work. A loop\ndefinition describes the objective, required inputs, phases, phase actions,\ncompletion criteria, outputs, transitions, and escalation policy an agent should\nfollow. The loop format is intentionally file-based and human-readable, centered\non a YAML document with `apiVersion: agent-loops.dev/v1alpha1`\n\nand\n`kind: AgentLoop`\n\n.\n\nWithout 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.\n\nOCI 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.\n\n- Registry agnostic. Loop artifacts MUST be storable in and retrievable from any OCI-compliant registry without registry-specific extensions.\n- Content addressable. Every published loop artifact MUST be identifiable by an immutable digest. Tags are convenience pointers; digests are the source of reproducibility.\n- 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.\n- Inspectable before execution. Clients SHOULD be able to inspect loop metadata from the OCI manifest and config before downloading or executing the YAML layer.\n- Signable and attestable. It MUST be possible to sign loop artifacts and attach provenance, validation, evaluation, or security attestations using standard OCI referrers.\n- 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.\n- Minimal client burden. A conforming client needs only OCI Distribution support plus YAML validation against the Agent Loop schema.\n\nThis specification follows the same architectural pattern as Thomas Vitale's\n[Agent Skills OCI Artifacts Specification](https://github.com/ThomasVitale/agents-skills-oci-artifacts-spec):\n\n- define a portable agent-facing format first;\n- use OCI manifests and artifacts only as the distribution layer;\n- expose useful metadata through config blobs and annotations;\n- model collections as OCI image indexes;\n- use project-local manifest and lock files for repeatability;\n- rely on OCI referrers for signatures and attestations.\n\nAgent 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.\n\nThe 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.\n\nLoop : A YAML document conforming to the Agent Loop schema defined by this specification.\n\nLoop Artifact : An OCI Artifact that packages one loop document and metadata.\n\nLoop Collection : An OCI Image Index that references a curated set of Loop Artifacts by digest.\n\nLoops Manifest\n: A project-local `loops.json`\n\nfile declaring loop dependencies by OCI\nreferences.\n\nLock File\n: A project-local `loops.lock.json`\n\nfile recording resolved digests for\ndeterministic pulls and update checks.\n\nOrchestrator : The agent or tool responsible for resolving inputs, running phases, recording outputs, following transitions, and escalating decisions.\n\nReferrers API : The OCI Distribution API mechanism used to discover signatures, attestations, and other artifacts attached to a loop artifact.\n\nAn 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.\n\nAn Agent Loop document MUST contain:\n\n| Field | Type | Required | Description |\n|---|---|---|---|\n`apiVersion` |\nstring | REQUIRED | MUST be `agent-loops.dev/v1alpha1` for this specification version. |\n`kind` |\nstring | REQUIRED | MUST be `AgentLoop` . |\n`metadata` |\nobject | REQUIRED | Stable identity and human-facing metadata. |\n`spec` |\nobject | REQUIRED | Loop objective and declared inputs. |\n`phases` |\narray | REQUIRED | Ordered phase definitions. MUST contain at least one phase. |\n`escalation` |\nobject | OPTIONAL | Root escalation policy and required escalation inputs. |\n\n`metadata`\n\nMUST contain:\n\n| Field | Type | Required | Description |\n|---|---|---|---|\n`name` |\nstring | REQUIRED | Stable machine-readable loop name. |\n`version` |\nstring | REQUIRED | Loop version. Semantic versioning is RECOMMENDED. |\n`title` |\nstring | REQUIRED | Human-readable title. |\n`description` |\nstring | REQUIRED | Human-readable description of the loop purpose. |\n\n`spec`\n\nMUST contain:\n\n| Field | Type | Required | Description |\n|---|---|---|---|\n`objective` |\nstring | REQUIRED | Overall loop objective. |\n`inputs` |\nobject | REQUIRED | Named input definitions required or accepted by the loop. |\n`dependencies` |\nobject | OPTIONAL | Other loops and Agent Skills required by this loop. |\n\nEach input definition MUST include:\n\n| Field | Type | Required | Description |\n|---|---|---|---|\n`type` |\nstring or single-item array | REQUIRED | One of `string` , `number` , `boolean` , `object` , or an array containing one of those values. |\n`required` |\nboolean | REQUIRED | Whether the orchestrator must resolve the input before execution. |\n`description` |\nstring | REQUIRED | Human-readable input description. |\n\n`spec.dependencies`\n\ndeclares external Agent Loops and Agent Skills the\norchestrator must make available before executing the loop. Dependencies are\npart of the loop contract: they describe the capabilities or sub-loops the\nauthor expects the orchestrator to have, but they do not inline or vendor those\ndependencies into the loop document.\n\n`spec.dependencies`\n\nMAY contain:\n\n| Field | Type | Required | Description |\n|---|---|---|---|\n`loops` |\narray | OPTIONAL | Agent Loop artifacts required by this loop. |\n`skills` |\narray | OPTIONAL | Agent Skill artifacts required by this loop. |\n\nAt least one of `loops`\n\nor `skills`\n\nMUST be present when `dependencies`\n\nis\ndefined.\n\nEach loop dependency MUST contain:\n\n| Field | Type | Required | Description |\n|---|---|---|---|\n`name` |\nstring | REQUIRED | Local dependency name used by the orchestrator. |\n`ref` |\nstring | 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>` ). |\n`required` |\nboolean | OPTIONAL | Whether execution MUST fail if the dependency cannot be resolved. Defaults to `true` . |\n`description` |\nstring | OPTIONAL | Human-readable reason the dependency is needed. |\n\nLoop dependencies MUST resolve to artifacts with artifact type\n`application/vnd.agentloops.loop.v1`\n\n.\n\nEach skill dependency MUST contain:\n\n| Field | Type | Required | Description |\n|---|---|---|---|\n`name` |\nstring | REQUIRED | Local skill name used by the orchestrator. |\n`ref` |\nstring | 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>` ). |\n`required` |\nboolean | OPTIONAL | Whether execution MUST fail if the dependency cannot be resolved. Defaults to `true` . |\n`description` |\nstring | OPTIONAL | Human-readable reason the skill is needed. |\n\nSkill dependencies MUST resolve to artifacts conforming to Thomas Vitale's\n[Agent Skills OCI Artifacts Specification](https://github.com/ThomasVitale/agents-skills-oci-artifacts-spec),\nincluding the `application/vnd.agentskills.skill.v1`\n\nartifact type.\n\nExample:\n\n```\nspec:\n  objective: Deliver a feature safely.\n  inputs:\n    ticket:\n      type: string\n      required: true\n      description: Ticket key or URL.\n  dependencies:\n    loops:\n      - name: review_loop_engineering\n        ref: ghcr.io/acme/loops/review_loop_engineering:0.2.0\n        description: Reusable engineering review loop invoked before publication.\n    skills:\n      - name: github-pr-review\n        ref: ghcr.io/acme/agent-skills/github-pr-review:1.4.0@sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef\n        description: Skill used to inspect and address pull request review feedback.\n```\n\nClients SHOULD resolve dependencies recursively, detect dependency cycles, and\nfail before execution when a required dependency cannot be resolved, verified,\nor installed. Resolved dependency digests MUST be recorded in `loops.lock.json`\n\nor an equivalent lock file.\n\nEach phase MUST contain:\n\n| Field | Type | Required | Description |\n|---|---|---|---|\n`name` |\nstring | REQUIRED | Stable phase identifier. |\n`title` |\nstring | REQUIRED | Human-readable phase title. |\n`objective` |\nstring | REQUIRED | Phase objective. |\n`actions` |\narray of strings | REQUIRED | Ordered actions for the orchestrator or delegated agents. |\n`completion` |\narray of strings | REQUIRED | Conditions that must be satisfied before leaving the phase. |\n`outputs` |\narray of single-entry objects | REQUIRED | Structured outputs produced by the phase. |\n`transitions` |\narray | OPTIONAL | Conditional transitions to other phases. |\n\nPhase names SHOULD be unique within a loop. Clients SHOULD reject loops with duplicate phase names because transitions would be ambiguous.\n\nA transition MUST contain:\n\n| Field | Type | Required | Description |\n|---|---|---|---|\n`to` |\nstring | REQUIRED | Target phase name. |\n`condition` |\nstring | REQUIRED | Natural-language condition for taking the transition. |\n\nWhen 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.\n\n`escalation`\n\ndefines when and how the orchestrator asks for human input. It MUST\ncontain:\n\n| Field | Type | Required | Description |\n|---|---|---|---|\n`principle` |\nstring | REQUIRED | Escalation policy for the loop. |\n`escalation_inputs` |\narray | REQUIRED | Structured fields the orchestrator must provide when escalating. |\n\nEach escalation input MUST contain `name`\n\n, `type`\n\n, and `description`\n\n.\n\nAn orchestrator executing an Agent Loop MUST:\n\n- Validate the loop document against this specification.\n- Resolve, verify, and make available all required\n`spec.dependencies`\n\n, including loop dependencies and Agent Skill dependencies. - Resolve all required\n`spec.inputs`\n\nbefore entering the first phase, unless the loop explicitly permits deferred resolution. - Execute phases in declaration order, subject to selected transitions.\n- Treat phase\n`actions`\n\nas the work instructions for that phase. - Evaluate\n`completion`\n\ncriteria before leaving a phase. - Record each phase's declared\n`outputs`\n\n. - Use\n`escalation.principle`\n\nto decide when a decision cannot be safely inferred. - Keep run evidence separate from the loop definition.\n\nThe 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.\n\nAll media types defined by this specification use the\n`application/vnd.agentloops`\n\nvendor tree.\n\n| Role | Media Type |\n|---|---|\n| Artifact type, individual loop | `application/vnd.agentloops.loop.v1` |\n| Config, individual loop | `application/vnd.agentloops.loop.config.v1+json` |\n| Content layer, loop YAML | `application/vnd.agentloops.loop.content.v1+yaml` |\n| Artifact type, collection index | `application/vnd.agentloops.loop.collection.v1` |\n\nImplementations MAY read earlier proof-of-concept media types for backwards\ncompatibility, but conforming publishers MUST use the\n`application/vnd.agentloops.*`\n\nmedia types.\n\nA Loop Artifact MUST be represented as an OCI Image Manifest with:\n\n`mediaType`\n\n:`application/vnd.oci.image.manifest.v1+json`\n\n`artifactType`\n\n:`application/vnd.agentloops.loop.v1`\n\n`config.mediaType`\n\n:`application/vnd.agentloops.loop.config.v1+json`\n\n- exactly one required YAML content layer with media type\n`application/vnd.agentloops.loop.content.v1+yaml`\n\nExample:\n\n```\n{\n  \"schemaVersion\": 2,\n  \"mediaType\": \"application/vnd.oci.image.manifest.v1+json\",\n  \"artifactType\": \"application/vnd.agentloops.loop.v1\",\n  \"config\": {\n    \"mediaType\": \"application/vnd.agentloops.loop.config.v1+json\",\n    \"digest\": \"sha256:...\",\n    \"size\": 524\n  },\n  \"layers\": [\n    {\n      \"mediaType\": \"application/vnd.agentloops.loop.content.v1+yaml\",\n      \"digest\": \"sha256:...\",\n      \"size\": 8123,\n      \"annotations\": {\n        \"org.opencontainers.image.title\": \"implement_feature.yml\"\n      }\n    }\n  ],\n  \"annotations\": {\n    \"io.agentloops.loop.name\": \"implement_feature\",\n    \"org.opencontainers.image.title\": \"implement_feature\",\n    \"org.opencontainers.image.description\": \"Implement Feature from Jira Ticket\",\n    \"org.opencontainers.image.version\": \"0.1.0\",\n    \"org.opencontainers.image.source\": \"https://github.com/example/loops\"\n  }\n}\n```\n\nThe config object contains normalized metadata extracted from the loop YAML. A client SHOULD validate that config values match the YAML layer before execution.\n\n| Field | Type | Required | Description |\n|---|---|---|---|\n`schemaVersion` |\ninteger | REQUIRED | Config schema version. This document defines `1` . |\n`apiVersion` |\nstring | REQUIRED | Loop API version, for example `agent-loops.dev/v1alpha1` . |\n`kind` |\nstring | REQUIRED | Loop kind, for example `AgentLoop` . |\n`name` |\nstring | REQUIRED | Stable loop name from `metadata.name` . |\n`version` |\nstring | REQUIRED | Loop version from `metadata.version` . |\n`title` |\nstring | REQUIRED | Human-readable title from `metadata.title` . |\n`description` |\nstring | REQUIRED | Description from `metadata.description` . |\n`inputs` |\narray | REQUIRED | Declared input names with required flags and type descriptors. |\n`dependencies` |\nobject | OPTIONAL | Summary of declared loop and skill dependencies. |\n`phases` |\narray | REQUIRED | Phase names in declaration order. |\n`hasEscalation` |\nboolean | REQUIRED | Whether the loop declares root escalation policy. |\n`annotations` |\nobject | OPTIONAL | Tool-specific metadata. |\n\nExample:\n\n```\n{\n  \"schemaVersion\": 1,\n  \"apiVersion\": \"agent-loops.dev/v1alpha1\",\n  \"kind\": \"AgentLoop\",\n  \"name\": \"implement_feature\",\n  \"version\": \"0.1.0\",\n  \"title\": \"Implement Feature from Jira Ticket\",\n  \"description\": \"Analyse a Jira ticket, implement the requested feature, and iterate until checks pass.\",\n  \"inputs\": [\n    {\n      \"name\": \"ticket\",\n      \"type\": \"string\",\n      \"required\": true\n    }\n  ],\n  \"dependencies\": {\n    \"loops\": [\n      {\n        \"name\": \"review_loop_engineering\",\n        \"ref\": \"ghcr.io/acme/loops/review_loop_engineering:0.2.0\"\n      }\n    ],\n    \"skills\": [\n      {\n        \"name\": \"github-pr-review\",\n        \"ref\": \"ghcr.io/acme/agent-skills/github-pr-review:1.4.0@sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef\"\n      }\n    ]\n  },\n  \"phases\": [\n    \"analyze-ticket\",\n    \"prepare\",\n    \"implement\",\n    \"cyber review\",\n    \"publish\"\n  ],\n  \"hasEscalation\": true\n}\n```\n\nA Loop Artifact MUST contain one YAML content layer. The layer MUST be a valid\nAgent Loop document. The layer SHOULD be stored as the original `.yml`\n\nor\n`.yaml`\n\nfile without archive wrapping so clients can fetch and cache it\ndirectly.\n\nClients 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.\n\nLoop annotations use the `io.agentloops.*`\n\nnamespace. OCI image annotations SHOULD\nbe used for generic metadata.\n\n| Annotation Key | Requirement Level | Description |\n|---|---|---|\n`io.agentloops.loop.name` |\nREQUIRED | Loop name. MUST match config `name` and YAML `metadata.name` . |\n`io.agentloops.loop.apiVersion` |\nREQUIRED | Loop API version. |\n`io.agentloops.loop.kind` |\nREQUIRED | Loop kind. |\n`io.agentloops.loop.inputs` |\nOPTIONAL | Comma-separated input names for lightweight discovery. |\n`io.agentloops.loop.phases` |\nOPTIONAL | Comma-separated phase names for lightweight discovery. |\n`io.agentloops.loop.categories` |\nOPTIONAL | Comma-separated categories for browsing. |\n`org.opencontainers.image.title` |\nREQUIRED | Human-readable artifact title. |\n`org.opencontainers.image.description` |\nRECOMMENDED | Loop description. |\n`org.opencontainers.image.version` |\nREQUIRED | Loop version. |\n`org.opencontainers.image.source` |\nRECOMMENDED | Source repository URL. |\n`org.opencontainers.image.revision` |\nRECOMMENDED | Source revision that produced the artifact. |\n`org.opencontainers.image.created` |\nRECOMMENDED | Creation timestamp. |\n`org.opencontainers.image.licenses` |\nOPTIONAL | License expression. |\n\nPublished loop releases SHOULD be tagged with the loop version:\n\n```\nghcr.io/acme/loops/implement_feature:0.1.0\n```\n\nThe canonical reproducible reference is digest-pinned:\n\n```\nghcr.io/acme/loops/implement_feature@sha256:<digest>\n```\n\nTags such as `latest`\n\n, `stable`\n\n, or `experimental`\n\nMAY be used for human\nconvenience, but clients MUST record resolved digests in lock files.\n\nA Loop Collection is an OCI Image Index whose manifests reference individual Loop Artifacts by digest. It enables discovery without downloading every loop YAML layer.\n\n```\n{\n  \"schemaVersion\": 2,\n  \"mediaType\": \"application/vnd.oci.image.index.v1+json\",\n  \"artifactType\": \"application/vnd.agentloops.loop.collection.v1\",\n  \"annotations\": {\n    \"io.agentloops.collection.name\": \"engineering-loops\",\n    \"org.opencontainers.image.title\": \"engineering-loops\",\n    \"org.opencontainers.image.description\": \"Reusable engineering loops\"\n  },\n  \"manifests\": [\n    {\n      \"mediaType\": \"application/vnd.oci.image.manifest.v1+json\",\n      \"artifactType\": \"application/vnd.agentloops.loop.v1\",\n      \"digest\": \"sha256:...\",\n      \"size\": 0,\n      \"annotations\": {\n        \"io.agentloops.loop.name\": \"implement_feature\",\n        \"io.agentloops.loop.ref\": \"ghcr.io/acme/loops/implement_feature:0.1.0\",\n        \"org.opencontainers.image.title\": \"implement_feature\",\n        \"org.opencontainers.image.version\": \"0.1.0\",\n        \"org.opencontainers.image.description\": \"Implement a feature from a ticket.\"\n      }\n    }\n  ]\n}\n```\n\n| Annotation Key | Requirement Level | Description |\n|---|---|---|\n`io.agentloops.collection.name` |\nREQUIRED | Collection name. |\n`org.opencontainers.image.title` |\nREQUIRED | Human-readable title. |\n`org.opencontainers.image.description` |\nRECOMMENDED | Collection description. |\n`org.opencontainers.image.version` |\nRECOMMENDED | Collection version. |\n`org.opencontainers.image.source` |\nRECOMMENDED | Source repository URL. |\n\nThe `loops.json`\n\nfile declares the loop dependencies a project expects agents or\ntools to use. It is analogous to a dependency manifest. It records desired\nOCI references, which MAY be mutable tags, immutable digests, or tag plus digest\nreferences.\n\nThe manifest file SHOULD live at the project root:\n\n```\nmy-project/\n  loops.json\n```\n\n| Field | Type | Required | Description |\n|---|---|---|---|\n`loops` |\narray | REQUIRED | Declared loop dependencies. |\n\nEach loop entry has:\n\n| Field | Type | Required | Description |\n|---|---|---|---|\n`name` |\nstring | REQUIRED | Local loop identifier. SHOULD match artifact metadata name. |\n`ref` |\nstring | REQUIRED | OCI reference with tag, digest, or tag plus digest. |\n`aliases` |\narray | OPTIONAL | Alternate local names. |\n`requiredInputs` |\nobject | OPTIONAL | Project-provided input defaults or bindings. |\n\nExample:\n\n```\n{\n  \"loops\": [\n    {\n      \"name\": \"implement_feature\",\n      \"ref\": \"ghcr.io/acme/loops/implement_feature:0.1.0\"\n    },\n    {\n      \"name\": \"fix_pr_ci\",\n      \"ref\": \"ghcr.io/acme/loops/fix_pr_ci:1.2.0@sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef\",\n      \"aliases\": [\"fix-ci\"]\n    }\n  ]\n}\n```\n\nThe 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.\n\nThe lock file SHOULD live beside `loops.json`\n\n:\n\n```\nmy-project/\n  loops.json\n  loops.lock.json\n{\n  \"lockfileVersion\": 1,\n  \"generatedAt\": \"2026-07-16T00:00:00Z\",\n  \"loops\": [\n    {\n      \"name\": \"implement_feature\",\n      \"path\": \".agents/loops/implement_feature/0.1.0/loop.yml\",\n      \"compatibilityPath\": \".agents/loops/implement_feature/loop.yml\",\n      \"source\": {\n        \"registry\": \"ghcr.io\",\n        \"repository\": \"acme/loops/implement_feature\",\n        \"tag\": \"0.1.0\",\n        \"digest\": \"sha256:...\",\n        \"ref\": \"ghcr.io/acme/loops/implement_feature:0.1.0@sha256:...\"\n      },\n      \"resolvedAt\": \"2026-07-16T00:00:00Z\"\n    }\n  ],\n  \"skills\": [\n    {\n      \"name\": \"github-pr-review\",\n      \"path\": \".agents/skills/github-pr-review/1.4.0\",\n      \"compatibilityPath\": \".agents/skills/github-pr-review\",\n      \"source\": {\n        \"registry\": \"ghcr.io\",\n        \"repository\": \"acme/agent-skills/github-pr-review\",\n        \"tag\": \"1.4.0\",\n        \"digest\": \"sha256:...\",\n        \"ref\": \"ghcr.io/acme/agent-skills/github-pr-review:1.4.0@sha256:...\"\n      },\n      \"resolvedAt\": \"2026-07-16T00:00:00Z\"\n    }\n  ]\n}\n```\n\nClients SHOULD install loops and skills under the selected agent root, commonly\n`.agents/`\n\n.\n\nWhen an artifact reference contains a tag, clients SHOULD use that tag as the local version directory:\n\n```\n.agents/\n  loops/<loop-name>/<version>/loop.yml\n  loops/<loop-name>/loop.yml\n  skills/<skill-name>/<version>/SKILL.md\n  skills/<skill-name>/SKILL.md\n```\n\nThe 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.\n\nWhen a reference is digest-only, clients SHOULD use a filesystem-safe digest\nlabel such as `sha256-<digest>`\n\ninstead of `<version>`\n\n.\n\nLock 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.\n\n- Read\n`loops.lock.json`\n\n. - Resolve the current digest for each loop or skill ref when the ref contains a tag.\n- Compare the resolved digest with the locked digest.\n- Report an available update when the digests differ.\n- Update the lock file only after pulling, validating, and accepting the new loop or skill artifact.\n\nClients SHOULD cache pulled loop YAML by registry, repository, tag, and digest to avoid accidental reuse of mutable tags.\n\nRecommended project-local layout:\n\n```\nmy-project/\n  .loop/\n    cache/\n      ghcr.io/\n        acme/\n          loops/\n            implement_feature/\n              0.1.0/\n                sha256-<digest>/\n                  loop.yml\n    runs/\n      yyyy/\n        mm/\n          dd/\n            hh/\n              mm/\n                run.json\n```\n\nAn 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.\n\nLoop 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.\n\nPublishers SHOULD:\n\n- sign loop artifacts with Sigstore Cosign or an equivalent OCI-compatible signing mechanism;\n- attach provenance attestations describing source repository, revision, build workflow, and schema validation result;\n- attach optional evaluation attestations describing tested agent behavior;\n- publish immutable version tags and avoid retagging released versions.\n\nConsumers SHOULD:\n\n- prefer digest-pinned references for automation;\n- verify signatures before execution;\n- validate the YAML layer against the loop schema;\n- inspect required inputs and escalation policy before starting a run;\n- treat unsigned public loops as untrusted unless local policy permits them.\n\nLoop 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.\n\nWhen 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.\n\nThe `agentkit`\n\nCLI is a reference implementation of this specification. It can:\n\n- validate Agent Loop YAML;\n- push a loop YAML file as an OCI artifact with\n`agentkit loop push`\n\n; - pull and install a loop artifact with\n`agentkit loop pull`\n\n; - render local or remote loop sources as a terminal flowchart;\n- print agent-facing prime instructions for loop execution.\n\nThe CLI follows this specification as the source of truth for accepted document and artifact formats.\n\nVersion constraints : A later revision may define semver ranges and compatibility rules for automatic loop updates.\n\nCollections and search : Collection artifacts may grow richer category, owner, compatibility, and quality metadata for registry browsing.\n\nExecution attestations : Completed runs may be published as separate referrer artifacts that point back to the loop digest used for the run.\n\nPolicy gates : Organizations may define policy checks that block unsigned loops, loops with forbidden tools, or loops whose escalation model is too broad.\n\nSchema evolution : Future loop API versions should preserve validation and discovery behavior while allowing richer transition logic and typed outputs.\n\nThis specification builds on the design pattern introduced by Thomas Vitale's\n[Agent Skills OCI Artifacts Specification](https://github.com/ThomasVitale/agents-skills-oci-artifacts-spec),\nthe OCI Image and Distribution Specifications, the ORAS project, and\nSigstore/Cosign.", "url": "https://wpnews.pro/news/proposed-spec-to-share-skill-and-loop-workflow-by-oci-registry", "canonical_source": "https://github.com/stumpyfr/loop-spec", "published_at": "2026-07-17 12:02:54+00:00", "updated_at": "2026-07-17 12:21:18.556855+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "ai-infrastructure"], "entities": ["OCI", "ORAS", "agentkit", "Apache-2.0"], "alternates": {"html": "https://wpnews.pro/news/proposed-spec-to-share-skill-and-loop-workflow-by-oci-registry", "markdown": "https://wpnews.pro/news/proposed-spec-to-share-skill-and-loop-workflow-by-oci-registry.md", "text": "https://wpnews.pro/news/proposed-spec-to-share-skill-and-loop-workflow-by-oci-registry.txt", "jsonld": "https://wpnews.pro/news/proposed-spec-to-share-skill-and-loop-workflow-by-oci-registry.jsonld"}}