@cave-man/realtime-register-skills

A hand-curated, fidelity-verified specification and CLI for the Realtime Register REST API v2. Every non-SiteLock endpoint — 109 operations across 16 categories — is described in machine-readable YAML, reconciled field-by-field against the live HTML documentation at dm.realtimeregister.com/docs/api.

One package, two audiences:

• AI agents load SKILL.md + references/*.md as structured context and validate outgoing requests through rtr validate.
• Human developers use rtr at the terminal for schema-validated request construction, operation lookup, and doc-link auditing.

---

Highlights

• 100 % fidelity — all 109 operations carry verified: docs (path, URL params, query params, and request-body fields reconciled against the live HTML). See docs/fidelity.md.
• Runtime validation — JSON Schemas derived from the YAML, evaluated by ajv with format checks for email, uri, date, date-time, ipv4, ipv6.
• Agent-first docs — SKILL.md + references/<category>.md are the only files an LLM needs to load; they are terse, structured, and stable.
• Zero-surprise CLI — six subcommands, no config files, no env vars, no network access except doctor and scrape.
• CamelCase everywhere — matches the official TypeScript SDK and the on-the-wire protocol.

---

Quick start

Install as an agent skill

Drop the skill (SKILL.md + references/ + assets/spec/) into your agent client's skills directory — one command, no prior install:

npx @cave-man/realtime-register-skills install

The installer auto-detects these targets. When multiple matches exist and stdin is a TTY, you'll be prompted to choose one; non-interactive callers (CI, --yes, piped input) get the first match:

Client	Path
Claude Desktop (macOS)	~/Library/Application Support/Claude/skills/
Claude Desktop (Windows)	%APPDATA%\Claude\skills\
Claude Desktop (Linux)	~/.config/Claude/skills/
Claude Code CLI	~/.claude/skills/
Augment	~/.augment/skills/
Local project fallback	./skills/

Override with --target <dir> or the REALTIME_REGISTER_SKILL_DIR env var. Installer subcommands:

npx @cave-man/realtime-register-skills install --dry-run           # preview
npx @cave-man/realtime-register-skills install --target ./skills   # explicit dir
npx @cave-man/realtime-register-skills install --global            # + npm i -g (rtr on PATH)
npx @cave-man/realtime-register-skills where                       # list detected targets
npx @cave-man/realtime-register-skills uninstall                   # remove the skill

Install the rtr CLI

# one-off (recommended)
npx @cave-man/realtime-register-skills rtr --help

# or globally
npm install -g @cave-man/realtime-register-skills
rtr --help

Describe an operation

rtr describe createDomain

Validate a request body before sending

cat > /tmp/register.json <<'JSON'
{
  "registrant": "H1234567",
  "period": 12,
  "ns": ["ns1.example.com", "ns2.example.com"],
  "privacyProtect": true
}
JSON

rtr validate createDomain --body /tmp/register.json
# → exits 0 if the body matches the schema, 1 otherwise

Audit every documentation link

rtr doctor
# OK  200 createDomain      https://dm.realtimeregister.com/docs/api/domains/create
# OK  200 getDomain         https://dm.realtimeregister.com/docs/api/domains/get
# … 109 lines total, non-200s exit non-zero.

---

CLI at a glance

Two binaries ship in this package:

skills — the installer entry point (npx @cave-man/realtime-register-skills …).

Command	Purpose
skills install [--target <dir>] [--global]	Install the skill into a detected or explicit target; optionally npm i -g.
skills uninstall [--target <dir>] [--all]	Remove the skill from one or all installed targets.
skills where	Print every known target and its install state.
skills doctor	rtr doctor against the packaged spec.
skills rtr <subcommand> [...]	Pass-through to the rtr CLI below without a separate install.

rtr — the operation / schema CLI.

Command	Purpose
rtr list [--category <name>]	List all operations or one category.
rtr describe <operationId>	Full contract for one operation: path, params, body, errors, gotchas, examples.
rtr validate <operationId> --body <file.json>	Validate a request body, query, or path params against the schema.
rtr generate [--category <name>]	Render references/<category>.md from the YAML.
rtr scrape <operationId>	Fetch the live HTML doc for an operation; print a spec skeleton.
rtr doctor [--category <name>]	Verify every docUrl returns HTTP 200.

Full flag reference in docs/cli.md.

---

Spec layout

The source of truth is assets/spec/:

assets/spec/
├── _shared.yaml        # enums and reusable nested types
├── domains.yaml        # 13 operations (11 customer + 2 gateway)
├── hosts.yaml          #  5 operations
├── contacts.yaml       # 11 operations
├── dnsZones.yaml       #  9 operations
├── dnsTemplates.yaml   #  5 operations
├── validation.yaml     #  2 operations
├── ssl.yaml            # 17 operations
├── sslAcme.yaml        #  7 operations
├── notifications.yaml  #  5 operations
├── processes.yaml      #  5 operations
├── customers.yaml      #  2 operations
├── brands.yaml         # 10 operations (CRUD + templates + locales)
├── financial.yaml      #  4 operations
├── tlds.yaml           #  2 operations
├── providers.yaml      #  7 operations (incl. gateway-only registry accounts)
└── misc.yaml           #  5 operations (IsProxy + 4 ADAC WebSocket actions)

Each operation carries operationId, method, path, docUrl, async, authScope, deprecated, verified, pathParams, queryParams, requestBody.fields, responses, errors, gotchas, and examples. Full schema in docs/spec-format.md.

---

Using the skill from an AI agent

The SKILL.md file at the repo root is the canonical entry point. Load it into your agent's system context along with the relevant references/<category>.md file(s). A typical flow:

1. Agent receives user request ("renew example.com for two years").
2. Agent loads SKILL.md → learns the hard rules (camelCase, period in months, async polling, billable acknowledgment).
3. Agent loads references/domains.md → finds the renewDomain entry.
4. Agent builds the payload and calls rtr validate renewDomain --body … before issuing the HTTP request.
5. On HTTP 202, agent polls /v2/processes/{processId} via the processes category.

End-to-end integration notes, a programmatic validation snippet, and the billable-acknowledgment / async-mutation patterns are documented in docs/agent-integration.md.

---

Fidelity markers

Every operation declares a verified marker:

• docs — path, URL parameters, query parameters, and request-content fields reconciled against the live HTML.
• sdk — derived from the public TypeScript SDK and the navigation slug only; no HTML-level reconciliation yet.

As of v0.1.0, all 109 operations carry verified: docs. Promotion workflow, drift policy, and enforcement tooling are documented in docs/fidelity.md.

---

Documentation index

File	Audience	Purpose
SKILL.md	AI agents	Skill card with activation rules and hard invariants
references/<category>.md	AI + human	Per-category operation reference (generated)
docs/agent-integration.md	Agent devs	How to load the skill, validate payloads, handle async
docs/cli.md	Humans	Full CLI flag and exit-code reference
docs/spec-format.md	Contributors	YAML schema for every field in assets/spec/
docs/fidelity.md	Maintainers	Reconciliation policy and drift detection
CONTRIBUTING.md	Contributors	How to land a PR
HANDOVER.md	Maintainers	End-to-end project memory and onboarding guide
CHANGELOG.md	Everyone	Release history

---

Requirements

• Node.js 20.11 or newer.
• No runtime Realtime Register account needed for the CLI — schema validation is local. You only need credentials to actually call api.yoursrs.com.

---

Contributing

See CONTRIBUTING.md. In short: never edit references/*.md directly (they are generated), keep field names camelCase, and run rtr doctor + node scripts/audit-refs.mjs before opening a PR.

---

Licence

MIT. Not affiliated with Realtime Register B.V.; this project merely consumes their public documentation.