skill

agents-skills-oci-artifacts-spec

Standard method for packaging, distributing, signing, and tracking Agent Skills using OCI Artifacts.

ThomasVitale/agents-skills-oci-artifacts-speccommunitylistedunreviewednot running here yet

Use skill

Set up

Skills are installed by placing their folder where your agent loads skills.

Install instructions come from the README

Skills do not use an MCP config. Follow the steps in the README below; one-click install arrives with accounts.

README

synced Oct 14, 2026

Agent Skills OCI Artifacts Specification

Version: 0.1.0
Status: Draft
Date: 2026-04-01
License: Apache-2.0

Abstract

This document specifies a standard method for packaging, distributing, signing, and tracking Agent Skills using OCI Artifacts. It defines the OCI media types, manifest structure, config schemas, annotation conventions, collection index format, lock file format, and supply-chain security mechanisms required for interoperable skill distribution across any OCI-compliant registry.

This specification is designed as an extension to the Agent Skills Specification. It does not alter the Agent Skills directory structure or SKILL.md format; it defines how a conforming skill directory is packaged into an OCI Artifact, published to a registry, installed into a project, and kept up to date.

Introduction
- 1.1 Motivation
- 1.2 Design Goals
- 1.3 Relationship to the Agent Skills Specification
- 1.4 Notational Conventions
Glossary
Media Types
Individual Skill Artifact
- 4.1 OCI Manifest Structure
- 4.2 Config Object Schema
- 4.3 Layers
- 4.4 Annotations
- 4.5 Tagging Conventions
Skills Collection Artifact
- 5.1 OCI Image Index Structure
- 5.2 Collection Annotations
Skills Manifest File
- 6.1 Purpose
- 6.2 File Location
- 6.3 Schema
Lock File
- 7.1 Purpose
- 7.2 File Location
- 7.3 Schema
- 7.4 Update Check Workflow
Supply-Chain Security
- 8.1 Signing with Cosign (Sigstore)
- 8.2 Attestations
File System Layout After Installation
- 9.1 Multi-Vendor Installation Layout
Registry Compatibility
Reference Implementation
- 11.1 Arconia CLI
- 11.2 ORAS CLI Walkthrough
- 11.3 ORAS Client Libraries
Future Considerations
Acknowledgments

1. Introduction

1.1 Motivation

The Agent Skills Specification defines a portable, file-system-based format for packaging instructions and resources that AI coding agents can consume. A skill is a directory containing a SKILL.md file (with YAML frontmatter and Markdown instructions) alongside optional scripts/, references/, and assets/ directories. The specification deliberately leaves distribution out of scope: it prescribes what a skill looks like on disk, but not how it gets there.

In practice, skills today are distributed ad hoc. Users clone or copy directories from GitHub repositories into a local .agents/skills/ folder, assisted by a growing number of incompatible CLI tools and proprietary registry formats invented by different vendors. This fragmentation creates several concrete problems.

No standard packaging or distribution mechanism. Without a common wire format, every vendor implements its own scheme for transporting skill directories from a source to a consumer. Users are locked into whichever vendor-specific tool they adopted first, and skill authors must publish to multiple destinations to reach their audience.

Vendor-specific, Git-centric approaches do not scale. Most existing solutions are tightly coupled to GitHub. Skill authors who host source code on GitLab, Codeberg, or self-hosted Git servers are excluded or second-class citizens. Even for GitHub users, Git-based distribution has fundamental limitations. Fetching a single skill from a monorepo requires downloading repository metadata far beyond what is needed, since Git has no native mechanism for retrieving an individual subdirectory as a standalone, versioned artifact. GitHub's API rate limits further constrain this model: unauthenticated requests are severely throttled, and authenticated requests require a GitHub account, meaning that organizations whose developers do not otherwise use GitHub must create and manage accounts solely to overcome rate-limiting. Skills within a monorepo cannot be independently versioned, and there is no standard, provider-agnostic API for resolving a skill version to an immutable artifact digest or for signing and attesting individual skill directories within a larger repository. These are not edge cases but routine requirements for any artifact distribution system operating at scale.

No provenance or integrity verification. Skills frequently include executable scripts that an AI agent may run on the developer's behalf. Without a way to verify who published a skill, whether it has been tampered with since publication, or what build process produced it, developers accept significant supply-chain risk every time they install a skill.

No standardized discovery or indexing. Browsing available skills requires visiting vendor-specific web portals. There is no machine-readable, registry-agnostic index that a CLI tool, IDE plugin, or CI job can query programmatically.

Enterprise environments are underserved. Organizations that operate behind firewalls, require artifact mirroring or proxying, enforce access-control policies through their existing infrastructure, or mandate on-premises artifact storage cannot use distribution models that assume direct access to public Git hosting services.

Language-specific solutions are insufficient. Packaging skills as npm packages, Python wheels, or similar language-specific artifacts couples the distribution mechanism to a particular language runtime. Agent skills are language-agnostic by design; their distribution format should be as well.

OCI Artifacts (OCI Image Spec v1.1 + OCI Distribution Spec v1.1) address every one of these problems. OCI is an open standard governed by the Open Container Initiative under the Linux Foundation. It defines a content-addressable, registry-agnostic primitive for storing and distributing arbitrary content. Every major cloud provider operates an OCI-compliant registry (GHCR, ECR, GAR, ACR, DockerHub), and mature open-source alternatives (Harbor, Zot) are available for on-premises deployment. Enterprise organizations already have infrastructure for controlling OCI registry access, including mirrors, pull-through proxies, local copies, and fine-grained authentication and authorization policies.

From a security perspective, OCI Distribution Spec v1.1 introduces the Referrers API, which enables Cosign (Sigstore) signatures and in-toto attestations to be attached to any OCI Artifact as first-class metadata. Producers can sign skill artifacts and attest their provenance using the same tooling and transparency infrastructure that secures container images in production today. Consumers can verify these signatures and attestations before extraction, establishing a trust chain from the skill author to the developer's local workspace.

OCI Artifacts do not require a container runtime to be installed. As an example, the ORAS project (OCI Registry As Storage), a CNCF Sandbox project, provides a purpose-built CLI and client libraries (Go, Python, Rust, C#, Java) for pushing and pulling non-image OCI Artifacts. Adopting OCI as the transport layer gives agent skills access to the entire OCI ecosystem without introducing container-specific tooling.

Beyond distribution itself, vendors are building value-added services on top of agent skills, such as vulnerability scanning of skill scripts, static analysis of prompt quality, and automated evaluation suites that measure how effectively a skill guides an agent through its intended task. These services produce results that are most useful when they travel with the artifact they describe. OCI Artifacts make this possible through the Referrers API: a scanning service can attach its findings as a custom attestation to the skill artifact, and an evaluation platform can attach benchmark results as an in-toto attestation with a domain-specific predicate type. The outcome of a security scan or an evaluation run becomes discoverable through the same standard mechanism used for SLSA provenance attestations and Cosign signatures. Any conforming client can enumerate these attestations, inspect their predicate types, and present the results to the user, without requiring integration with the specific vendor that produced them. This decouples the production of quality and security signals from their consumption, enabling a healthy ecosystem where multiple vendors can contribute complementary attestations to the same artifact, and reach a wider audience through shared standards.

Projects such as Helm, Sigstore, FluxCD, and WebAssembly already use OCI Artifacts in production, validating the approach at scale.

1.2 Design Goals

This specification is guided by the following design goals.

Registry agnostic. Skill artifacts MUST be storable in and retrievable from any OCI-compliant registry without registry-specific extensions.
Content addressable. Every published skill artifact MUST be uniquely identified by an immutable digest. Tags are provided for human convenience; digests are the source of truth.
Transparent packaging. Once extracted, the resulting directory structure MUST be indistinguishable from a skill directory created manually according to the Agent Skills Specification. The OCI packaging layer is invisible to the consuming agent.
Signable and attestable. It MUST be possible to sign a skill artifact and attach provenance or evaluation attestations using standard OCI mechanisms (Referrers API, Cosign) without modifying the artifact itself.
Minimal client burden. A conforming client needs only to implement the OCI Distribution Spec for push, pull, and manifest resolution. The ORAS CLI or any ORAS-compatible library is sufficient.
Deterministic reproduction. A lock file records the exact digest of every installed skill. Given the same lock file, any client MUST be able to reproduce the identical set of installed skills.

1.3 Relationship to the Agent Skills Specification

This specification is an extension to the Agent Skills Specification. It depends on the following definitions from that specification:

The directory structure of a skill (SKILL.md, scripts/, references/, assets/).
The YAML frontmatter fields of SKILL.md (name, description, license, compatibility, metadata, allowed-tools).
The file reference conventions and progressive disclosure model.

This specification does not modify any of those definitions. It adds:

A wire format (OCI Artifact) for transporting skill directories.
A config schema for structured metadata within the OCI manifest.
Annotation conventions for skill-specific metadata.
A skills collection format for indexing collections of skills.
A manifest file (skills.json) for declaring required skills.
A lock file (skills.lock.json) for pinning installed versions.
Guidance on signing, attestation, and supply-chain security.

1.4 Notational Conventions

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.

2. Glossary

Agent Skills Terms

Term	Definition
Skill	A directory conforming to the Agent Skills Specification, centered on a `SKILL.md` file.
Skill Artifact	An OCI Artifact that packages a single skill directory as defined by this specification.
Skills Collection	An OCI Image Index that references a curated collection of Skill Artifacts by digest, enabling discovery without downloading skill content.
Skills Manifest	A project-local JSON file (`skills.json`) that declares which skills a project requires, analogous to `package.json` or `Cargo.toml`.
Lock File	A project-local JSON file (`skills.lock.json`) that records the exact OCI reference and digest of every installed skill, enabling deterministic reproduction and automated update checks.

OCI Terms

Term	Definition
OCI	Open Container Initiative is the organization that governs the Image Spec and Distribution Spec under the Linux Foundation.
OCI Artifact	Any content stored in an OCI-compliant registry using the OCI Image Manifest format with a custom `artifactType` to distinguish it from container images. OCI Artifacts leverage the same registry infrastructure as container images but package arbitrary content (skills, Helm charts, WASM modules, etc.). See OCI Artifacts Guidance.
OCI Image Manifest	A JSON document describing the components that make up a single artifact: a config descriptor, an ordered list of layer descriptors, an optional `artifactType`, and annotations. Media type: `application/vnd.oci.image.manifest.v1+json`.
OCI Image Index	An annotated list of manifests, typically used to group multiple related manifests (e.g., platform variants of an image, or a collection of skill artifacts in a skills collection). Media type: `application/vnd.oci.image.index.v1+json`.
OCI Config	A blob referenced by the `config` descriptor in an OCI Image Manifest. It carries structured metadata about the artifact. For Skill Artifacts, the config contains skill metadata (name, version, description, etc.) accessible without unpacking the content layer.
Descriptor	A JSON object that references content by its media type, digest (content address), and size. Descriptors are the fundamental building block for linking manifests, configs, and layers in OCI.
Digest	A unique, content-addressable identifier computed as a cryptographic hash of a blob's content (e.g., `sha256:abc123...`). Digests are immutable: if the content changes, the digest changes.
Tag	A human-readable, mutable pointer to a manifest in a registry (e.g., `1.2.0`, `latest`). A manifest may have zero, one, or many tags.
Registry	A service implementing the OCI Distribution Specification that stores and serves OCI manifests and blobs. Examples: GHCR, ECR, GAR, ACR, Docker Hub, Harbor, Zot.
Repository	A named collection of content within a registry, identified by a path (e.g., `arconia-io/agent-skills/pull-request`). A repository contains manifests, blobs, and tags.
Referrers API	The `GET /v2/<name>/referrers/<digest>` endpoint from OCI Distribution Spec v1.1, used to discover signatures, attestations, and other artifacts attached to a manifest via the `subject` field.

Other Terms

Term	Definition
ORAS	OCI Registry As Storage is a CNCF Sandbox project providing a CLI and client libraries for pushing and pulling non-image OCI Artifacts.
Cosign	A tool from the Sigstore project for signing, verifying, and attesting OCI artifacts.
in-toto	An open-source framework for supply-chain security (in-toto) that defines a standard format for attestations describing the provenance and integrity of software artifacts.

3. Media Types

All media types defined by this specification use the application/vnd.agentskills vendor tree registered under the OCI Artifact convention.

Role	Media Type
Artifact type (individual skill)	`application/vnd.agentskills.skill.v1`
Config (individual skill)	`application/vnd.agentskills.skill.config.v1+json`
Content layer (individual skill)	`application/vnd.agentskills.skill.content.v1.tar+gzip`
Artifact type (collection index)	`application/vnd.agentskills.collection.v1`

The standard OCI empty descriptor (application/vnd.oci.empty.v1+json) MAY be used where a placeholder config is required by a registry implementation.

Rationale for tar+gzip. Skills are directory trees. A single compressed tar archive is the most portable, deterministic representation. This approach is consistent with established precedents: Helm charts use application/vnd.cncf.helm.chart.content.v1.tar+gzip and FluxCD uses application/vnd.cncf.flux.content.v1.tar+gzip.

4. Individual Skill Artifact

A Skill Artifact is an OCI Artifact that packages a single skill directory for distribution through an OCI-compliant registry.

4.1 OCI Manifest Structure

A Skill Artifact is represented as an OCI Image Manifest (application/vnd.oci.image.manifest.v1+json) with the following structure:

The artifactType field MUST be set to application/vnd.agentskills.skill.v1.
The config descriptor MUST reference a JSON blob with media type application/vnd.agentskills.skill.config.v1+json conforming to the schema in Section 4.2.
The layers array MUST contain exactly one entry with media type application/vnd.agentskills.skill.content.v1.tar+gzip conforming to the requirements in Section 4.3.
The annotations object SHOULD include the annotations defined in Section 4.4.

Example manifest:

{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "artifactType": "application/vnd.agentskills.skill.v1",
  "config": {
    "mediaType": "application/vnd.agentskills.skill.config.v1+json",
    "digest": "sha256:45de2ee8cd987f42b921589d09ef5f082399f4f3c6a28f3832a7892915b021dd",
    "size": 603,
    "data": "ewogICJzY2hlb..."
  },
  "layers": [
    {
      "mediaType": "application/vnd.agentskills.skill.content.v1.tar+gzip",
      "digest": "sha256:d33a70bb4e26d727c3ca63d6d9fdf07b91144f85dd4dfcbe86fa282203f749b2",
      "size": 1544,
      "annotations": {
        "org.opencontainers.image.title": "oras14942267480164953970.tar.gz"
      }
    }
  ],
  "annotations": {
    "org.opencontainers.image.created":     "2026-04-01T21:00:04Z",
    "org.opencontainers.image.title":       "manage-pull-requests",
    "org.opencontainers.image.description": "A skill for managing pull requests in Forgejo repositories using the forgejo-cli. Supports creating, listing, viewing, merging, closing, and commenting on PRs.",
    "org.opencontainers.image.version":     "1.0.0",
    "org.opencontainers.image.licenses":    "Apache-2.0",
    "org.opencontainers.image.revision":    "47c0e53",
    "org.opencontainers.image.source":      "https://github.com/ThomasVitale/agents-skills-oci-artifacts-spec.git",
    "io.agentskills.skill.name":            "manage-pull-requests"
  }
}

4.2 Config Object Schema

The config blob is a JSON object that mirrors the SKILL.md frontmatter fields and provides structured, queryable metadata accessible directly from the OCI manifest without unpacking the content layer.

Media type: application/vnd.agentskills.skill.config.v1+json

Field	Type	Required	Description
`schemaVersion`	string	REQUIRED	Version of this config schema. MUST be `"1"` for this specification version. Clients MUST reject configs whose `schemaVersion` they do not recognize.
`name`	string	REQUIRED	Skill identifier. MUST match the `name` field in `SKILL.md` frontmatter and the `io.agentskills.skill.name` annotation. Allowed characters: lowercase ASCII letters, digits, and hyphens. Maximum length: 64 characters. Pattern: `^[a-z0-9][a-z0-9-]{0,62}[a-z0-9]$`.
`version`	string	RECOMMENDED	Skill version. SHOULD follow Semantic Versioning 2.0.0. Sourced from the OCI tag at publish time. MUST match the `org.opencontainers.image.version` annotation when present.
`description`	string	OPTIONAL	What the skill does and when an agent should invoke it. Sourced from `SKILL.md` frontmatter. Maximum length: 1024 characters.
`license`	string	OPTIONAL	SPDX license expression. SHOULD match the `org.opencontainers.image.licenses` annotation.
`compatibility`	string	OPTIONAL	Free-text environment requirements. Sourced from `SKILL.md` frontmatter. Maximum length: 500 characters.
`allowedTools`	array of strings	OPTIONAL	Pre-approved tool patterns the skill is permitted to invoke (e.g., `Bash(git:*)`). Sourced from the `allowed-tools` field in `SKILL.md` frontmatter.
`metadata`	object (string values)	OPTIONAL	Arbitrary key-value pairs providing supplemental metadata. Common keys: `author`, `category`.

Example config object:

{
  "schemaVersion": "1",
  "name": "manage-pull-requests",
  "version": "1.0.0",
  "description": "A skill for managing pull requests in Forgejo repositories using the forgejo-cli. Supports creating, listing, viewing, merging, closing, and commenting on PRs.",
  "license": "Apache-2.0",
  "compatibility": "Requires forgejo-cli (https://codeberg.org/forgejo-contrib/forgejo-cli/wiki/PRs). Agent must have network access to the Forgejo API.",
  "allowedTools": null,
  "metadata": {
    "category": "development-tools",
    "tags": [
      "git",
      "forgejo",
      "pull-requests",
      "automation"
    ]
  }
}

4.3 Layers

A Skill Artifact MUST contain exactly one content layer with media type application/vnd.agentskills.skill.content.v1.tar+gzip.

The tar archive MUST satisfy the following requirements:

The archive MUST contain the full skill directory, rooted at <skill-name>/ (e.g., pull-request/).
The file <skill-name>/SKILL.md MUST be present.
The archive MAY include scripts/, references/, assets/, and any other files or directories defined by the Agent Skills Specification.
The archive MUST preserve POSIX file permissions.
Implementations SHOULD use deterministic archive creation (fixed mtime, sorted entries) to produce reproducible digests.

Example archive layout:

manage-pull-requests/
  SKILL.md
  scripts/
    create-pr.sh
  references/
    REFERENCE.md
  assets/
    pr-template.md

4.4 Annotations

This specification uses two annotation namespaces on the OCI manifest.

Standard OCI annotations (org.opencontainers.image.*) as defined by the OCI Image Spec:

Annotation Key	Requirement Level	Description
`org.opencontainers.image.created`	RECOMMENDED	ISO 8601 timestamp of artifact creation.
`org.opencontainers.image.title`	RECOMMENDED	Human-readable skill name (same as `name` in config).
`org.opencontainers.image.description`	RECOMMENDED	Short description (matches `description` in config).
`org.opencontainers.image.source`	RECOMMENDED	URL of the source repository.
`org.opencontainers.image.revision`	RECOMMENDED	Source control revision (e.g., Git commit SHA).
`org.opencontainers.image.version`	RECOMMENDED	Version string (matches `version` in config).
`org.opencontainers.image.licenses`	RECOMMENDED	SPDX license expression.
`org.opencontainers.image.vendor`	OPTIONAL	Name of the distributing organization.

Agent Skills annotations (io.agentskills.*):

Annotation Key	Requirement Level	Description
`io.agentskills.skill.name`	REQUIRED	Skill name. MUST match the `name` field in the config and in the `SKILL.md` frontmatter.
`io.agentskills.skill.compatibility`	OPTIONAL	Compatibility notes from `SKILL.md` frontmatter.

Rationale for io.agentskills.skill.name. This annotation intentionally duplicates the value carried by org.opencontainers.image.title, but with a stricter semantic contract: the name must consist exclusively of lowercase ASCII letters, digits, and hyphens, and must match the name field in both the OCI config and the SKILL.md frontmatter exactly. The generic title field carries no such constraints. Skill-aware tooling such as CLIs, IDE plugins, or catalog UIs can therefore use io.agentskills.skill.name as a validated, machine-readable identifier without needing to interpret OCI conventions.

4.5 Tagging Conventions

Skill Artifacts SHOULD be pushed with the following tags:

Tag	Meaning	Mutability
`<semver>` (e.g., `1.2.0`)	Immutable release tag. MUST NOT be moved once published.	Immutable
`latest`	Pointer to the most recent stable release.	Mutable
`<major>` (e.g., `1`)	Pointer to the latest release within a major version.	Mutable
`<major>.<minor>` (e.g., `1.2`)	Pointer to the latest patch within a minor version.	Mutable

The canonical reference for a published release is always digest-pinned:

ghcr.io/thomasvitale/agent-skills/manage-pull-requests@sha256:<digest>

Tags are provided for human convenience and automation. The digest is the source of truth for reproducibility.

5. Skills Collection Artifact

A Skills Collection is an OCI Image Index (application/vnd.oci.image.index.v1+json) that acts as a lightweight, browsable directory of available skills. A skills collection does not embed skill content; it references standalone Skill Artifacts by digest. Skills can be pulled individually without downloading the entire skills collection.

5.1 OCI Image Index Structure

The skills collection is represented as an OCI Image Index with the following structure:

The artifactType field MUST be set to application/vnd.agentskills.collection.v1.
Each entry in manifests references a Skill Artifact by digest and carries skill-level annotations at the descriptor level.
The index-level annotations SHOULD include collection-level metadata as described in Section 5.2.

Each manifests entry MUST include:

Field	Value
`mediaType`	`application/vnd.oci.image.manifest.v1+json`
`artifactType`	`application/vnd.agentskills.skill.v1`
`digest`	The immutable digest of the referenced Skill Artifact manifest.
`size`	The size in bytes of the referenced manifest.

Each manifests entry SHOULD include the following annotations:

Annotation Key	Description
`io.agentskills.skill.name`	Skill name.
`io.agentskills.skill.ref`	Canonical tag-based OCI reference (e.g., `ghcr.io/org/skills/name:1.2.0`).
`org.opencontainers.image.title`	Human-readable skill name.
`org.opencontainers.image.version`	Skill version.
`org.opencontainers.image.description`	Short description.

Example collection index:

{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.index.v1+json",
  "artifactType": "application/vnd.agentskills.collection.v1",
  "annotations": {
    "io.agentskills.collection.name":       "thomas-skills-collection",
    "org.opencontainers.image.created":     "2026-04-01T21:00:25Z",
    "org.opencontainers.image.title":       "thomas-skills-collection",
    "org.opencontainers.image.description": "Agent Skills Collection",
    "org.opencontainers.image.version":     "1.0.0",
    "org.opencontainers.image.source":      "https://github.com/ThomasVitale/agents-skills-oci-artifacts-spec.git",
    "org.opencontainers.image.revision":    "47c0e53",
  },
  "manifests": [
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "artifactType": "application/vnd.agentskills.skill.v1",
      "digest": "sha256:bc6708cbbc37adb919157f04d31e601e68f4b9c24b35c655079da87ad0e30f86",
      "size": 0,
      "annotations": {
        "io.agentskills.skill.name":            "manage-pull-requests",
        "io.agentskills.skill.ref":             "ghcr.io/thomasvitale/agent-skills/manage-pull-requests:1.0.0",
        "org.opencontainers.image.title":       "manage-pull-requests",
        "org.opencontainers.image.version":     "1.0.0",
        "org.opencontainers.image.description": "A skill for managing pull requests in Forgejo repositories using the forgejo-cli. Supports creating, listing, viewing, merging, closing, and commenting on PRs."
      }
    },
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "artifactType": "application/vnd.agentskills.skill.v1",
      "digest": "sha256:48f9f03d0b463016b32616f2c5807330462e182ec8dfe6dbfd10a3ed8ef94ca7",
      "size": 0,
      "annotations": {
        "io.agentskills.skill.name":            "upgrade-spring-boot",
        "io.agentskills.skill.ref":             "ghcr.io/thomasvitale/agent-skills/upgrade-spring-boot:1.0.0",
        "org.opencontainers.image.title":       "upgrade-spring-boot",
        "org.opencontainers.image.version":     "1.0.0",
        "org.opencontainers.image.description": "A skill for upgrading Spring Boot projects to a newer version using the Arconia CLI and OpenRewrite recipes. Automates dependency version bumps, deprecated API replacements, and configuration updates."
      }
    }
  ]
}

Design rationale:

The skills collection uses the OCI Image Index type because it is the natural OCI primitive for a collection of manifests. Registries already know how to store and serve it.
Each manifests entry carries skill annotations at the descriptor level, meaning a client can display the full collection (names, versions, descriptions) by fetching the single index manifest without pulling individual skill artifacts.
The io.agentskills.skill.ref annotation records the canonical tag-based reference so that clients can present a human-readable pull command even though the underlying pointer is always digest-based.
Because the skills collection stores only references (digest pointers), updating a single skill requires republishing only that skill's manifest and a new collection index. No skill content is duplicated.

5.2 Collection Annotations

Annotation Key	Requirement Level	Description
`io.agentskills.collection.name`	REQUIRED	Unique identifier for the collection.
`org.opencontainers.image.title`	RECOMMENDED	Human-readable collection name.
`org.opencontainers.image.version`	RECOMMENDED	Version string.
`org.opencontainers.image.description`	RECOMMENDED	Short description.
`org.opencontainers.image.source`	RECOMMENDED	URL of the source repository.
`org.opencontainers.image.revision`	RECOMMENDED	Source control revision (e.g., Git commit SHA).
`org.opencontainers.image.created`	RECOMMENDED	ISO 8601 creation timestamp.

6. Skills Manifest File

6.1 Purpose

The skills manifest file (skills.json) is the user-edited, declarative file that specifies which skills a project requires. It is analogous to package.json (npm) or Cargo.toml (Rust). The file is intended to be committed to version control. It is the human-authored counterpart to the machine-generated skills.lock.json lock file defined in Section 7.

6.2 File Location

The manifest file MUST be placed at the project root, adjacent to the .agents/ directory:

my-project/
  .agents/
    skills/
      ...
  skills.json
  skills.lock.json

6.3 Schema

skills.json is a JSON file with the following structure:

Field	Type	Required	Description
`skills`	array of skill entry objects	REQUIRED	Ordered list of skill entries declaring the skills this project requires.

Each skill entry object contains:

Field	Type	Required	Description
`name`	string	REQUIRED	Skill identifier used for local references (in the lock file and as the installed directory name). SHOULD match the last path segment of `source` and the `name` field in the skill's `SKILL.md` frontmatter.
`source`	string	REQUIRED	OCI repository reference for the skill artifact, without a tag or digest (e.g., `ghcr.io/arconia-io/agent-skills/pull-request`).
`version`	string	OPTIONAL	OCI tag (version) to install. SHOULD follow Semantic Versioning 2.0.0. When omitted, the implementation resolves the tag at install time (typically `latest`) and records the resolved digest in `skills.lock.json`.
`additionalBasePaths`	array of strings	OPTIONAL	Extra base directories where the skill should also be installed (e.g., `[".claude/skills", ".vibe/skills"]`). The skill is always installed to the default `.agents/skills` directory; entries in this array specify additional vendor-specific directories that receive a copy of the same skill content. When omitted, the skill is installed only to the default location.

Example skills.json:

{
  "skills" : [ 
    {
      "name" : "manage-pull-requests",
      "source" : "ghcr.io/thomasvitale/agent-skills/manage-pull-requests",
      "version" : "1.0.0"
    },
    {
      "name" : "upgrade-spring-boot",
      "source" : "ghcr.io/thomasvitale/agent-skills/upgrade-spring-boot",
      "version" : "1.0.0",
      "additionalBasePaths" : [ ".claude/skills", ".vibe/skills" ]
    }
  ]
}

7. Lock File

7.1 Purpose

Once a skill is installed from an OCI Artifact into a project, the project needs a mechanism to:

Record exactly which version was installed, enabling deterministic reproduction.
Check whether an update is available by comparing the installed digest against the current digest for the same tag.
Perform an automated upgrade by pulling the new artifact and replacing the existing directory.

The lock file serves all three purposes. This model is deliberately analogous to package manager lock files (e.g., package-lock.json, Cargo.lock, go.sum) and gives teams full control over when and how they adopt updates.

7.2 File Location

The lock file MUST be placed at the project root, alongside skills.json and the .agents/ directory:

my-project/
  .agents/
    skills/
      manage-pull-requests/
        SKILL.md
        scripts/
      upgrade-spring-boot/
        SKILL.md
  skills.json
  skills.lock.json

Placing the lock file at the project root (rather than inside .agents/) makes it easy to commit to version control, diff in code review, and process with standard tooling. The lock file SHOULD be committed to version control so that every team member and CI environment installs identical skill versions.

7.3 Schema

skills.lock.json is a JSON file with the following structure:

Field	Type	Required	Description
`lockfileVersion`	integer	REQUIRED	Version of the lock file schema. Clients MUST reject lock files whose `lockfileVersion` they do not recognize. Current value: `1`.
`generatedAt`	string (date-time)	REQUIRED	ISO 8601 timestamp recording when this lock file was last generated or updated.
`skills`	array of lock file entry objects	REQUIRED	List of installed skill entries.

Each lock file entry object contains:

Field	Type	Required	Description
`name`	string	REQUIRED	Skill name as declared in `SKILL.md`. Used as the key for update checks and removal operations.
`path`	string	REQUIRED	Relative path (from project root) to the primary extracted skill directory. Typically `.agents/skills/<name>`.
`additionalPaths`	array of strings	OPTIONAL	Relative paths to additional copies of the skill in vendor-specific directories (e.g., `[".claude/skills/<name>", ".vibe/skills/<name>"]`). Present only when the corresponding `skills.json` entry specifies `additionalBasePaths`. Used by the removal workflow to clean up all copies.
`source`	object	REQUIRED	The OCI origin of the installed skill (see source schema below).
`installedAt`	string (date-time)	REQUIRED	ISO 8601 timestamp of installation or last update.

The source object contains:

Field	Type	Required	Description
`registry`	string	REQUIRED	OCI registry hostname (e.g., `ghcr.io`).
`repository`	string	REQUIRED	Repository path within the registry, excluding the hostname.
`tag`	string	REQUIRED	The mutable tag resolved at install time (e.g., `1.2.0`, `latest`).
`digest`	string	REQUIRED	The immutable SHA-256 digest of the manifest that was pulled. Format: `sha256:<64 hex chars>`. This is the canonical identifier for update checks.
`ref`	string	REQUIRED	Fully-qualified, digest-pinned OCI reference. Format: `<registry>/<repository>:<tag>@<digest>`. Sufficient to re-pull the exact same artifact.

Example skills.lock.json:

{
  "lockfileVersion": 1,
  "generatedAt": "2026-04-01T21:00:01.485386Z",
  "skills": [
    {
      "name": "manage-pull-requests",
      "path": ".agents/skills/manage-pull-requests",
      "source": {
        "registry": "ghcr.io",
        "repository": "thomasvitale/agent-skills/manage-pull-requests",
        "tag": "1.0.0",
        "digest": "sha256:bc6708cbbc37adb919157f04d31e601e68f4b9c24b35c655079da87ad0e30f86",
        "ref": "ghcr.io/thomasvitale/agent-skills/manage-pull-requests:1.0.0@sha256:bc6708cbbc37adb919157f04d31e601e68f4b9c24b35c655079da87ad0e30f86"
      },
      "installedAt": "2026-04-01T21:00:54.763380Z"
    },
    {
      "name": "upgrade-spring-boot",
      "path": ".agents/skills/upgrade-spring-boot",
      "additionalPaths": [
        ".claude/skills/upgrade-spring-boot",
        ".vibe/skills/upgrade-spring-boot"
      ],
      "source": {
        "registry": "ghcr.io",
        "repository": "thomasvitale/agent-skills/upgrade-spring-boot",
        "tag": "1.0.0",
        "digest": "sha256:48f9f03d0b463016b32616f2c5807330462e182ec8dfe6dbfd10a3ed8ef94ca7",
        "ref": "ghcr.io/thomasvitale/agent-skills/upgrade-spring-boot:1.0.0@sha256:48f9f03d0b463016b32616f2c5807330462e182ec8dfe6dbfd10a3ed8ef94ca7"
      },
      "installedAt": "2026-04-01T21:00:01.485364Z"
    }
  ]
}

7.4 Update Check Workflow

A conforming implementation (CLI, CI job, IDE plugin) performing update checks SHOULD follow this algorithm for each entry in skills.lock.json:

Resolve the current digest. Query the registry for the current digest behind source.tag at source.registry/source.repository.
Compare digests. If the resolved digest differs from source.digest in the lock file, an update is available for that tag.
Optionally check for higher versions. The implementation MAY additionally query the registry for tags that represent a higher semantic version than source.tag.
Apply the update. Pull the new artifact, extract it to path, replace the existing skill directory, and update the lock file entry with the new digest, tag, ref, and installedAt values.

8. Supply Chain Security

Agent skills frequently include executable scripts that an AI agent may run with the developer's privileges. Verifying the provenance and integrity of a skill before installation is therefore a critical security requirement.

OCI Distribution Spec v1.1 introduces the Referrers API (GET /v2/<name>/referrers/<digest>), which returns an OCI Index listing all manifests whose subject field points to the given digest. This is the standard mechanism for attaching signatures, SBOMs, and attestations to any OCI Artifact without modifying the artifact itself.

8.1 Signing with Cosign (Sigstore)

After pushing a Skill Artifact, the publisher SHOULD sign it using Cosign. Cosign stores the signature as a referrer to the skill manifest.

Conforming implementations SHOULD support verifying Cosign signatures before extracting a skill artifact. Implementations MAY allow users to configure trusted identities and OIDC issuers.

8.2 Attestations

In-toto attestations (e.g., SLSA provenance, SBOMs, vulnerability scan results) are attached using Cosign's attest command. The artifactType of the attestation manifest distinguishes the attestation type in the Referrers API response.

The Referrers API response for a signed, attested skill will contain entries for each attached artifact.

9. File System Layout After Installation

After pulling one or more skills into a project, the resulting layout conforms to the Agent Skills Specification directory structure:

my-project/
  .agents/
    skills/
      manage-pull-requests/
        SKILL.md
        scripts/
          create-pr.sh
      upgrade-spring-boot/
        SKILL.md
  skills.json
  skills.lock.json

The extracted directory structure is identical to a skill directory created manually. The OCI packaging layer is transparent once extraction is complete. The consuming agent sees only standard skill directories as defined by the Agent Skills Specification.

That is true both for a project directory or for a global skills directory (e.g., ~/.agents/skills/) if the implementation supports that. The installation process is the same: pull the OCI artifact, extract the content layer, and place it in the appropriate location. The agent itself interacts with skill directories in a uniform way regardless of their origin.

9.1 Multi-Vendor Installation Layout

When additionalBasePaths are configured in skills.json, the installer copies the skill content to additional vendor-specific directories alongside the primary .agents/skills location. For example, if upgrade-spring-boot specifies additionalBasePaths: [".claude/skills", ".vibe/skills"], the resulting layout is:

my-project/
  .agents/
    skills/
      manage-pull-requests/
        SKILL.md
        scripts/
          create-pr.sh
      upgrade-spring-boot/
        SKILL.md
  .claude/
    skills/
      upgrade-spring-boot/
        SKILL.md
  .vibe/
    skills/
      upgrade-spring-boot/
        SKILL.md
  skills.json
  skills.lock.json

The OCI artifact is fetched only once; the vendor directories receive a file-system copy of the extracted content. Each vendor directory follows the same <base>/skills/<skill-name>/ convention, so agent implementations that scan their own vendor directory (e.g., Claude Code scanning .claude/skills/) discover the skill transparently.

10. Registry Compatibility

This specification builds on standard OCI primitives and is compatible with any registry that supports OCI Image Spec v1.1 and OCI Distribution Spec v1.1.

The following registries are known to support the required features:

Registry	Custom Artifact Types	Referrers API
GitHub Container Registry (ghcr.io)	Yes	Yes
AWS Elastic Container Registry (ECR)	Yes	Yes
Google Artifact Registry (GAR)	Yes	Yes
Azure Container Registry (ACR)	Yes	Yes
Docker Hub	Yes	Yes
Harbor	Yes	Yes
Zot Registry	Yes	Yes

For registries that do not yet implement the Referrers API, OCI Distribution Spec v1.1 defines a fallback tag mechanism: the client maintains a tag of the form sha256-<digest> that mirrors the Referrers API response. ORAS and Cosign both implement this fallback transparently.

11. Reference Implementation

11.1 Arconia CLI

Arconia CLI provides a reference implementation of this specification in Java, built on the ORAS Java SDK. The implementation includes:

Skill publishing (SkillPublisher): Validates the skill directory, parses SKILL.md frontmatter, builds the config blob and annotations, creates a deterministic tar+gzip archive, and pushes the resulting Skill Artifact with correct media types and artifact type.
Skill installation (SkillInstaller): Resolves the OCI reference to a manifest digest, pulls the content layer, extracts the archive into the project's .agents/skills/ directory, and updates both skills.json and skills.lock.json. Supports additionalBasePaths to copy the extracted skill to vendor-specific directories (e.g., .claude/skills/, .vibe/skills/) in a single operation.
Skills collection publishing (SkillCollectionPublisher): Constructs an OCI Image Index referencing individual Skill Artifacts by digest, with per-descriptor annotations for browsing.
Skills collection reading (SkillCollectionReader): Fetches the skills collection index and extracts skill metadata without downloading content layers.
Lock file management (SkillsLockfile): Loads, updates, and saves the skills.lock.json file with full source traceability.
Manifest management (SkillsManifest): Loads, updates, and saves the skills.json file.

The media types, annotation keys, and config schemas used in the reference implementation correspond directly to the constants defined in SkillMediaTypes and SkillAnnotations, and the record types SkillConfig, SkillsLockfile, SkillsManifest, and SkillsCollection.

There is work in progress to publish a common Java library that implements the core operations described in this specification (OCI interactions, manifest construction, lock file management) so that other Java-based tools can build on the same foundation. If you are interested in using or contributing to the Java library, please reach out.

See the detailed walkthrough in examples/arconia-cli.md.

The arconia-io/agent-skills repository showcases the Arconia CLI in action, with example skill directories, published Skill Artifacts and a Skills Collection on GitHub Container Registry, all conforming to the specification and automated via GitHub Actions workflows.

11.2 ORAS CLI

The entire specification can be exercised using only the ORAS CLI and standard Unix tools. No custom tooling is required to publish, pull, browse, or verify skill artifacts.

See the detailed walkthrough in examples/oras-cli.md.

11.3 ORAS Client Libraries

Developers building their own implementations can use the ORAS client libraries, which are available for:

Go
Python
Rust (in progress)
C# (in progress)
Java (in progress)

These libraries implement the OCI Distribution Spec client operations (push, pull, resolve, copy) and provide the foundation for building conforming tools in any of these languages.

12. Future Considerations

The following areas are identified for potential future specification revisions.

Versioning Policy. The relationship between the tag on the OCI artifact and the version in the config is currently informational. A future revision may add an explicit policy for which semantic version ranges a client should consider compatible when performing automatic updates.

Skills Collection Namespacing. Skills collection publishers may wish to scope skills within a skills collection (e.g., by domain: security, ci, docs). The io.agentskills.* annotation namespace can be extended with a io.agentskills.skill.categories annotation (comma-separated list) to support filtering in collection browsing tools.

Manifest Dependency Declaration. The current skills.json format supports flat lists of independent skills. A future revision may introduce dependency relationships between skills, enabling a skill to declare that it requires another skill to be present.

Deferred Pulling of Skills. Agents read each skill's name and description when starting a new session, but the full skill content is not needed until the agent decides to invoke the skill. It might be worth investigating how to use the concept of Skills Collection to provide an agent with the necessary metadata about available skills without pulling the full content until needed.

13. Acknowledgments

This specification builds upon the work of the following projects and standards:

Agent Skills Specification by Anthropic.
OCI Image Specification v1.1 by the Open Container Initiative.
OCI Distribution Specification v1.1 by the Open Container Initiative.
ORAS (OCI Registry As Storage) by the CNCF.
Sigstore and Cosign for supply-chain security tooling.
Flux for inspiration on declarative configuration packaged and distributed via OCI Artifacts.