Get started

One manifest. Every agent.

This page explains how skm installs the agent skills you declare in one file into every agent your project uses.

You declare the skills your project needs in skills.yaml and commit it. skm resolves them from a registry and links them into Claude, Codex, Cursor, Copilot, Grok and Hermes, so every agent working in the repo reads the same instructions.

Skills are versioned folders in Git. You can pin one, follow latest, or track the maintainer's default. See also: skm (GitHub).

Install skm

One command on macOS or Linux.

Browse the catalog

Every published skill and metapackage.

Write a skill

Publish a package that works in every agent.

Install skm

On macOS or Linux, run the install script:

Terminal
curl -fsSL https://raw.githubusercontent.com/skills-yaml/skm/main/scripts/install.sh | sh

Windows PowerShell, Cargo and the development channel are covered in the install guide.

How it works

Each agent reads skills from its own folder. skm keeps one copy of each skill and links it into the skill folder of every agent declared in skills.yaml, so all agents in the repository run the same version of the same instructions.

To set up a project:

  1. Declare the skills

    Create skills.yaml at the root of the project. List the registries to fetch from, the agents to link into, and the skills you want:

    skills.yaml
    name: my-project
registries:
  default: [email protected]:skills-yaml/registry.git
agents: [claude, codex, cursor, copilot, grok, hermes]
skills:
  - name: software-development/spec
    version: 1.0.0
    source: default

    skm init can write this file for you through a series of prompts, and lets you search your registries for skills along the way.

  2. Install them

    Run the install command in the project:

    Terminal
    skm install

    skm resolves every skill, checks each target before writing, links them, and then writes skills.lock.yaml.

  3. Commit the manifest and the lockfile

    Commit skills.yaml and skills.lock.yaml. The lockfile records the resolved versions, integrity hashes and every path skm manages, so a second install on another machine is byte-for-byte identical.

The resulting links look like this:

my-project/
├── skills.yaml
├── skills.lock.yaml
├── .claude/skills/spec  -> registry/software-development/spec/v1.0.0
├── .codex/skills/spec   -> registry/software-development/spec/v1.0.0
├── .cursor/skills/spec  -> registry/software-development/spec/v1.0.0
├── .github/skills/spec  -> registry/software-development/spec/v1.0.0
├── .grok/skills/spec    -> registry/software-development/spec/v1.0.0
└── .hermes/skills/spec  -> registry/software-development/spec/v1.0.0

Nothing is copied into your tree. skm creates symlinks, so a skill update is a re-link, and reviewers see one manifest change instead of hundreds of vendored files.

Install for your user account

Add --global to install, list or check to work on the agent folders in your home directory instead of the project:

~/
├── .claude/skills/
├── .codex/skills/
├── .cursor/skills/
├── .copilot/skills/
├── .grok/skills/
└── .hermes/skills/

The manifest

skills.yaml declares the registries, agents and skills of a project. Everything skm does starts from this file. Fields you leave out keep working defaults:

skills.yaml
name: my-project
version: 0.1.0

registries:
  default: [email protected]:skills-yaml/registry.git

agents:
  - claude
  - codex
  - cursor
  - copilot

skills:
  - name: software-development/spec
    version: 1.0.0        # pinned
    source: default

  - name: system/gcp-debug
    version: latest       # follows the newest release
    source: default

  - name: local/my-skill  # no registry needed
    version: latest
    path: ./skills/local/my-skill
registries
Git remotes or local paths to fetch skills from. Name them, then refer to a name in source. A project inherits your global registries too.
agents
Which agents get links. Add one later and re-run skm install to fill its folder.
version
A pinned release such as 1.0.0, or the latest and default aliases the skill's maintainer moves. Leave it out and you get latest.
path
Points at a folder in the repo instead of a registry. Useful for a skill that is not ready to publish.
skills.lock.yaml
Written by skm install, committed by you. It records the resolved versions, integrity hashes and every path skm manages.

Make sure every source contains a SKILL.md file, whether it comes from a registry or a local path.

Commands

One binary, no daemon, and no project scaffolding beyond the manifest. These are the commands in skm 0.7.0.

Add --global to install, list or check to work in your home directory instead of the project. Add --json to install, search, versions or a bundle add when a script needs to read the result.

Set up

CommandWhat it does
skm initCreates or edits skills.yaml through a series of prompts, lets you search your registries for skills, and shows the finished file before saving it. --non-interactive writes a default manifest for scripts.
skm search <query>Searches your registries for skills and bundles in one list. Each result shows its version, description and registry, and the skm add command for it. Search never changes your project. --registry searches a single registry, and --limit caps the number of results.
skm add <skill>Adds one skill to the manifest and links it. --path adds a skill from a local folder.
skm add <bundle>Adds every skill in a published bundle, each pinned to an exact version, as one change that is rolled back if any part fails. --dry-run shows what would change, and --yes applies it. Add --kind bundle when a skill has the same name.
skm remove <skill>Removes a skill from the manifest and unlinks it. --dry-run shows what would be removed.

Keep it correct

CommandWhat it does
skm installResolves every skill, checks each target before writing, links them, then writes the lockfile. --dry-run shows every write first, and --yes applies without asking.
skm listReports link status, including sources that went missing and links that point somewhere wrong.
skm checkVerifies sources, SKILL.md files and symlink targets. Run it in CI.
skm updateUpdates the skm binary itself. --check only reports whether a new release is available, and --channel prod|development switches release channel.

Move between versions

CommandWhat it does
skm versions <skill>Lists the releases a registry offers for one skill. --pre includes prereleases.
skm use <skill>@<version>Switches a skill to a specific version and re-links it. --dry-run shows the change first.
skm update-skill <skill>Moves a skill to its newest release and re-links it.

Write a skill

CommandWhat it does
skm dev link <path>Links a skill you are editing straight from disk, so you can try it in your agents before publishing.
skm dev list, show, modeShows what is linked in development, and turns development mode on or off.
skm dev unlink <skill>Removes a development link.

The registry

These skills are in the default registry, and the list is generated from the repository itself. Each one is a versioned folder holding a SKILL.md and whatever references, templates or scripts it needs.

Browse the full catalog, or read the authoring guide to publish a skill of your own.

Guardrails

Agent skills end up as instructions your team executes, so skm treats writing them to disk as a transaction:

It refuses collisions

Before writing anything, skm checks every target. A file it does not already manage stops the install instead of being overwritten.

It rolls back

A local journal backs up managed paths during apply. A failure part-way through restores what was there, and the lockfile is written last.

It verifies sources

Git sources need a full commit revision and an expected SHA-256. Names are validated before any filesystem call: no absolute paths, no .., no unsupported agents.

skm and the registry are open source and MIT licensed.