DEV Community

Cover image for AI Skills and How to Distribute Them
Mohammad-Ali A'RÂBI
Mohammad-Ali A'RÂBI

Posted on Originally published at containersecurity.dev

AI Skills and How to Distribute Them

AI world is a wild west, and AI coding agents are the new cowboys. It makes things exciting, but also chaotic. In this post, I try to explain the current situation on AI Agent Skills, because I also didn't know and had to learn it the hard way.

TL;DR: AI Skills are reusable packages. They are NPM packages to your React website, plugable devices to your laptop, and mods to your Skyrim game.

So, let's sit through the chaos and see what we can learn.

An armored robotic cowboy named Jack springs from an AI package, surrounded by glowing code, tool, and workflow symbols.

What Is an Agent Skill?

The Agent Skills specification defines a portable format centered around a SKILL.md file.

A skill typically looks like this:

my-skill/
├── SKILL.md
├── scripts/
│   └── validate.sh
├── references/
│   └── guidelines.md
└── assets/
Enter fullscreen mode Exit fullscreen mode

Only SKILL.md is required. The other directories are optional.

The file begins with YAML frontmatter:

---
name: my-skill
description: "Validate a project against"
  security best practices.
---

# Security Validation

1. Inspect the project.
2. Identify security issues.
3. Recommend improvements.
4. Generate a report.
Enter fullscreen mode Exit fullscreen mode

The frontmatter means the part between two --- lines. It contains the skill's name, description, and other metadata, in a key-value format. It's called frontmatter because it's not the main content of the file, similar to a book's frontmatter that includes the title page, copyright, and table of contents.

The agent discovers the skill through its name and description, then loads the detailed instructions when needed. This mechanism is called progressive disclosure. It means that the agent doesn't need to load the entire skill until it is invoked, which saves memory and improves performance.

The specification defines how skills are structured, but not a universal distribution mechanism.

And that's where things become interesting.

Different AI Agent Clients

The Agent Skills format is supported by a growing number of clients:

  • Claude Code — Anthropic's coding agent, supporting skills and plugin-based distribution.
  • OpenAI Codex — Supports skills, bundled scripts, references, and client-specific metadata.
  • GitHub Copilot — Supports skills in coding agents, code review, and compatible IDE workflows.
  • Cursor — Discovers local skills and supports plugin-based distribution.
  • Gemini CLI — Google's terminal-based agent with support for skills.
  • Google Antigravity — Supports reusable skills for agent workflows.
  • OpenCode — Supports skills through project-level and user-level directories.
  • OpenClaw — Supports skills distributed through ClawHub.

Most of these clients support the same core SKILL.md format, but installation locations, invocation behavior, supported metadata, and security controls can differ.

For example, one client might discover a skill from .agents/skills/, while another expects .claude/skills/ or .github/skills/.

Portable format does not necessarily mean portable behavior.

Skill authors should test the same workflow across their intended clients rather than assuming that format compatibility guarantees identical execution.

Where Can You Publish Skills?

Unlike traditional software packages, AI Agent Skills do not have a single dominant registry like npm or PyPI.

Instead, there are several marketplaces, directories, and distribution mechanisms.

Skill Marketplaces and Directories

  • skills.sh — A popular directory and installation ecosystem. Skills are distributed from GitHub repositories using the skills CLI.
  • SkillsMP — A marketplace that indexes public GitHub repositories containing Agent Skills.
  • ClawHub — The OpenClaw skill registry, supporting direct publishing, versioning, and installation through its CLI.
  • GitHub — A natural distribution location for portable skills. GitHub CLI also provides gh skill commands for discovery, installation, and publishing.
  • LobeHub Skills — A community marketplace supporting GitHub-hosted skills.

Plugin Marketplaces

Some platforms distribute skills as parts of larger plugins:

Publication processes vary considerably.

Some directories automatically discover GitHub repositories. Others require CLI authentication, packaging, manual submissions, or approval.

This creates a maintenance problem for skill authors: releasing one skill to several marketplaces may require multiple manifests, different packaging formats, and independent version tracking.

Publishing, Indexing, and Approval Are Different Steps

Getting a package into a registry, appearing in a search directory, and being accepted into a curated marketplace are three different outcomes. A successful upload only proves the first one.

For example, skills.sh uses installation telemetry for its leaderboard. SkillsMP indexes public GitHub content, and its developer API exposes discovery and search. Neither is a reason to add artificial installations to a release workflow or assume that a new tag guarantees a listing.

For SIP, I separated automated package publication from directory submissions. The release results below show which parts actually worked.

Skill vs. Kit vs. MCP Server

These concepts are related, but they solve different problems.

Concept Purpose Example
Agent Skill Teaches an agent how to perform a task Audit a Dockerfile and generate an SBOM
Docker Sandbox Kit Defines an agent's execution environment, tools, instructions, and capabilities A sandbox with Codex, Trivy, and restricted network access
MCP Server Exposes tools, resources, and prompts through a standardized protocol A tool that retrieves vulnerability information from a security service
Plugin Packages capabilities for installation in a particular ecosystem A plugin containing skills and an MCP server

A Skill answers how to do something.

An MCP server exposes what the agent can interact with.

A Docker Sandbox Kit defines the environment and capabilities available to the agent.

For example, consider an agent implementing a container security workflow:

  1. A Skill instructs the agent to inspect dependencies, build an SBOM, and scan for vulnerabilities.
  2. A Docker Sandbox Kit supplies the tools, configuration, credentials, and network restrictions required to perform those operations.
  3. An MCP server can expose additional capabilities, such as querying a vulnerability database.

These mechanisms complement one another.

Docker Sandbox Kits are particularly interesting because their v3 format uses ordinary OCI images. A Kit can be built, distributed, versioned, and signed using existing container tooling.

There is also an emerging MCP Skills extension that allows MCP servers to expose Agent Skills alongside their other capabilities. This further reduces the separation between reusable instructions and remotely provided tools.

Packaging Skills: Why Not OCI Artifacts?

We already know how to distribute software reliably.

Container images, Helm charts, SBOMs, and signatures can all be managed using OCI-compatible registries and tooling.

Why shouldn't Agent Skills work the same way?

A typical skill currently resides in a GitHub repository. Installation might involve cloning that repository, copying files into a particular directory, or using a marketplace-specific CLI.

This works, but introduces several challenges:

  • How do we identify an immutable version of a skill?
  • How can we verify its integrity and publisher?
  • How do we distribute private enterprise skills?
  • How do we synchronize releases across multiple platforms?
  • How can we attach provenance, signatures, and security reports?
  • Can we create an SBOM for a skill and its dependencies? Or perhaps an SkBOM (Skill Bill of Materials)?

OCI artifacts offer a possible answer.

Existing Proposals

Two notable specifications are being developed:

1. Agent Skills OCI Artifacts Specification

Thomas Vitale's proposal defines an OCI artifact format for individual skills and skill collections.

It introduces a dedicated artifact type:

application/vnd.agentskills.skill.v1
Enter fullscreen mode Exit fullscreen mode

The specification covers manifests, configuration, packaging, versioning, and digest-based installation. Implementations such as Arconia demonstrate publishing skills to OCI registries.

2. NVIDIA Agent Package Specification

NVIDIA proposes a broader format supporting both skills and plugins.

Its skill artifact type is:

application/vnd.agentpackage.skill.v1
Enter fullscreen mode Exit fullscreen mode

The proposal preserves native skill files while providing OCI metadata, file inventories, and integrity verification.

These approaches build on OCI conventions, but they use different artifact types and metadata schemas. Neither should be treated as the universally adopted packaging standard for Agent Skills.

What Would OCI Distribution Look Like?

Imagine publishing a skill under a registry reference such as:

ghcr.io/containersecurity-dev/sip:1.0.0
Enter fullscreen mode Exit fullscreen mode

A publishing pipeline could:

  1. Validate the SKILL.md specification.
  2. Package the skill and supporting resources.
  3. Publish a versioned OCI artifact.
  4. Sign the artifact using Cosign.
  5. Attach provenance and security attestations.
  6. Distribute it to compatible clients or marketplace adapters.

Consumers could pin the artifact using an immutable digest:

ghcr.io/containersecurity-dev/sip@sha256:...
Enter fullscreen mode Exit fullscreen mode

Existing OCI infrastructure could provide storage, authentication, access control, integrity verification, and artifact discovery.

However, OCI packaging does not automatically make a skill installable by every AI client. A compatible installer must still extract the artifact, validate its contents, and place the skill where the client expects it.

OCI solves much of the distribution problem. It does not eliminate platform compatibility requirements.

A Checklist for Skill Owners

Before publishing your skill, consider the following.

Specification and Compatibility

  • [ ] Does the skill conform to the Agent Skills specification?
  • [ ] Does SKILL.md contain valid name and description fields?
  • [ ] Does the skill's directory name match its declared name?
  • [ ] Have you tested the skill with the clients you claim to support?
  • [ ] Are platform-specific dependencies and limitations documented?

Security

  • [ ] Have you reviewed all scripts and bundled resources?
  • [ ] Have you checked for embedded credentials, tokens, and sensitive data?
  • [ ] Does the skill document its required tools, network access, and permissions?
  • [ ] Does it require explicit authorization before destructive or security-sensitive changes?
  • [ ] Have you checked the instructions for prompt-injection and dependency risks?
  • [ ] Are executable components tested, preferably in an isolated environment?

Packaging and Publication

  • [ ] Does the repository include a README and an explicit license?
  • [ ] Have you assigned a version and created release notes?
  • [ ] Can consumers install an immutable, reviewed release?
  • [ ] Have you considered signing your release and generating provenance?
  • [ ] Have you checked the licensing and submission requirements of each marketplace?
  • [ ] Can you reproduce the release package from the same source revision?
  • [ ] Have you verified that published marketplace listings reference the intended release?

Maintenance

  • [ ] Is there a process for updating the skill when dependencies or client APIs change?
  • [ ] Can users report bugs and security vulnerabilities?
  • [ ] Can you revoke, deprecate, or replace a compromised release?
  • [ ] Are old versions and compatibility changes documented?

A skill is not necessarily harmless because it consists primarily of Markdown. Its instructions may cause an agent to execute scripts, install dependencies, access credentials, or modify infrastructure.

Treat third-party skills as software supply-chain dependencies, not merely documentation.

What Does Checking These Boxes Actually Involve?

Reproducible packaging: Start with an explicit list of files to ship. Exclude .git, credentials, caches, and build output. Normalize archive ordering, timestamps, ownership, permissions, and gzip metadata, then build twice and compare the bytes. SIP's packaging script also rejects symlinks and writes a SHA-256 inventory. The resulting directory is sip/, matching name: sip, even though the repository is called sip-skill.

Integrity and provenance: A checksum tells you whether bytes match an expected value. If an attacker can replace both the download and its checksum, that alone does not establish who produced it. Build provenance adds a verifiable statement about the producing workflow and source. SIP's distribution jobs verify the repository, release workflow, and source tag before publishing the downloaded assets. This still does not prove the instructions are safe or that every client executes them correctly.

Security tests: Test failures that could bypass a control. During this work, I found that SIP's npm validator could skip a malformed dependency entry without a version. It now rejects that entry. Tests also cover registry failures, cooldown boundaries, and integrity mismatches. The validator compares lockfile values with registry metadata; it does not independently download and hash each dependency tarball. That distinction belongs in the documentation.

Safe retries: Multiple registries cannot be updated atomically. One can succeed while another fails. SIP runs each publication job independently and permits retries only when an existing version matches the intended files or package integrity. Different bytes cause a failure instead of an overwrite. Authentication failures also stop the job. Version-specific registry tags avoid moving a latest pointer backward when an older release is retried.

Putting It Into Practice: SIP

I recently created SIP — Security Immediate Plan, an Agent Skill for implementing five supply-chain security controls:

  1. Isolate AI agents using Docker Sandboxes.
  2. Enforce dependency publication cooldowns.
  3. Use Docker Hardened Images.
  4. Generate SBOMs and provenance attestations.
  5. Block promotion when fixable Critical vulnerabilities are detected.

SIP uses a canonical SKILL.md, additional technical references, and an executable npm lockfile validator with regression tests.

The core instructions remain in one place. Registry packages and client-specific plugin manifests are generated around that canonical skill. Format compatibility remains separate from tested behavior in each client.

What Shipped with SIP v1.0.0?

SIP v1.0.0 was published on November 17, 2026. Its completed distribution run verified the release assets and successfully handled GHCR and GitHub Packages. Here is the status at release time:

Channel How publication works SIP v1.0.0 status
GitHub Releases Build archives, attach provenance, create a draft, then publish it Published with three packages and checksums
GHCR Push the verified files as a versioned OCI bundle using ORAS Published successfully
GitHub Packages Publish the generated npm tarball using the workflow's GitHub token Published; matching package verified on retry
npmjs.org Publish the same npm tarball with npm credentials and namespace access Implemented but disabled; live publishing untested
Docker Hub Push the OCI bundle with registry credentials Implemented but disabled; live publishing untested
skills.sh / SkillsMP Make the GitHub source discoverable; directory indexing is separate No verified listing claimed
Claude / Cursor directories Generate plugin manifests and submit through the stores' review processes Plugin ZIP generated; client testing and submissions outstanding
LobeHub Claim ownership and publish through its authenticated user tooling Not automated or published by SIP
ClawHub Publish through its CLI under its distribution terms Excluded to preserve the chosen licensing terms

The npm package is @containersecurity-dev/sip-skill, containing skills/sip/ and supporting documentation. It has no install scripts or dependencies. Publishing it to GitHub Packages does not also publish it to npmjs.org, and installing the package does not automatically register the skill with an agent.

Licensing turned out to be a practical distribution constraint. ClawHub's publishing documentation says uploaded skills are released under MIT-0. I chose Apache-2.0 for SIP and excluded that channel rather than granting additional licensing terms as a side effect of automation. Check those requirements before treating a store as another upload destination.

From a Tag to Several Registries

SIP uses two workflows:

Version tag
  → validate metadata and run regression tests
  → build the canonical skill archive
  → derive npm and plugin packages
  → generate build provenance and create a draft release
  → publish the reviewed GitHub release
  → verify its downloaded assets
  → publish independently to each enabled registry
Enter fullscreen mode Exit fullscreen mode

The release workflow checks that the tag matches VERSION. The canonical archive is used to derive the npm tarball and Claude/Cursor plugin ZIP; the latter includes skills/sip/ and both clients' plugin manifests. All three archives receive provenance.

The distribution workflow starts when the stable GitHub release is published. It verifies the downloaded archives before handing them to registry clients. It does not rebuild the skill separately for each store.

GHCR and GitHub Packages use the workflow's scoped GitHub token. npm publishing requires the NPM_TOKEN secret and NPM_PUBLISH=true repository variable. Docker Hub has its own credentials and enable flag. Disabled jobs are reported as skipped, which is different from a successful publication. The distribution guide documents the exact setup and remaining manual submissions.

Downloading and Verifying the Release

With GitHub CLI installed and authenticated as needed, download the release assets into a new directory:

mkdir sip-v1.0.0
cd sip-v1.0.0

gh release download v1.0.0 \
  --repo ContainerSecurity-dev/sip-skill \
  --pattern 'sip-*.tar.gz' \
  --pattern 'sip-*.tgz' \
  --pattern 'sip-*.zip' \
  --pattern SHA256SUMS

sha256sum --check SHA256SUMS

gh attestation verify sip-1.0.0.tar.gz \
  --repo ContainerSecurity-dev/sip-skill \
  --signer-workflow ContainerSecurity-dev/sip-skill/.github/workflows/release.yml \
  --source-ref refs/tags/v1.0.0
Enter fullscreen mode Exit fullscreen mode

Use a GitHub CLI version that supports gh attestation verify. Verify the corresponding .tgz or .zip as well if that is the package you intend to install. Review the verified contents before copying sip/ into the chosen client's skill directory.

The OCI bundle can also be retrieved with ORAS, after registry authentication if required:

oras pull ghcr.io/containersecurity-dev/sip-skill:v1.0.0
Enter fullscreen mode Exit fullscreen mode

SIP uses the project-specific artifact type application/vnd.containersecurity.sip.bundle.v1. It is a bundle of downloadable files, not a runnable container or an implementation of either OCI skill proposal discussed earlier. Consumers can use the digest recorded by the publication job to pin the bundle immutably. They still need to verify and install the skill for their client.

The Release Failure That Local Tests Did Not Catch

The first GHCR job failed while installing ORAS. Although ORAS 1.3.0 existed, the pinned setup-oras action contained an older, bundled release catalog that did not recognize it.

I updated the installer action to a verified commit supporting that CLI version, then retried distribution from main against the existing release:

gh workflow run distribute.yml --ref main \
  -f tag=v1.0.0 --repo ContainerSecurity-dev/sip-skill
Enter fullscreen mode Exit fullscreen mode

GHCR then succeeded, and the GitHub Packages job verified the version already published by the first run. The v1.0.0 tag and release assets stayed unchanged.

Pinning tooling makes a pipeline reproducible, but the installer and requested tool version must also work together. Local packaging tests and workflow linting could not establish that; the hosted release run did.

What's Next?

The Agent Skills specification has made reusable AI workflows more portable. The next challenge is making their distribution equally reliable.

Ideally, a skill author should be able to write a skill once, validate it, publish a versioned artifact, and distribute it across compatible marketplaces.
With proper release management, immutable artifacts, digital signatures, security validation, and client-specific adapters, publishing Agent Skills could become as routine as publishing container images.

OCI provides much of the underlying infrastructure. What remains is agreement on packaging conventions, interoperable installers, and reliable marketplace integrations.

We have standardized how agents learn skills. Now we need to standardize how those skills travel.

Top comments (0)