# Chops — the open agent skills registry

> Chops indexes public Agent Skills (SKILL.md folders) and installs them source-pinned and
> digest-verified into one shared local store, linked into Claude Code, Codex, Cursor, and
> other coding agents. No account is required for public skills.

Website: https://chops.sh · Library: https://chops.sh/skills · Registry API: https://api.chops.sh · npm: chops-sh

## Quickstart

```sh
# 1. Install the CLI (npm package chops-sh, command chops)
npm install -g chops-sh

# 2. Search by outcome — semantic + keyword relevance
chops find "optimize postgres queries"

# 3. Install a result (slug format: owner/repo@skill)
chops add anthropics/skills@algorithmic-art --yes
```

Zero-install alternative: every command also works as `npx chops-sh <command>` — the right
form for agents and CI. `add` verifies the package digest before anything is linked into an
agent directory.

## Commands

| Command | What it does |
| --- | --- |
| `find "<query>"` | Search the index. Returns the top 10 skills ranked by hybrid semantic + keyword relevance. |
| `add <owner/repo@skill>` | Download the pinned package, verify its sha256 against the manifest, unpack it into the shared store, and link it into detected agents. Asks for confirmation unless `--yes`. |
| `list` | Show installed skills from the lockfile. |
| `remove <owner/repo@skill>` | Remove the store entry and its agent links. |
| `help`, `--version` | Usage and CLI version. |

## Flags

| Flag | Meaning |
| --- | --- |
| `--json` | Machine-readable output on stdout (one JSON document). Recommended for agents. |
| `--yes`, `-y` | Skip the install confirmation. Required when running without a TTY. |
| `--agent <names>` | Comma-separated link targets: `claude-code`, `cursor`, `codex` (alias `agents`, the vendor-neutral `~/.agents/skills` directory). Default: `~/.agents/skills` always, plus `~/.claude/skills` when `~/.claude` exists. |
| `--api-url <url>` | Registry override (default https://api.chops.sh; env `CHOPS_API_URL`). |

## How an install works

1. The registry returns a manifest: skill slug → pinned content SHA, tarball URL, tarball sha256.
2. The tarball is downloaded and rejected unless its sha256 matches the manifest.
3. Contents unpack once into `~/.chops/store/<owner>/<repo>/<skill>@<sha>/`.
4. The store path is symlinked (junction on Windows) into each selected agent directory.
5. The install is recorded in `~/.chops/chops.lock`.

Published versions are immutable: tarballs are content-addressed by sha256 and the registry
mirrors them, so a force-pushed source repo cannot change what you installed.

## For coding agents

- Always pass `--json` and `--yes` for non-interactive use.
- `find --json` returns `{ query, results: [{ slug, description, publisher: { owner, repo }, agents, stars, installs, last_published_at, pinned_sha, install_cmd, score }] }`.
- `add --json` returns `{ ok, slug, sha, store, links }`.
- Failures print `{"error":{"code":"failed","message":"..."}}` and exit non-zero.
- Example agent instruction: "To find a skill, run `npx chops-sh find \"<task>\" --json`. To install one, run `npx chops-sh add <slug> --yes --json`."

## Public registry API (https://api.chops.sh)

No authentication required.

| Endpoint | Description |
| --- | --- |
| `GET /skills/search?q=<query>&limit=<1-50>` | Hybrid semantic + keyword search. Optional `owner` and `agent` filters. |
| `GET /skills?sort=popular\|recent&limit=<1-50>&offset=<0-10000>` | Browse the full index; returns `total` plus a results page. |
| `GET /manifest?slug=<owner/repo@skill>` | Pinned version, tarball URL, sha256, size. |
| `GET /tarballs/<sha256>` | Immutable content-addressed package download. |
| `GET /health`, `GET /version` | Service status and deployed version. |

## Web pages

- https://chops.sh — search by outcome
- https://chops.sh/skills — the full library (sort by most installed or recently published)
- https://chops.sh/skills/<owner>/<repo>/<name> — skill detail with source repo, content SHA, and package digest
- https://chops.sh/docs — human-readable version of this document