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
- 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/.)
- For each resource, set
identifier (urn:air:<publisher>:<namespace?>:<name>),
displayName, type (the artifact's media type), and exactly one of url or data.
- 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.
- Add
trustManifest only when you have real identity/attestations; keep simple entries lean.
- 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.
- Validate:
python scripts/validate_catalog.py ./ard.json. Fix until it passes.
Workflow 2 — Validate / debug a manifest
- Run the validator first, before reading the file by hand — it pinpoints issues fast:
python scripts/validate_catalog.py <path-or-url>.
- 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.
- 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.
- Re-run until clean. For CI, use
--json (machine output) and/or --strict (fail on warnings).
Workflow 3 — Test a live registry API
- 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).
- Required checks failing → the server is not ARD-conformant on the mandated floor (
/search).
Fix the envelope/status against references/registry-api.md.
- For exploratory calls, hit endpoints directly with
curl (see references/registry-api.md).
Workflow 4 — Update / maintain
- Edit the entry. Keep the
identifier URN stable — it is a permanent contract. To move an
endpoint, change url (or data), never the URN.
- Bump the entry's
version and refresh updatedAt (ISO 8601) when the artifact changes.
- Adding a resource → append an entry; ensure its
identifier is unique (the validator flags
duplicates).
- 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.
1---
2name: ard-registry-builder
3description: >-
4 Build, validate, test, and update registries and catalogs that follow the Agentic Resource
5 Discovery (ARD) specification. Use this whenever the user works with an ai-catalog.json,
6 a capability manifest, an ARD/AIR catalog or Agent Registry, urn:air: identifiers,
7 trustManifest/attestations, representativeQueries, or an Agent Finder / discovery service —
8 including authoring a new manifest, scaffolding one, fixing schema or URN errors, running
9 conformance/validation, probing a registry's /search, /explore, or /agents REST endpoints,
10 reviewing trust and federation metadata, or preparing to publish at /.well-known/ai-catalog.json.
11 Trigger it even when the user only says "ARD", "agentic resource discovery", "AI catalog
12 manifest", "agent registry", or "make agents discoverable" without naming the file.
13license: MIT
14metadata:
15 source: https://skillmd.com/skills/webmaxru/ard-registry-builder
16 author: webmaxru
17 version: "1.4"
18---
19
20# ARD Registry Builder
21
22Agentic Resource Discovery (ARD) lets AI clients **discover** agents, MCP servers, skills, and
23APIs at runtime by search instead of hardcoding them. Publishers describe their resources in a
24static `ai-catalog.json` **capability manifest**; dynamic **Agent Registries** index those
25manifests and answer `POST /search`. This skill helps you engineer both — author, validate,
26test, and maintain them so they actually pass conformance and get discovered.
27
28Two artifacts, one mental model — **identity vs location**:
29- The **manifest** (`ai-catalog.json`, static) lists entries. Each entry's `identifier` is a
30 permanent `urn:air:` URN (identity); its `url`/`data` is the movable endpoint (location).
31- The **registry** (REST API, dynamic) is a service that searches indexed entries.
32
33Never bake a hostname into a URN; never treat a URL as an identity. Almost every ARD mistake
34traces back to confusing these two.
35
36## Bundled tools (use these — don't reinvent them)
37All scripts are stdlib-only Python 3.8+; `validate_catalog.py` uses the `jsonschema` library
38when present (recommended: `pip install jsonschema`) and falls back to a built-in checker.
39
40| Tool | Purpose |
41| :-- | :-- |
42| `scripts/validate_catalog.py <path-or-url> [--json] [--strict]` | Validate a manifest: JSON Schema **plus** ARD semantic rules. Exit 1 on errors. |
43| `scripts/test_registry.py <base-url> [--query T] [--json]` | Probe a live registry's `/search` (required), `/agents`, `/explore` for conformance. |
44| `scripts/new_catalog.py --template minimal\|enterprise\|local-dev [--publisher D] [--host N] --out F` | Scaffold a starter manifest. |
45| `assets/ai-catalog.schema.json` | JSON Schema for the `ai-catalog.json` manifest format (Draft 2020-12), bundled for offline validation. |
46| `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. |
47| `assets/templates/*.json` | Valid starting points: `minimal`, `enterprise` (trust + registry entry), `local-dev`. |
48
49Always **validate after every edit**, and validate the **live URL** after publishing — not just
50the local file.
51
52## Decide what the user needs
53- *"Create / scaffold / start a catalog"* → **Workflow 1**.
54- *"Validate / check / is this valid / why won't it pass conformance / fix this manifest"* →
55 **Workflow 2** (run `validate_catalog.py` first, before reading anything).
56- *"Test / probe my registry / does my /search work / is my API ARD-compliant"* → **Workflow 3**.
57- *"Add an agent / bump a version / change an endpoint / maintain"* → **Workflow 4**.
58- *"How does X work" (data model, API, trust, publishing)* → read the matching reference below.
59
60## Workflow 1 — Build a manifest
611. Pick the closest template and scaffold it:
62 `python scripts/new_catalog.py --template enterprise --publisher mycorp.com --host "MyCorp AI" --out ./ard.json`.
63 (Without scaffolding, copy a file from `assets/templates/`.)
642. For each resource, set `identifier` (`urn:air:<publisher>:<namespace?>:<name>`),
65 `displayName`, `type` (the artifact's media type), and **exactly one** of `url` or `data`.
663. Add `description`, `tags`, `capabilities`, and especially `representativeQueries` (2–5
67 natural-language queries) — the single biggest lever for being found by semantic search.
68 Absence is a conformance warning in v0.91; presence is still strongly recommended.
694. Add `trustManifest` only when you have real identity/attestations; keep simple entries lean.
705. Choose the publisher domain to match the deployment context (enterprise FQDN, public
71 namespace like `github.com:you`, or `agent.localhost`/`example.com` for local-only). See
72 `references/data-model.md`.
736. Validate: `python scripts/validate_catalog.py ./ard.json`. Fix until it passes.
74
75## Workflow 2 — Validate / debug a manifest
761. **Run the validator first**, before reading the file by hand — it pinpoints issues fast:
77 `python scripts/validate_catalog.py <path-or-url>`.
782. Read findings by severity. **ERROR** must be fixed; **WARN** should be (use `--strict` in CI
79 to enforce); **INFO** is advice. Every finding names a JSON path and a stable `code`.
803. Map the `code` to a fix using `references/validation-rules.md`. The high-frequency ones:
81 - `urn-wrong-nid` → change `urn:ai:` to `urn:air:`.
82 - `value-or-reference` → keep exactly one of `url` / `data`.
83 - `schema` (oneOf/required/pattern/minItems) → fix the structure the message names.
84 - `urn-localhost` / `urn-publisher-fqdn` → use a verifiable or reserved-placeholder domain.
85 - `trust-domain-mismatch` → make the `trustManifest.identity` domain match the URN publisher.
864. Re-run until clean. For CI, use `--json` (machine output) and/or `--strict` (fail on warnings).
87
88## Workflow 3 — Test a live registry API
891. Probe it: `python scripts/test_registry.py https://registry.example.com/api/v1`.
90 The tester sends a real `POST /search`, validates the `results` envelope (each item is a
91 catalog entry carrying a `score` 0–100 and a `source`), confirms a malformed request is
92 rejected with `400 + errorCode + message`, and checks optional `/agents` and `/explore`
93 (skipped, not failed, when a server returns `404`/`501`).
942. Required checks failing → the server is not ARD-conformant on the mandated floor (`/search`).
95 Fix the envelope/status against `references/registry-api.md`.
963. For exploratory calls, hit endpoints directly with `curl` (see `references/registry-api.md`).
97
98## Workflow 4 — Update / maintain
991. Edit the entry. **Keep the `identifier` URN stable** — it is a permanent contract. To move an
100 endpoint, change `url` (or `data`), never the URN.
1012. Bump the entry's `version` and refresh `updatedAt` (ISO 8601) when the artifact changes.
1023. Adding a resource → append an entry; ensure its `identifier` is unique (the validator flags
103 duplicates).
1044. Re-validate the file; if it is already published, also validate the live URL and re-probe any
105 registry. Treat "passes validation" as the definition of done.
106
107## Golden rules (the why behind the checks)
108- **URN = identity, url/data = location.** Stable URNs keep search indexes, client references,
109 and orchestration working while infrastructure moves underneath them.
110- **The publisher segment must be a verifiable FQDN.** Registries extract it and bind it to
111 `trustManifest.identity` to stop namespace squatting. `localhost` and bare words break this.
112- **Exactly one of `url` or `data`.** Predictable parsing in enterprise pipelines depends on it.
113- **`score` is relevance, not trust.** Never gate safety on a search score; verify
114 `trustManifest` independently.
115- **Validate early, validate often, validate the live URL.** Most "it won't index" problems are
116 schema or hosting issues a 1-second validator run would have caught.
117
118## Reference files
119Read the one matching the task; each has a table of contents.
120- `references/data-model.md` — manifest/entry fields, URN format, media types, value-or-reference,
121 trust manifest, JSON-LD context extension, and the known `urn:air:` vs `urn:ai:` doc inconsistencies.
122- `references/registry-api.md` — `/search`, `/explore`, `/agents`, the query/filter model,
123 federation modes, and error codes.
124- `references/validation-rules.md` — every check the validator runs, with its `code` and severity.
125- `references/publishing.md` — well-known URI (`ard.json`), CORS, DNS discovery, and public reference
126 registries to test against.
127
128## Evals
129`evals/evals.json` holds realistic task prompts for the skill-creator evaluation loop. Use it to
130benchmark or regression-test changes to this skill.