# Getting started with the Chainguard Skills Registry

URL: https://chainguard-docs-preview-git-fix-learning-lab-jsonld.chainguard.app/chainguard/agent-skills/skills-registry.md
Last Modified: October 14, 2026
Tags: Agent Skills, Overview

Enable the Chainguard Skills Registry, then upload, harden, install, and run an agent skill scoped to your organization.


The Chainguard Skills Registry lets you publish, manage, and distribute skills scoped to your organization. Use `chainctl` to upload original skills to `uploads.cgr.dev`, submit them for hardening, and install the hardened results from `skills.cgr.dev`.

This guide walks through enabling the registry for your organization, then uploading, hardening, installing, and running a skill. For job tracking, digest-based submissions, and browsing user folders, see [Getting started with skill hardening](/chainguard/agent-skills/skill-hardening/).

> **Note**: Chainguard Skills Registry is in beta.


## Prerequisites

To follow this guide, you need:

* `chainctl` **v0.2.376** or later, installed and authenticated. Check your version with `chainctl version`. Refer to [How to install `chainctl`](/platform/chainctl-usage/how-to-install-chainctl/) if you don't have it yet.
* An active Chainguard organization.
* Owner access on the organization.

In the commands below, replace `your-organization` with your organization's name or UIDP (its unique identifier).

## Enabling the skills entitlement

Before your org can push or install skills, create a skills entitlement.

> **Note**: You must have the `owner` role in your organization to create a skills entitlement and accept the Skills Registry terms of service.

```shell
chainctl skills entitlements create --parent your-organization
```

```output
Created skills entitlement for org example.dev (717b474ac6972745c5706a898aa6e67ffba97dad)
```

The `entitlements` subcommands take the organization with `--parent`, while the other `skills` subcommands use `--group`. Omit `--parent` to pick the organization from an interactive list.

Next, accept the Skills Registry terms of service for your org:

```shell
chainctl skills accept-terms --group your-organization
```

This opens an interactive prompt:

```output
   Chainguard Legal Agreements
   To continue, please review and accept the following:
   ▶ [ ] I agree to the Agent Skills Terms of Service
         https://www.chainguard.dev/legal/agent-skills

     [ ] I agree to the Data Privacy Agreement
         https://www.chainguard.dev/legal/supplemental-dpa

   ↑/↓ navigate  •  space toggle  •  enter confirm  •  q cancel
```

Press <kbd>SPACE</kbd> to check each agreement, using the arrow keys to move between them, then press <kbd>ENTER</kbd> to confirm. The prompt doesn't continue until you accept both.

In CI, where no interactive terminal is available, pass `--yes` instead. By using `--yes`, you confirm that you have read and agreed to the [Agent Skills Terms of Service](https://www.chainguard.dev/legal/agent-skills) and the [Data Privacy Agreement](https://www.chainguard.dev/legal/supplemental-dpa).

## Creating an example skill

A skill is a directory containing a `SKILL.md` file. The `SKILL.md` frontmatter declares the skill's `name` and a `description` that tells an agent when to use it. The rest of the file contains the instructions the agent follows.

The next section has a few examples that refer to a skill named `hello-world`. You can create a sample `hello-world` skill with the following command:

```shell
mkdir hello-world
cat > hello-world/SKILL.md << 'EOF'
---
name: hello-world
description: A simple hello world skill. Use this to verify your skills registry setup is working end to end.
---

When this skill is invoked, greet the user with:

"Hello from Chainguard Agent Skills! Your skill installed and loaded successfully."

If the user provides their name, greet them by name instead:

"Hello, <name>! Welcome to Chainguard Agent Skills."
EOF
```

After running this command, your directory has the following structure:

```
hello-world/
└── SKILL.md
```

The directory name (`hello-world/`) must match the `name` field in the frontmatter (`name: hello-world`). If they don't match, both `validate` and `push` fail.

## Manage skills with `chainctl`

This section outlines some of the `chainctl` commands you can use to manage skills in your organization's private Skills Registry. The following commands use the `hello-world` skill as an example, but you can use any other skills you've created in its place.

Refer to the [`chainctl skills` reference documentation](/platform/chainctl/chainctl-docs/chainctl_skills/) for more information.

### Validate the skill

Before you publish, check that the skill directory meets the spec with the `validate` subcommand. It runs locally and makes no network calls:

```shell
chainctl skills validate hello-world
```

```output
✓  SKILL.md found
✓  Frontmatter valid
✓  name: "hello-world" (matches directory basename)
✓  description: 96 chars
✓  Total size: 387 B / 10 MB
✓  1 file(s) will be published:
     SKILL.md

Validation passed.
This checks format only, not authenticity. To check that Chainguard signed a published skill, run `chainctl skills verify <ref>`.
```

`validate` confirms that the directory contains a `SKILL.md`, that its frontmatter is valid, that the `name` field matches the directory name, and that the skill is within the size limit. It also lists the files that `push` publishes. `validate` checks format only, not who published a skill. To check that, verify the hardened skill's signature, as described in [Verify the skill](#verify-the-skill).

To also flag optional fields that Chainguard recommends, add the `--strict` flag:

```shell
chainctl skills validate hello-world --strict
```

```output
✓  SKILL.md found
✓  Frontmatter valid
✓  name: "hello-world" (matches directory basename)
✓  description: 96 chars
✓  Total size: 387 B / 10 MB
✓  1 file(s) will be published:
     SKILL.md
⚠  license field is recommended

Validation passed.
This checks format only, not authenticity. To check that Chainguard signed a published skill, run `chainctl skills verify <ref>`.
```

Here, `--strict` warns that the skill omits the recommended `license` field. Warnings don't cause validation to fail, but addressing them produces a more complete skill.

### Push the skill to your organization's uploads registry

From the parent directory of `hello-world/`, push the skill to your organization's uploads registry with a version tag:

```shell
chainctl skills push hello-world --group your-organization --tag v1.0.0
```

```output
                    REFERENCE                   |     DIGEST
------------------------------------------------|----------------
 uploads.cgr.dev/example.dev/hello-world:v1.0.0 | sha256:3196...
```

You can repeat `--tag` to publish one artifact under several tags, such as `--tag v1.0.0 --tag latest`. If you omit `--tag`, `chainctl` publishes the skill as `latest` and warns that you didn't pin a version. To build and validate the artifact without publishing it, add `--dry-run`.

Keep the versioned reference for the hardening submission below.

### List your uploads

Confirm the upload with the `list` subcommand and `--source uploads`:

```shell
chainctl skills list --group your-organization --source uploads
```

```output
     SOURCE      | TYPE  |    NAME     |  TAGS  | UPDATED
-----------------|-------|-------------|--------|----------
 uploads.cgr.dev | skill | hello-world | v1.0.0 | just now
```

Without `--source uploads`, `list` shows the hardened registry. A successful push does not mean a hardened result is available there. Submit the upload for hardening in the next step.

The `TAGS` column shows all tags for each skill. A `latest` tag is not required. If your output has a `LATEST TAG` column or omits the upload, see [Find a skill that is missing from the listing](/chainguard/agent-skills/skill-hardening/#find-a-skill-that-is-missing-from-the-listing).

### Harden the skill

Submit the uploaded artifact and wait for the result:

```shell
chainctl skills harden uploads.cgr.dev/your-organization/hello-world:v1.0.0 \
  --group your-organization --wait --timeout 30m
```

The command prints a job ID, waits for hardening, and downloads the result to `./hardened/hello-world/`. Review the instructions and `HARDENING.md` report, including any findings that remain open.

Save the exact hardened reference returned by the command. It includes a user namespace and digest, in the form `skills.cgr.dev/<org-uidp>/users/<user-namespace>/hello-world@sha256:<digest>`:

```shell
export HARDENED_REF='<full-hardened-reference-returned-by-the-command>'
chainctl skills describe "$HARDENED_REF"
```

For submissions directly from a local directory, checking a job later, and resuming after a timeout, see [Getting started with skill hardening](/chainguard/agent-skills/skill-hardening/).

### List hardened skills

Hardened results are nested under `users/<user-namespace>/`. Add `--recursive` to browse skills inside those folders:

```shell
chainctl skills list --group your-organization --source skills --recursive
```

Without `--recursive`, the organization-level listing may show only a `users` row with `TYPE` set to `folder`. Expand the folder with `--recursive`, or browse it with `chainctl skills list --group your-organization/users`. See [Browse results in user folders](/chainguard/agent-skills/skill-hardening/#browse-results-in-user-folders) for the folder layout and how to show uploads alongside hardened results.

The listing includes skills with generated version tags and skills without tags. Use the exact `$HARDENED_REF` returned by the job to inspect and install the result you reviewed.

### Verify the skill

Chainguard signs every hardened skill it publishes to your organization's registry. Check that signature with the `verify` subcommand:

```shell
chainctl skills verify "$HARDENED_REF"
```

A `Status` of `verified` confirms that Chainguard signed the skill for your organization and that it hasn't changed since. Verifying a skill in your organization requires the `groups.list` capability on the organization, such as with the built-in `owner`, `editor`, `viewer`, `limited_owner`, or `console_viewer` role. For what `verify` checks, its other results, and how to verify with Cosign, refer to [Verifying Chainguard Agent Skills signatures](/chainguard/agent-skills/verifying-skills/).

### Install the skill

Download and install the skill to make it available to agents on your machine:

```shell
chainctl skills install "$HARDENED_REF"
```

This command automatically detects agents on your machine and reports where it placed the skill. The install name includes the registry namespace to distinguish skills with the same name. Copy the **Install Name** from `chainctl skills describe "$HARDENED_REF"` for use in the following steps:

```shell
export INSTALLED_SKILL='<install-name-from-describe>'
```

By default, `install` writes one shared copy to `.agents/skills/` and symlinks each agent's skills directory to it, so every agent reads the same files. Add `--copy` to give each agent its own copy, `--global` to install under your home directory instead of the current project, or `--agent` to target specific agents instead of every detected one.

To use the skill in [Chainguard Workspaces](/chainguard/workspaces/overview/) sessions, run `install` from your repository's top-level directory and commit what it writes: the `.agents/skills/` and `.claude/skills/` entries and the `skills-lock.json` file. Refer to [Configure Claude Code in a session](/chainguard/workspaces/coding-agents/#configure-claude-code-in-a-session).

To check the signature as part of the install, add `--verify`. `install` then verifies the exact digest it fetches and installs nothing unless the skill is `verified`:

```shell
chainctl skills install --verify "$HARDENED_REF"
```

### Run the skill from an agent

Load the skill from the location reported by `install`. In Claude Code, invoke it with `/<installed-skill-name>`, replacing `<installed-skill-name>` with the value you saved in `$INSTALLED_SKILL`. Ask the agent to greet you, and check that its response follows the instructions you reviewed in the hardened `SKILL.md`.

### Uninstall the skill

To remove a skill from your machine, pass its install name to the `uninstall` subcommand:

```shell
chainctl skills uninstall "$INSTALLED_SKILL"
```

The command prompts for confirmation before removing any files.

By default, `uninstall` removes the project-local copy from every agent directory where it's installed. If a global copy also exists, `uninstall` leaves it in place and prints a warning. Re-run the command with `--global` to remove that copy. Use the `--agent` flag to remove the skill from specific agents only, and the `-y` flag to skip the confirmation prompt.

`uninstall` operates only on the local files on your machine. It doesn't modify your organization's registry. To remove a published skill from the registry, use [`chainctl skills delete`](/platform/chainctl/chainctl-docs/chainctl_skills_delete/) instead.

### Delete a skill from the registry

To remove a published version of a skill from your organization's hardened registry, first list its tags. Use the repository portion of the hardened reference, preserving its user namespace:

```shell
HARDENED_REPO="${HARDENED_REF%@*}"
chainctl skills versions "$HARDENED_REPO"
```

Select a tag from that output and pass the full tagged reference to `delete`. The upload's `v1.0.0` tag is not a substitute for a tag from the hardened repository. Digest references are not accepted by `delete`:

```shell
export HARDENED_TAG='<tag-from-the-versions-output>'
chainctl skills delete "$HARDENED_REPO:$HARDENED_TAG"
```

The command prompts for confirmation before removing the version. Press <kbd>y</kbd> and <kbd>ENTER</kbd> to confirm. Add the `-y` flag to skip the prompt and delete the version non-interactively.

The command requires a tag so you don't delete the `latest` tag by accident. Deleting `latest` is still possible, but it prompts for an additional confirmation.

When you delete a skill's last remaining version, `chainctl` also removes the empty skill entry, so it doesn't linger in `list` output with nothing to pull. `delete` accepts a reference without a tag, such as `"$HARDENED_REPO"`, only for a skill with no versions left. A skill that still has versions requires an explicit tag.

Unlike `uninstall`, `delete` removes the skill from the registry for your whole organization. It doesn't remove copies already installed on anyone's machine.

## Command reference

| Action | Command |
| ----- | ----- |
| Enable the entitlement | `chainctl skills entitlements create --parent your-organization` |
| Accept the registry terms | `chainctl skills accept-terms --group your-organization` |
| Validate a skill | `chainctl skills validate <name>` |
| Upload a skill | `chainctl skills push <name> --group your-organization --tag <version>` |
| List uploads | `chainctl skills list --group your-organization --source uploads` |
| Harden a local skill | `chainctl skills harden ./<name> --group your-organization --wait` |
| Check a hardening job | `chainctl skills status --group your-organization --id "$JOB_ID"` |
| List hardened skills in all folders | `chainctl skills list --group your-organization --recursive` |
| Describe a hardened skill | `chainctl skills describe "$HARDENED_REF"` |
| Verify a hardened skill's signature | `chainctl skills verify "$HARDENED_REF"` |
| Install a hardened skill | `chainctl skills install "$HARDENED_REF"` |
| Install only if the signature verifies | `chainctl skills install --verify "$HARDENED_REF"` |
| Uninstall a skill | `chainctl skills uninstall "$INSTALLED_SKILL"` |
| Delete a published version | `chainctl skills delete "$HARDENED_REPO:$HARDENED_TAG"` |