Supported formats

AI Skills registry

An AI agent skill is a folder that contains a SKILL.md file with instructions that an AI agent loads when it needs them. A skill can also include scripts, reference files, and templates.

Cloudsmith hosts, versions, scans, and distributes skills and plugins in public or private repositories.

For more information, see:

• Agent Skills specification: The format of a skill and its SKILL.md file
• Claude Code plugins: How Claude Code plugins and plugin marketplaces work

Early Access

The AI Skills format is available in Early Access. Details on this page, including Cloudsmith CLI commands, may change while the format is in Early Access.

What Cloudsmith supports

Cloudsmith AI Skills repositories support:

• Public and private repositories: Serve skills to anyone or only to authenticated users.
• Skills and plugins: Upload a skill as a .zip archive that contains a SKILL.md file, or a plugin as a .zip archive that contains a .claude-plugin/plugin.json file.
• Versioning: Identify every release by a semantic version or a full Git commit SHA.
• Malware scanning and policies: Serve a release only after its malware scan completes and your policies allow it.
• Upstream caching from GitHub: Cache skills and plugins from a GitHub repository. For more information, see Upstream proxying / caching.
• Connected repositories: Make skills from other repositories available through one repository. For more information, see Connected repositories.

Cloudsmith serves the packages in an AI Skills repository from skills.cloudsmith.io, or from your custom domain if you set one up.

In the following examples:

Upload a package

You can upload a skill or a plugin with the Cloudsmith CLI, the Cloudsmith API, or the Cloudsmith web app. Every upload is a single .zip archive. An archive with a .claude-plugin/plugin.json file is a plugin. Any other archive is a skill and must contain a SKILL.md file.

The following sections apply to both skills and plugins: Versions, Limits and rejected content, and Files created for each upload. For the archive layout of each type, see Upload a skill and Upload a plugin.

Versions

Every upload needs a version: either a complete semantic version in the form MAJOR.MINOR.PATCH, or the full Git commit SHA that the skill was built from. Semantic versions can include pre-release and build suffixes.

Use a commit SHA for a skill without a semantic version. When Cloudsmith chooses the latest version, releases with a semantic version always rank higher than releases with a commit SHA. Releases with a commit SHA rank by upload time, newest first.

If you upload a version that already exists, Cloudsmith rejects it as a duplicate unless republishing is enabled. Republishing overwrites the existing package. To enable republishing for a single upload, set the republish API field or use the --republish CLI option. To allow it for all uploads, enable the Replace packages by default repository setting. To keep the existing package, upload the skill with a new version.

A skill and a plugin in the same repository cannot have the same name and version. Cloudsmith rejects the second upload.

Limits and rejected content

• Archive size: up to 10 MiB. The total size once expanded can be up to 25 MiB.
• Entries: up to 1,000 entries, nested at most 16 folders deep. SKILL.md can be up to 1 MiB, with up to 64 KiB of frontmatter.
• File types: only regular files and folders. Cloudsmith rejects symbolic links, encrypted entries, and compression methods other than Store and Deflate.
• Paths: Cloudsmith rejects paths that contain .. segments or backslashes, names that differ only by case, and names that Windows reserves, such as CON or LPT1.
• Frontmatter: cannot use YAML anchors, aliases, or tags, and cannot repeat a key.
• macOS folders: Cloudsmith allows the __MACOSX folder that macOS adds when you compress a folder.

Files created for each upload

Cloudsmith processes each upload after it validates the archive. The files that a package contains depend on its type:

The marketplace serves a plugin from the archive that you uploaded. It does not list skills. To install a skill, use the archive that you uploaded.

Upload a skill

Skill structure

Upload an AI skill as a single .zip archive that contains one skill. Cloudsmith validates the archive without extracting it.

The archive must contain exactly one SKILL.md file, either at the root of the archive or inside a single top-level folder. Any other files that the skill needs, such as scripts, references, and templates, can sit alongside it in subfolders:

pdf-processing/
├── SKILL.md            (required)
├── references/
│   └── REFERENCE.md
└── scripts/
    └── extract.py

To build the archive from the skill folder, run:

zip -r pdf-processing-1.0.0.zip pdf-processing

This creates an archive with a top-level pdf-processing folder. To put SKILL.md at the root of the archive instead, compress the contents of the folder:

cd pdf-processing && zip -r ../pdf-processing-1.0.0.zip .

Both layouts are valid. The Cloudsmith CLI can also build the archive for you. For more information, see Upload a skill folder.

SKILL.md format

SKILL.md must be UTF-8 and start with a YAML frontmatter block between two --- lines, followed by the skill instructions in Markdown. The format follows the Agent Skills specification:

---
name: pdf-processing
description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
license: Apache-2.0
metadata:
  author: example-org
  version: "1.0.0"
---

Version and publisher

Where Cloudsmith gets the version and the publisher depends on how a skill gets into your repository:

Author

metadata.author is for agents and other tools that read SKILL.md. Cloudsmith does not use it to set the publisher.

Upload via the Cloudsmith CLI

To upload a skill archive, run:

cloudsmith push skills WORKSPACE/REPOSITORY SKILL_NAME-VERSION.zip \
  --name SKILL_NAME \
  --version VERSION

The --name and --version options are required.

Use --changelog to add release notes of up to 4,096 characters. You can also add standard push options, such as --tags, --republish, and --no-wait-for-sync.

You can use the same command to upload a plugin. For more information, see Upload a plugin package.

Upload a skill folder

To upload a skill folder instead of an archive, pass the folder and add --compress:

cloudsmith push skills WORKSPACE/REPOSITORY ./SKILL_NAME \
  --compress \
  --name SKILL_NAME \
  --version VERSION

With --compress, the CLI compresses the contents of the folder into a .zip archive with SKILL.md at the root, uploads the archive, and then deletes it. The CLI:

• Leaves out .DS_Store, ._*, __MACOSX, .git, and .env.
• Keeps all other files, including dotfiles such as .claude-plugin/.
• Rejects all symbolic links.

Without --compress, the command fails with the error directories require --compress. If you pass a .zip file with --compress, the CLI uploads the file unchanged.

Other sensitive files

The CLI ignores common files such as .git and .env. Ensure that the folder does not contain secrets, such as credential files, before you upload it.

For more information about installing and authenticating the CLI, see Command-line interface.

Upload via the Cloudsmith API

Uploading a package with the API takes two requests: first, upload the file to get a single-use identifier, then create the package with that identifier.

1. Upload the archive. The response contains the identifier:

   shell

   curl -X PUT -H "X-Api-Key: API_KEY" \
     --upload-file SKILL_NAME-VERSION.zip \
     "https://upload.cloudsmith.io/WORKSPACE/REPOSITORY/SKILL_NAME-VERSION.zip"

2. Create the package. Replace IDENTIFIER with the identifier from the previous response:

   shell

   curl -X POST -H "X-Api-Key: API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"package_file": "IDENTIFIER", "name": "SKILL_NAME", "version": "VERSION"}' \
     "https://api.cloudsmith.io/packages/WORKSPACE/REPOSITORY/upload/skills/"

   To add release notes, include an optional changelog field in the request body.

For more information, see Upload via Cloudsmith API and the AI Skills upload API reference.

Upload via the web app

To learn how to upload a package in the web app, see Upload via Cloudsmith web app.

Select AI Skills as the package format, then enter the Skill name and the Version for the archive. The skill name must match the name in SKILL.md.

Download / install a skill

To install a skill, download its archive and unpack it into a skills folder that your agent reads. Cloudsmith does not list skills in the plugin marketplace. Use the archive that you uploaded, not the SKILL_NAME-claude.zip file, which is a one-skill plugin that Cloudsmith generates.

Download the archive

Download the archive with the Cloudsmith CLI:

cloudsmith download WORKSPACE/REPOSITORY SKILL_NAME --version VERSION

The command saves the archive that you uploaded to the current folder. The file keeps the filename that it had when you uploaded it. For a private repository, the CLI authenticates with your API key. For example, set the CLOUDSMITH_API_KEY environment variable for the command:

CLOUDSMITH_API_KEY=API_KEY cloudsmith download WORKSPACE/REPOSITORY SKILL_NAME --version VERSION

You can also download the archive with the native API. Cloudsmith redirects the request to the archive, so the command follows redirects:

curl -fL -o SKILL_NAME-VERSION.zip \
  'https://skills.cloudsmith.io/WORKSPACE/REPOSITORY/api/v1/download/PUBLISHER/SKILL_NAME/VERSION'

For a private repository, authenticate with an entitlement token:

curl -fL -u "token:TOKEN" -o SKILL_NAME-VERSION.zip \
  'https://skills.cloudsmith.io/WORKSPACE/REPOSITORY/api/v1/download/PUBLISHER/SKILL_NAME/VERSION'

To use an API key instead, replace token:TOKEN with token:API_KEY. Treat entitlement tokens and API keys as secrets, and do not commit them to source control or expose them in logs.

• PUBLISHER: The publisher of the skill. For a skill that you uploaded, this is your workspace slug. For a skill that Cloudsmith cached from GitHub, see Version and publisher.
• VERSION: The exact version of the skill.
• -L: Makes curl follow redirects. Required, because the response is a redirect.
• -f: Makes curl fail on an HTTP error instead of saving the error response.

If an upstream has indexed a release but Cloudsmith has not cached it yet, the request waits while Cloudsmith fetches, validates, and scans the release. Cloudsmith then serves the cached copy.

You can also download the archive from the Files tab of the package page in the Cloudsmith web app.

Unpack the archive

Unpack the archive into the skills folder for the scope that you want. The folders in the following table are for Claude Code; for details about other agents, see the external documentation for your agent.

The result must be SKILL_NAME/SKILL.md inside the skills folder. If SKILL.md is at the root of the archive, unpack it into a folder named after the skill. If the archive has a single top-level folder named after the skill, unpack it into the skills folder itself:

# SKILL.md at the root of the archive
unzip ARCHIVE_FILE -d ~/.claude/skills/SKILL_NAME

# SKILL.md inside a top-level folder
unzip ARCHIVE_FILE -d ~/.claude/skills

For a project, run the same command from the project root and replace ~/.claude/skills with .claude/skills. Commit the folder to share the skill with your team.

Confirm that the file is in place:

ls ~/.claude/skills/SKILL_NAME/SKILL.md

To update the skill, delete the existing skill folder, then download and unpack the new version. For more information about skills in Claude Code, see Extend Claude with skills in the Claude Code documentation.

Example skill workflow

To publish a skill and install it for Claude Code:

1. Package the skill folder and upload it:

   shell

   zip -r SKILL_NAME-VERSION.zip SKILL_NAME
   
   cloudsmith push skills WORKSPACE/REPOSITORY SKILL_NAME-VERSION.zip \
     --name SKILL_NAME \
     --version VERSION

2. Wait for the malware scan to finish and for your policies to allow the release. Cloudsmith does not serve the release until then.

3. Download the archive:

   shell

   cloudsmith download WORKSPACE/REPOSITORY SKILL_NAME --version VERSION

4. Unpack the archive into your personal skills folder. The archive has a top-level SKILL_NAME folder, so unpack it into the skills folder itself:

   shell

   unzip SKILL_NAME-VERSION.zip -d ~/.claude/skills

Verify the archive

To confirm that the archive was not corrupted or modified, calculate its SHA-256 checksum and compare it with the checksum on the package page in the Cloudsmith web app:

shasum -a 256 -- 'SKILL_NAME-VERSION.zip'

On Linux, run sha256sum SKILL_NAME-VERSION.zip instead.

The package page shows the checksum of the archive exactly as it was uploaded. If the values do not match, do not use the file.

Discover skills

For public repositories, Cloudsmith publishes a discovery index that follows the Agent Skills discovery format. Agents and tools use the index to list the skills that a repository serves. To get the index, run:

curl -1sLf 'https://skills.cloudsmith.io/WORKSPACE/REPOSITORY/.well-known/agent-skills/index.json'

Each entry contains the skill name, its description, the download url, and a digest that is the SHA-256 checksum of the archive.

• The index is available only for public repositories. Private repositories return a 404 error.
• The index supports up to 100 skills. For a repository with more than 100 skills, the index returns a 413 error.
• If two publishers have a skill with the same name, the index returns a 409 error because it requires unambiguous skill names.

Upload a plugin

Plugin structure

Cloudsmith treats an archive as a plugin when it contains a .claude-plugin/plugin.json file at its root or inside a single top-level folder. A plugin can bundle any number of skills, along with agents, commands, hooks, and Model Context Protocol (MCP) or Language Server Protocol (LSP) servers. Cloudsmith serves the plugin to the agent exactly as you uploaded it.

example-plugin/
├── .claude-plugin/
│   └── plugin.json     (required)
├── skills/
│   └── example-skill/
│       └── SKILL.md
├── agents/
│   └── reviewer.md
└── hooks/
    └── hooks.json

To build the archive from the plugin folder, run:

zip -r example-plugin-1.0.0.zip example-plugin

Plugin requirements

• plugin.json must be a JSON object whose name follows the same rules as a skill name and matches the name that you enter at upload. If plugin.json sets a version, it must match the uploaded version.
• Every bundled SKILL.md must follow the rules in SKILL.md format, except that name defaults to its folder name and description is optional. This matches how Claude Code reads bundled skills.
• Component paths in plugin.json must start with ./ and stay inside the plugin. The hooks/hooks.json, .mcp.json, and .lsp.json files must be valid JSON objects.
• The rules in Limits and rejected content apply to the whole plugin.

Plugin code detection

Cloudsmith detects hooks, MCP servers, LSP servers, monitors, and executables in a plugin on a best-effort basis, and exposes the results as policy input fields. To block every plugin that can run code, match subtype == "plugin" instead of relying on these fields.

Upload a plugin package

Upload a plugin with the same commands as a skill. Set the name to the name in plugin.json. To upload a plugin folder with the CLI, use --compress:

cloudsmith push skills WORKSPACE/REPOSITORY ./PLUGIN_NAME \
  --compress \
  --name PLUGIN_NAME \
  --version VERSION

For the API, send the same two requests as in Upload via the Cloudsmith API with the plugin name and version. In the Cloudsmith web app, select AI Skills and enter the plugin name in the Skill name field.

View the skills in a plugin

The package details API returns a plugin_skills list for a plugin. Each entry has the name and description of a skill that the plugin bundles. Cloudsmith truncates each description to 200 characters. The field is null for a skill.

Download / install a plugin

Claude Code installs plugins from a plugin marketplace. Cloudsmith generates a marketplace for every AI Skills repository, so you do not need to create or upload a marketplace file. The marketplace lists the latest available version of each plugin. It does not list skills. To install a skill, see Download / install a skill.

Code execution in plugins

A plugin can run code on your machine through hooks, MCP servers, LSP servers, monitors, and executables. Review a plugin before you install it.

To install plugins from your repository, run the following commands in a Claude Code session:

1. Add your repository as a plugin marketplace. You only need to do this once for each repository:

   text

   /plugin marketplace add https://skills.cloudsmith.io/WORKSPACE/REPOSITORY/.claude-plugin/marketplace.json

   This registers the marketplace as WORKSPACE-REPOSITORY.

2. Browse the plugins in the marketplace:

   text

   /plugin

3. Install a plugin by name:

   text

   /plugin install PLUGIN_NAME@WORKSPACE-REPOSITORY

The marketplace lists only releases that have passed malware scanning and that your policies and quarantine rules allow. For more information, see Blocked releases.

The marketplace returns a 409 error if two plugins that you uploaded to your repository have the same name, and a 413 error if the marketplace is too large to build. For more information, see Releases with the same name.

Private repositories

For a private repository, add an entitlement token to the marketplace URL:

/plugin marketplace add https://token:TOKEN@skills.cloudsmith.io/WORKSPACE/REPOSITORY/.claude-plugin/marketplace.json

Cloudsmith uses the same credentials to download the plugins that the marketplace lists, so you don't need any other setup.

Secrets management

Treat entitlement tokens and API keys as secrets. Do not commit them to source control or expose them in logs.

Example plugin workflow

To publish a plugin and install it in Claude Code:

1. Package the plugin folder and upload it:

   shell

   zip -r PLUGIN_NAME-VERSION.zip PLUGIN_NAME
   
   cloudsmith push skills WORKSPACE/REPOSITORY PLUGIN_NAME-VERSION.zip \
     --name PLUGIN_NAME \
     --version VERSION

2. Wait for the malware scan to finish and for your policies to allow the release. Cloudsmith does not list the release in the marketplace until then.

3. In a Claude Code session, add the marketplace and install the plugin:

   text

   /plugin marketplace add https://skills.cloudsmith.io/WORKSPACE/REPOSITORY/.claude-plugin/marketplace.json
   /plugin install PLUGIN_NAME@WORKSPACE-REPOSITORY

4. To confirm that the plugin is installed, run the following command in a terminal:

   shell

   claude plugin list

   The output lists PLUGIN_NAME@WORKSPACE-REPOSITORY with the version that you uploaded and an enabled status.

Upstream proxying / caching

The AI Skills format supports upstream caching from GitHub repositories. Cloudsmith indexes the skills and plugins in a GitHub repository, and caches a release in your repository after it is validated and scanned.

Supported upstream sources

Strict mode

AI Skills upstreams use strict mode, which evaluates policies in the sync pipeline before a package sync completes. Skills are bundled from GitHub repositories before being cached, so these upstreams use cache only package delivery.

Strict mode isn't yet enabled by default for all workspaces. To use AI Skills upstreams, contact Cloudsmith support to enable it for your workspace.

Access token required

A GitHub upstream requires a GitHub access token, for example, a personal access token. For more information, see Managing your personal access tokens in the GitHub documentation.

Unauthenticated requests to GitHub are limited to 60 requests per hour for each IP address, and a token raises the limit to 5,000 requests per hour. For a public repository, the token does not need any special permissions. For a private repository, the token must be able to read the repository.

Each upstream uses its own token, so there is no pre-configured GitHub upstream. Create a custom upstream with your own token.

What Cloudsmith indexes

• Skills: Every folder that contains a SKILL.md file is a skill, including skills nested inside other skills, up to four levels deep. A skill includes its whole folder, including nested skills.
• Plugins: The repository root is a plugin if it contains .claude-plugin/plugin.json. A folder is also a plugin if the .claude-plugin/marketplace.json file at the repository root lists it. The marketplace.json file lists plugins only, so Cloudsmith finds skills through their SKILL.md files. The upstream also indexes plugins that the marketplace.json file lists from other GitHub repositories, up to 2,500 plugins. Cloudsmith skips the plugins over this limit.
• Versions: If SKILL.md has a metadata.version that is a complete semantic version, Cloudsmith uses it. Otherwise, Cloudsmith uses the full commit SHA. A plugin uses the version in plugin.json, or the commit SHA if it does not set one. Cloudsmith skips a plugin whose plugin.json sets an invalid version. For more information, see Versions of GitHub skills.

Versions of GitHub skills

• A version keeps its content. Cloudsmith pins a declared version to the content that it first indexed. If a later push changes the files without changing the version, Cloudsmith does not offer the new files until the version changes.
• Versions only go up. Cloudsmith does not index a commit that removes the declared version, or that declares a lower version than the newest one it indexed.
• Earlier versions stay available. While a skill or plugin exists in the GitHub repository, Cloudsmith keeps up to 10 superseded versions available for download.
• Commit versions follow the content. A skill without a declared version uses the commit SHA. The version changes only when the files of the skill change.

Skills versioning setting

The Skills versioning repository setting controls which versions of GitHub skills the repository offers:

• The setting applies only to skills that Cloudsmith caches from GitHub upstreams. Uploaded skills and plugins keep their versions.
• A change takes effect immediately. Cloudsmith does not index again.
• With Require version, a skill that is already cached under a commit SHA stays available by that exact version. Cloudsmith no longer offers it as the latest version.

To change the setting, set the skills_versioning field when you create or update a repository with the API, or use Format Settings in the repository settings of the legacy web app at cloudsmith.io. For more information, see Repository settings.

Releases with the same name

A release is one version of a plugin. A marketplace entry is installed by name. When more than one plugin has the same name, Cloudsmith lists one of them in the marketplace, based on the following rules, in order:

• If two plugins that you uploaded have the same name, the marketplace returns a 409 error.
• If the winning release cannot be served, Cloudsmith does not list the name. It does not list a lower-ranked release instead. A release cannot be served while it is quarantined, blocked, or still being scanned, or if its fetch failed. For how Cloudsmith picks among the versions of one skill or plugin, see Blocked releases.

Configure an upstream

When you create the upstream, set the Proxy URL to the GitHub repository that you want to cache from, for example:

https://github.com/OWNER/REPO

The URL must point at the repository itself. Cloudsmith does not accept URLs that point at a branch, folder, or file, such as https://github.com/OWNER/REPO/tree/main/skills.

You can also create the upstream with the Cloudsmith API or the Cloudsmith CLI. Save the following configuration as skills-upstream.json:

{
  "name": "Example skills repository",
  "upstream_url": "https://github.com/OWNER/REPO",
  "mode": "Cache Only",
  "auth_mode": "Token",
  "auth_secret": "GITHUB_TOKEN",
  "contents": "Skills and plugins",
  "priority": 1
}

To create the upstream with the API, send the file to the upstream endpoint for your repository:

curl -X POST -H "X-Api-Key: API_KEY" \
  -H "Content-Type: application/json" \
  -d @skills-upstream.json \
  "https://api.cloudsmith.io/repos/WORKSPACE/REPOSITORY/upstream/skills/"

For more information, see the AI Skills upstream API reference.

To create the upstream with the Cloudsmith CLI, run:

cloudsmith upstream skills create WORKSPACE/REPOSITORY skills-upstream.json

Use the remaining subcommands to list, update, or delete AI Skills upstreams:

cloudsmith upstream skills list WORKSPACE/REPOSITORY
cloudsmith upstream skills update WORKSPACE/REPOSITORY/SLUG_PERM skills-upstream.json
cloudsmith upstream skills delete WORKSPACE/REPOSITORY/SLUG_PERM

For more information about form fields and configuration options, see Create an AI Skills upstream.

Security scanning

Cloudsmith scans every AI Skills package for malware. Cloudsmith serves a release only after its malware scan completes and your policies allow it. Quarantine and deny rules also apply to releases that Cloudsmith caches from an upstream.

Vulnerability scanning is not available for AI Skills.

Blocked releases

A release is blocked when it is quarantined, or when a deny rule or a policy blocks it. Cloudsmith leaves a blocked release out of the marketplace and the discovery index.

• If the newest release of a skill or plugin is blocked, Cloudsmith offers the newest earlier release that is available.
• If none of the 10 newest releases is available, Cloudsmith no longer offers the skill or plugin.
• A new release does not appear until its malware scan completes and policy evaluation finishes.

Policy input

Policy as code evaluates AI Skills packages like packages in other formats. The policy input for an AI Skills package includes the following fields. In a Rego policy, read them from input.v0.package:

The policy input does not include the publisher of a package.

Key signing support

Cloudsmith does not sign AI Skills packages, and Claude Code does not check package signatures. To confirm that an archive is unmodified, compare its SHA-256 checksum. For more information, see Verify the archive.

Limitations

• Cache only package delivery: Skills are bundled from GitHub repositories before being cached, so AI Skills upstreams cannot proxy requests and use cache only package delivery, which is available with strict mode. Strict mode isn't yet enabled by default for all workspaces. For more information, see Upstream proxying / caching.
• GitHub rate limits: GitHub limits unauthenticated requests to 60 requests per hour for each IP address, and requests with a token to 5,000 requests per hour. If GitHub rate limits the token, Cloudsmith pauses indexing and retries after the delay that GitHub gives, up to one hour, so new releases can take longer to appear.
• Releases with the same name: A plugin that you upload to the repository wins over a plugin with the same name from an upstream. For more information, see Releases with the same name.
• Name conflicts: A skill and a plugin in the same repository cannot have the same name and version. If two publishers have a skill with the same name, the discovery index returns a 409 error.
• Marketplace files in GitHub repositories: The .claude-plugin/marketplace.json file in a GitHub repository lists plugins only. Cloudsmith finds skills through their SKILL.md files.
• Size limits: The marketplace returns a 413 error if it is too large to build, and the discovery index supports up to 100 skills.
• Vulnerability scanning: Not available for AI Skills.
• Policy input: Does not include the publisher of a package.

Updated 2 minutes ago