AgentCaps Registry

Enterprise-grade ARD registry for approved agent capabilities.

AgentCaps Registry turns scattered capability sources, starting with SKILL.md, into a governed ARD / AI Catalog that agents can discover, search, and consume. It is designed for teams that want agents to use approved, pinned, reviewable capabilities instead of importing arbitrary skills directly from the internet.

SKILL.md-compatible source
-> reviewed CatalogEntry draft
-> published pinned snapshot
-> ai-catalog.json + search index
-> private or public agent capability registry

Positioning

AgentCaps Registry is a registry engine, not another skill marketplace.

It provides the control object between capability producers and capability consumers:

producers keep capability content in their own repositories or URLs;
registry maintainers import and review those sources;
only published entries are exported to the agent-facing catalog;
consumers point agents at the registry output instead of raw upstream projects.

This makes agent capability discovery reproducible, auditable, and enterprise-friendly.

What It Does

V0 focuses on a narrow, useful workflow:

Import capability sources from public git repositories or direct SKILL.md URLs.
Generate standard ARD CatalogEntries from SKILL.md content.
Add reviewed ARD fields such as tags, capabilities, and representativeQueries when the source document is incomplete.
Validate metadata quality with findings and a completeness score.
Publish approved entries through an explicit publication gate.
Pin snapshots by commit URL and content digest so the exported catalog is reproducible.
Detect source drift when an upstream git ref changes after publication.
Build static registry artifacts: ai-catalog.json, search-index.json, and per-entry listings.
Search locally against the generated static BM25 index.

What It Is Not

AgentCaps Registry intentionally does not try to do everything in V0:

not a runtime sandbox or permission enforcement layer;
not a safety, trust, or publisher-verification score;
not an automatic installer for skills;
not a hosted marketplace by default;
not a mirror that stores every producer artifact;
not an MCP / A2A / OpenAPI registry yet;
not a replacement for enterprise approval systems.

The registry decides what agents can discover. Runtime enforcement, execution receipts, and policy checks should be handled by adjacent systems.

Core Concepts

Source

A source is where the original capability document lives.

V0 supports:

git_repository             public git repository containing one SKILL.md
git_repository_collection  public git repository containing multiple SKILL.md files
direct_url                 direct URL or local path to a SKILL.md-compatible document

CatalogEntry

The agent-facing output is a standard ARD / AI Catalog CatalogEntry.

AgentCaps product state, such as publication status, validation report, source commit, and drift status, is kept outside the CatalogEntry.

Curation

Many real-world SKILL.md files describe the skill well but do not include ARD search fields. Registry maintainers can add reviewed standard fields in sources.yaml:

sources:
  - slug: frontend-slides
    type: git_repository
    url: https://github.com/zarazhangrui/frontend-slides
    path: SKILL.md
    trackingRef: main
    curation:
      reason: reviewed public SKILL.md for presentation generation use cases
      catalogEntry:
        tags:
          - slides
          - presentation
          - html
          - frontend
          - design
          - pptx
        capabilities:
          - slides.create
          - slides.convert
          - presentation.design
          - html.generate
          - pptx.convert
        representativeQueries:
          - create an animated HTML presentation for a product pitch
          - convert a PowerPoint deck into a web-based slide deck
          - make visually polished frontend slides from a topic

For repository collections, use include to expand one source repo into multiple entries:

sources:
  - slug: anthropics-skills
    type: git_repository_collection
    url: https://github.com/anthropics/skills
    include:
      - "**/SKILL.{md,markdown}"
    exclude:
      - "**/templates/**"

Globs support * (one path segment), ** / **/ (zero or more segments), ?, and brace alternation like {md,markdown}. Optional exclude globs filter out matches, and node_modules, .git, .hg, .svn, and .cache directories are ignored automatically.

Each matched SKILL.md becomes its own entry. For example, skills/pdf/SKILL.md becomes a separate CatalogEntry from skills/docx/SKILL.md.

curation.catalogEntry only fills standard CatalogEntry fields. It is not emitted as AgentCaps-specific metadata.

Publication Gate

Importing a source does not publish it.

import    creates or updates an entry draft
validate  checks ARD metadata quality
publish   marks an entry as approved for export
build     exports only published entries
revoke    removes an entry from future exports

This keeps the registry compatible with Git PR review, existing approval systems, or lightweight maintainer review.

Drift

Published entries are pinned. If the upstream source changes, the registry reports drift but does not silently replace the published snapshot.

git source:        published commit != latest tracked ref      -> drifted
direct_url source: published content digest != latest content  -> drifted
                   (HTTP sources use a conditional GET via ETag / Last-Modified
                    and report `clean` on a 304 Not Modified)
unreachable source: drift cannot be determined                 -> unknown
-> maintainer decides whether to re-import and publish again

drift --ci exits non-zero when anything is drifted; build --exclude-drifted (or excludeDriftedFromCatalog: true in registry.yaml) keeps drifted entries out of the exported catalog.

Quick Start

Requirements:

Node.js >=22
npm
git

Install the CLI from npm:

npm install -g @agentcaps/registry

Or run it without a global install:

npx -y @agentcaps/registry@latest --help

Create a registry workspace:

mkdir my-agentcaps-registry
cd my-agentcaps-registry
agentcaps-registry --root .agentcaps init

If you prefer npx, replace agentcaps-registry with npx -y @agentcaps/registry@latest in the commands below.

Edit .agentcaps/sources.yaml:

sources:
  - slug: frontend-slides
    type: git_repository
    url: https://github.com/zarazhangrui/frontend-slides
    path: SKILL.md
    trackingRef: main
    curation:
      catalogEntry:
        tags: [slides, presentation, html, frontend, design, pptx]
        capabilities:
          - slides.create
          - slides.convert
          - presentation.design
          - html.generate
          - pptx.convert
        representativeQueries:
          - create an animated HTML presentation for a product pitch
          - convert a PowerPoint deck into a web-based slide deck
          - turn markdown or notes into a polished slide deck

Run the workflow:

agentcaps-registry --root .agentcaps import frontend-slides
agentcaps-registry --root .agentcaps validate frontend-slides
agentcaps-registry --root .agentcaps publish frontend-slides --by alice@example.com
agentcaps-registry --root .agentcaps build

Search the built index:

agentcaps-registry --root .agentcaps search "convert pptx to web slides"

See a checked-in real example at examples/frontend-slides. It includes sources.yaml, the generated CatalogEntry, validation report, and ai-catalog.json.

Generated output:

.agentcaps/
  registry.yaml
  sources.yaml
  entries/
    frontend-slides/
      entry.yaml
      catalog-entry.json
      validation.json
      drift.json
  dist/
    ai-catalog.json
    search-index.json
    listings/
      frontend-slides.json

CLI

agentcaps-registry init
agentcaps-registry import [slug|--all]
agentcaps-registry validate [slug|--all] [--check-urls] [--timeout <ms>] [--json] [--min-score <n>]
agentcaps-registry publish [slug|--all]
agentcaps-registry revoke <slug>
agentcaps-registry drift [slug|--all] [--json] [--ci]
agentcaps-registry build [--exclude-drifted] [--json]
agentcaps-registry search "<query>"
agentcaps-registry serve [dir] [--port <n>] [--host <host>]

CI-friendly output

Most commands take --json for machine-readable output. validate exits with a non-zero code when any entry has an error-level finding, or — with --min-score <n> — when any entry scores below the threshold, so it can gate a pipeline:

agentcaps-registry validate --all --json --min-score 70
agentcaps-registry drift --all --ci   # non-zero exit if anything drifted
agentcaps-registry build --exclude-drifted --json

validate --check-urls adds an optional network reachability check for each CatalogEntry.url. The result is recorded as an url-reachability finding and does not change the deterministic completeness score, so offline and CI runs stay stable by default.

The CLI is published as the agentcaps-registry binary by the @agentcaps/registry npm package.

HTTP Endpoint

serve exposes the built static artifacts over a minimal ARD-compatible HTTP surface. It reads dist/ai-catalog.json and dist/search-index.json once at startup, so run build first and restart to pick up changes.

agentcaps-registry --root .agentcaps serve
# or point directly at a dist directory
agentcaps-registry serve .agentcaps/dist --port 8787

Routes:

GET  /.well-known/ai-catalog.json   the AICatalog manifest
POST /search                        body: {"query": "...", "limit": 10}
GET  /health                        liveness and published entry count

All responses include permissive CORS headers for public read-only use. This is a lightweight adapter over static artifacts, not a long-running registry server.

curl http://127.0.0.1:8787/.well-known/ai-catalog.json
curl -X POST http://127.0.0.1:8787/search \
  -H 'content-type: application/json' \
  -d '{"query": "convert pptx to web slides", "limit": 5}'

Generated `ai-catalog.json`

Example output:

{
  "specVersion": "1.0",
  "host": {
    "displayName": "AgentCaps Registry",
    "identifier": "urn:air:agentcaps.local:registry:default"
  },
  "entries": [
    {
      "identifier": "urn:air:github.com:zarazhangrui:frontend-slides:skill:frontend-slides",
      "displayName": "frontend-slides",
      "type": "application/ai-skill",
      "url": "https://raw.githubusercontent.com/zarazhangrui/frontend-slides/<commit>/SKILL.md",
      "description": "Create stunning, animation-rich HTML presentations from scratch or by converting PowerPoint files.",
      "tags": ["slides", "presentation", "html", "frontend", "design", "pptx"],
      "capabilities": ["slides.create", "slides.convert", "presentation.design", "html.generate", "pptx.convert"],
      "representativeQueries": [
        "create an animated HTML presentation for a product pitch",
        "convert a PowerPoint deck into a web-based slide deck",
        "turn markdown or notes into a polished slide deck"
      ]
    }
  ]
}

Validation Score

The validation score measures ARD metadata completeness and search readiness.

It is not:

a safety score;
a trust score;
a publisher verification score;
a runtime permission score;
an enterprise compliance score.

Use validation to improve catalog quality, not to certify execution safety.

Deployment Model

V0 is file-first and static-export first.

You can commit the registry workspace to Git, review changes through pull requests, and host dist/ on any static or internal HTTP service.

Typical private deployment:

company registry repo
-> PR adds or updates sources.yaml / entries
-> CI runs import, validate, drift, build
-> approved dist/ai-catalog.json is deployed internally
-> agents consume the internal catalog

A future server can expose ARD-compatible endpoints such as /.well-known/ai-catalog.json and POST /search using the generated static artifacts.

Repository Boundary

This project is the reusable registry engine.

A public website such as agentcaps.dev can be built on top of it by maintaining a curated sources.yaml, running the registry pipeline, and rendering the generated listings. The public site depends on this registry engine; this registry engine should not depend on the public site.

Roadmap

Done:

stronger CatalogEntry validation rules (capability label format, tag dedupe/normalization, representative-query quality, optional URL reachability);
ARD-compatible HTTP endpoint adapter (serve: /.well-known/ai-catalog.json and POST /search);
end-to-end CLI workflow smoke test in CI;
CI-friendly command output (--json, validate exit codes / --min-score, drift --ci, build --exclude-drifted);
richer source adapters (direct_url drift via content digest + ETag / Last-Modified; brace / **/ collection globs; exclude globs; default directory ignores).

Near-term:

static web deployment examples;
drift notifications and webhook integrations;
additional capability source types (MCP / A2A / OpenAPI).

Later:

private registry server mode;
enterprise auth and access-control integration;
MCP, A2A, and OpenAPI capability source types;
signed catalog artifacts and stronger provenance metadata.

Package

This package is published on npm as @agentcaps/registry.

npm install -g @agentcaps/registry
npx -y @agentcaps/registry@latest --help

The published package includes the compiled dist/ files, README.md, and LICENSE.

Development

Build from source only if you are contributing to the registry engine:

git clone https://github.com/agentcaps/registry.git
cd registry
pnpm install
pnpm build
pnpm test
pnpm pack --dry-run

Tests use local fixtures and local git repositories. They do not depend on live GitHub state.

License

Apache-2.0. See LICENSE.

Name		Name	Last commit message	Last commit date
Latest commit History 11 Commits
.github		.github
examples/frontend-slides		examples/frontend-slides
fixtures		fixtures
scripts		scripts
src		src
tests		tests
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
README.zh-CN.md		README.zh-CN.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

AgentCaps Registry

Positioning

What It Does

What It Is Not

Core Concepts

Source

CatalogEntry

Curation

Publication Gate

Drift

Quick Start

CLI

CI-friendly output

HTTP Endpoint

Generated `ai-catalog.json`

Validation Score

Deployment Model

Repository Boundary

Roadmap

Package

Development

License

About

Uh oh!

Releases 4

Packages

Uh oh!

Contributors

Uh oh!

Languages

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

AgentCaps Registry

Positioning

What It Does

What It Is Not

Core Concepts

Source

CatalogEntry

Curation

Publication Gate

Drift

Quick Start

CLI

CI-friendly output

HTTP Endpoint

Generated ai-catalog.json

Validation Score

Deployment Model

Repository Boundary

Roadmap

Package

Development

License

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 4

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Generated `ai-catalog.json`

Packages