Skip to main content
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.

​
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:
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.
The binary is registry.

​
Get started

Initialize a manifest for the project:
That writes registry.yml. Then add a source:
Sources may be owner/repo, an HTTPS or SSH URL, file://, or a local directory — each optionally suffixed with @tag, @branch, or @sha:
Preview any run before it touches the filesystem:
--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

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: 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

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

Content is cloned once into ~/.registry/store/git/<host>/<owner>/<repo>/<commit>, copied into .registry/artifacts/<name> — 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

In CI, add --frozen so a run fails rather than silently rewriting the lock:
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

Command reference

Every command, flag, and exit code.

Discover and use skills

Finding skills in Agent Registry.