> ## Documentation Index
> Fetch the complete documentation index at: https://platform.atlan.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Registry package manager
> Install skills, plugins, and other agent artifacts from a Git repository into the coding agents a project uses.
`registry` is a package manager for agent artifacts. Point it at a Git
repository and it installs that repository's skills, plugins, subagents,
commands, hooks, MCP servers, rules, and LSP servers into whichever coding
agents your project actually uses — then records exactly what it did, so the
next run can tell whether anything moved.
**Internal release.** `@atlanai/registry` is not published to public npm yet.
Confirm access with your Atlan contact before adopting it in a project other
people build.
This is a different tool from the `atlanai` CLI. `registry` pulls artifacts
**into** a project; `atlanai` publishes **to** Agent Registry and reads from
it. The `atlanai` CLI's own registry commands are documented separately in
[the CLI registry guide](/cli/registry).
## Why use it
Without it, adopting a set of skills means copying directories into
`.claude/skills`, then again into `.codex/skills`, then remembering which
version you copied and re-doing it by hand when upstream changes. `registry`
makes that one command, keeps the copies traceable to a commit, and tells you
when a local edit has diverged.
* **One source, many agents.** Install once; it projects into every detected
harness.
* **Pinned and reproducible.** A lockfile records the exact commit. `sync` is
offline when the lock pins the ref.
* **Honest about drift.** `status` compares what is installed against the lock;
`why` tells you where one artifact came from.
* **No migration needed.** Repositories written for `npx skills` or
`npx plugins` work unchanged — the same `marketplace.json`, `plugin.json`,
and `skills/*/SKILL.md` conventions are read, in that order.
## Requirements
* Node 22.20 or later, and `git` on `PATH`.
* `gh` is used when present, to reach private repositories.
## Install
During the internal release, point the `@atlanai` scope at GitHub Packages
once, in your `.npmrc`:
```ini theme={null}
@atlanai:registry=https://npm.pkg.github.com
```
Authenticate with a token that has `read:packages` — a personal access token
locally, or `NODE_AUTH_TOKEN` in CI. Keep the token out of a committed
`.npmrc`.
```bash theme={null}
npm install -g @atlanai/registry
```
The binary is `registry`.
## Get started
Initialize a manifest for the project:
```bash theme={null}
registry init
```
That writes `registry.yml`. Then add a source:
```bash theme={null}
registry add vercel-labs/agent-skills
```
Sources may be `owner/repo`, an HTTPS or SSH URL, `file://`, or a local
directory — each optionally suffixed with `@tag`, `@branch`, or `@sha`:
```bash theme={null}
registry add owner/repo@v2.1.0
registry add https://github.com/owner/repo@main
registry add ./local-skills
```
Preview any run before it touches the filesystem:
```bash theme={null}
registry add owner/repo --dry-run
```
`--dry-run` is the same code path as a real run, not a separate simulation, so
the plan it prints is what would happen.
## What it can install
| Kind | What it is |
| --------- | --------------------------------------------------------------------------------------------- |
| `plugin` | A directory the harness loads whole, keeping the hooks and MCP servers its manifest declares. |
| `skill` | A skill directory with a `SKILL.md`. |
| `agent` | A subagent definition. |
| `command` | A slash command. |
| `hook` | A hook configuration. |
| `mcp` | An MCP server definition. |
| `rule` | An editor rule file. |
| `lsp` | An LSP server definition. |
Not every harness supports every kind. `registry targets` shows which
harnesses were detected and what each accepts.
## Where things go
Four harnesses are built in:
| Harness | Project root | User root |
| ----------------------- | ------------ | ------------------------- |
| Claude Code | `.claude` | `~/.claude` |
| Codex | `.codex` | `~/.codex` |
| Cursor | `.cursor` | `~/.cursor` |
| `AGENTS.md` (universal) | `.agents` | `$XDG_CONFIG_HOME/agents` |
The vendor-neutral `AGENTS.md` layout is the fallback, so it is always a valid
target. You can define additional harnesses in a `harnesses:` block — the shape
is identical to the built-in definitions, so anything the built-ins express you
can express too.
## Scopes
| Scope | Flag | Manifest | Projects into |
| ------- | ----------------- | -------------------------- | --------------------------- |
| user | `-g`, `--global` | `~/.registry/registry.yml` | `~/.claude`, `~/.codex`, … |
| project | `-p`, `--project` | `./registry.yml` | `./.claude`, `./.cursor`, … |
| local | `--scope local` | `./registry.local.yml` | same as project, gitignored |
Inside a project the default is `project`; outside one, `user`. Use `local` for
artifacts you want on your machine without committing them for the team.
## How installs are stored
```text theme={null}
Request -> Resolution -> Catalog -> Selection -> Plan -> Projection -> Lock
```
Content is cloned once into
`~/.registry/store/git////`, copied into
`.registry/artifacts/` — the only writable copy — and linked from there
into each harness.
The lockfile is written **last**. An interrupted run therefore leaves the
previous state intact, plus a journal naming what to clean up. Use `--copy` to
place real copies instead of links when a harness or filesystem cannot follow
them.
## Keep a project in sync
```bash theme={null}
registry status # is what's installed still what the lock says?
registry sync # make this project match its manifest
registry update # re-resolve refs and restage only what moved
```
In CI, add `--frozen` so a run fails rather than silently rewriting the lock:
```bash theme={null}
registry sync --frozen
```
Exit code `3` means drift and `4` means authentication is required, so CI can
distinguish "someone edited an artifact by hand" from "the token expired".
## Next steps
Every command, flag, and exit code.
Finding skills in Agent Registry.