# Ard Registry Builder

> Build, validate, test, and update registries and catalogs that follow the Agentic Resource Discovery (ARD) specification. Use this whenever the user works with an ai-catalog.json, a capability manifest, an ARD/AIR catalog or Agent Registry, urn:air: identifiers, trustManifest/attestations, representativeQueries, or an Agent Finder / discovery service — including authoring a new manifest, scaffolding one, fixing schema or URN errors, running conformance/validation, probing a registry's /search, /explore, or /agents REST endpoints, reviewing trust and federation metadata, or preparing to publish at /.well-known/ai-catalog.json. Trigger it even when the user only says "ARD", "agentic resource discovery", "AI catalog manifest", "agent registry", or "make agents discoverable" without naming the file.

- Skill: `webmaxru/ard-registry-builder` (Agent Skill, multi-file: 15 files)
- Install (CLI): `npx skillmds add webmaxru/ard-registry-builder`
- Raw SKILL.md: https://api.skillmd.com/api/skills/webmaxru/ard-registry-builder/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- License: MIT
- Author: webmaxru (https://skillmd.com/u/webmaxru)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/webmaxru/ard-registry-builder

---


# ARD Registry Builder

Agentic Resource Discovery (ARD) lets AI clients **discover** agents, MCP servers, skills, and
APIs at runtime by search instead of hardcoding them. Publishers describe their resources in a
static `ai-catalog.json` **capability manifest**; dynamic **Agent Registries** index those
manifests and answer `POST /search`. This skill helps you engineer both — author, validate,
test, and maintain them so they actually pass conformance and get discovered.

Two artifacts, one mental model — **identity vs location**:
- The **manifest** (`ai-catalog.json`, static) lists entries. Each entry's `identifier` is a
  permanent `urn:air:` URN (identity); its `url`/`data` is the movable endpoint (location).
- The **registry** (REST API, dynamic) is a service that searches indexed entries.

Never bake a hostname into a URN; never treat a URL as an identity. Almost every ARD mistake
traces back to confusing these two.

## Bundled tools (use these — don't reinvent them)
All scripts are stdlib-only Python 3.8+; `validate_catalog.py` uses the `jsonschema` library
when present (recommended: `pip install jsonschema`) and falls back to a built-in checker.

| Tool | Purpose |
| :-- | :-- |
| `scripts/validate_catalog.py <path-or-url> [--json] [--strict]` | Validate a manifest: JSON Schema **plus** ARD semantic rules. Exit 1 on errors. |
| `scripts/test_registry.py <base-url> [--query T] [--json]` | Probe a live registry's `/search` (required), `/agents`, `/explore` for conformance. |
| `scripts/new_catalog.py --template minimal\|enterprise\|local-dev [--publisher D] [--host N] --out F` | Scaffold a starter manifest. |
| `assets/ai-catalog.schema.json` | JSON Schema for the `ai-catalog.json` manifest format (Draft 2020-12), bundled for offline validation. |
| `assets/ard-entry.schema.json` | JSON Schema for a standalone ARD entry and `ArdManifest` (the v0.91 `ard.json` format). Use this to validate entries individually or a bare-`entries` manifest. |
| `assets/templates/*.json` | Valid starting points: `minimal`, `enterprise` (trust + registry entry), `local-dev`. |

Always **validate after every edit**, and validate the **live URL** after publishing — not just
the local file.

## Decide what the user needs
- *"Create / scaffold / start a catalog"* → **Workflow 1**.
- *"Validate / check / is this valid / why won't it pass conformance / fix this manifest"* →
  **Workflow 2** (run `validate_catalog.py` first, before reading anything).
- *"Test / probe my registry / does my /search work / is my API ARD-compliant"* → **Workflow 3**.
- *"Add an agent / bump a version / change an endpoint / maintain"* → **Workflow 4**.
- *"How does X work" (data model, API, trust, publishing)* → read the matching reference below.

## Workflow 1 — Build a manifest
1. Pick the closest template and scaffold it:
   `python scripts/new_catalog.py --template enterprise --publisher mycorp.com --host "MyCorp AI" --out ./ard.json`.
   (Without scaffolding, copy a file from `assets/templates/`.)
2. For each resource, set `identifier` (`urn:air:<publisher>:<namespace?>:<name>`),
   `displayName`, `type` (the artifact's media type), and **exactly one** of `url` or `data`.
3. Add `description`, `tags`, `capabilities`, and especially `representativeQueries` (2–5
   natural-language queries) — the single biggest lever for being found by semantic search.
   Absence is a conformance warning in v0.91; presence is still strongly recommended.
4. Add `trustManifest` only when you have real identity/attestations; keep simple entries lean.
5. Choose the publisher domain to match the deployment context (enterprise FQDN, public
   namespace like `github.com:you`, or `agent.localhost`/`example.com` for local-only). See
   `references/data-model.md`.
6. Validate: `python scripts/validate_catalog.py ./ard.json`. Fix until it passes.

## Workflow 2 — Validate / debug a manifest
1. **Run the validator first**, before reading the file by hand — it pinpoints issues fast:
   `python scripts/validate_catalog.py <path-or-url>`.
2. Read findings by severity. **ERROR** must be fixed; **WARN** should be (use `--strict` in CI
   to enforce); **INFO** is advice. Every finding names a JSON path and a stable `code`.
3. Map the `code` to a fix using `references/validation-rules.md`. The high-frequency ones:
   - `urn-wrong-nid` → change `urn:ai:` to `urn:air:`.
   - `value-or-reference` → keep exactly one of `url` / `data`.
   - `schema` (oneOf/required/pattern/minItems) → fix the structure the message names.
   - `urn-localhost` / `urn-publisher-fqdn` → use a verifiable or reserved-placeholder domain.
   - `trust-domain-mismatch` → make the `trustManifest.identity` domain match the URN publisher.
4. Re-run until clean. For CI, use `--json` (machine output) and/or `--strict` (fail on warnings).

## Workflow 3 — Test a live registry API
1. Probe it: `python scripts/test_registry.py https://registry.example.com/api/v1`.
   The tester sends a real `POST /search`, validates the `results` envelope (each item is a
   catalog entry carrying a `score` 0–100 and a `source`), confirms a malformed request is
   rejected with `400 + errorCode + message`, and checks optional `/agents` and `/explore`
   (skipped, not failed, when a server returns `404`/`501`).
2. Required checks failing → the server is not ARD-conformant on the mandated floor (`/search`).
   Fix the envelope/status against `references/registry-api.md`.
3. For exploratory calls, hit endpoints directly with `curl` (see `references/registry-api.md`).

## Workflow 4 — Update / maintain
1. Edit the entry. **Keep the `identifier` URN stable** — it is a permanent contract. To move an
   endpoint, change `url` (or `data`), never the URN.
2. Bump the entry's `version` and refresh `updatedAt` (ISO 8601) when the artifact changes.
3. Adding a resource → append an entry; ensure its `identifier` is unique (the validator flags
   duplicates).
4. Re-validate the file; if it is already published, also validate the live URL and re-probe any
   registry. Treat "passes validation" as the definition of done.

## Golden rules (the why behind the checks)
- **URN = identity, url/data = location.** Stable URNs keep search indexes, client references,
  and orchestration working while infrastructure moves underneath them.
- **The publisher segment must be a verifiable FQDN.** Registries extract it and bind it to
  `trustManifest.identity` to stop namespace squatting. `localhost` and bare words break this.
- **Exactly one of `url` or `data`.** Predictable parsing in enterprise pipelines depends on it.
- **`score` is relevance, not trust.** Never gate safety on a search score; verify
  `trustManifest` independently.
- **Validate early, validate often, validate the live URL.** Most "it won't index" problems are
  schema or hosting issues a 1-second validator run would have caught.

## Reference files
Read the one matching the task; each has a table of contents.
- `references/data-model.md` — manifest/entry fields, URN format, media types, value-or-reference,
  trust manifest, JSON-LD context extension, and the known `urn:air:` vs `urn:ai:` doc inconsistencies.
- `references/registry-api.md` — `/search`, `/explore`, `/agents`, the query/filter model,
  federation modes, and error codes.
- `references/validation-rules.md` — every check the validator runs, with its `code` and severity.
- `references/publishing.md` — well-known URI (`ard.json`), CORS, DNS discovery, and public reference
  registries to test against.

## Evals
`evals/evals.json` holds realistic task prompts for the skill-creator evaluation loop. Use it to
benchmark or regression-test changes to this skill.