URI Scheme

Every primitive instance in CKP is addressable via a claw:// URI. This enables unambiguous references between tools, skills, swarm peers, and registry packages.

---

Canonical forms

CKP defines two canonical URI forms:

Local

References a primitive defined in the current manifest or available on the local runtime:

claw://local/{kind}/{name}
claw://local/{kind}/{name}@{version}

Examples:

claw://local/identity/research-assistant
claw://local/tool/web-fetch
claw://local/tool/[email protected]
claw://local/sandbox/container-sandbox
claw://local/world-model/environment-model

Registry

References a primitive published to a remote registry:

claw://registry/{namespace}/{name}@{version}

Examples:

claw://registry/community-skills/[email protected]
claw://registry/datastrat/[email protected]

Registry URIs MUST include a version. The registry endpoint is configured at the runtime level, not in the protocol.

---

Alias form (manifest only)

For ergonomics, manifests support a shortened alias form:

claw://{kind}/{name}

This resolves to claw://local/{kind}/{name} before any wire transmission.

Examples:

# In claw.yaml -- alias form for readability
tools:
  - name: web-fetch
    sandbox: claw://sandbox/network-sandbox   # alias
    policy: claw://policy/standard-policy     # alias

Alias URIs MUST NOT appear in JSON-RPC messages. The runtime resolves them to canonical form during the INIT phase.

---

ABNF grammar

The URI scheme follows RFC 5234 (ABNF):

claw-uri      = claw-local / claw-registry

claw-local    = "claw://local/" kind "/" name [ "@" version ]
claw-registry = "claw://registry/" namespace "/" name "@" version

kind          = "identity" / "provider" / "channel" / "tool"
              / "skill" / "memory" / "world-model" / "sandbox"
              / "policy" / "swarm" / "telemetry"

name          = 1*63( ALPHA / DIGIT / "-" )
namespace     = 1*63( ALPHA / DIGIT / "-" / "." )

version       = semver
semver        = 1*DIGIT "." 1*DIGIT "." 1*DIGIT [ "-" pre-release ]
pre-release   = 1*( ALPHA / DIGIT / "-" / "." )

---

Validation rules

1. Kind MUST be one of the 11 primitive types. Unknown kinds are invalid.
2. Name MUST be 1-63 characters, alphanumeric plus hyphens.
3. Registry URIs MUST include a version. Local URIs MAY omit it.
4. Alias URIs MUST be resolved before wire transmission. A runtime that sends an alias URI over JSON-RPC is non-conformant.
5. Names are case-sensitive. Web-Fetch and web-fetch are different primitives.

---

Registry resolution

The runtime resolves registry URIs using configured registry endpoints:

# Runtime configuration (not part of the manifest)
registries:
  - name: default
    url: https://registry.clawkernel.dev/v1
  - name: internal
    url: https://registry.company.com/v1

Resolution order:

1. Check local manifest for a matching primitive
2. Query configured registries in order
3. Return the first match or fail with an error

Registry resolution happens during the INIT phase. By the time the agent reaches READY, all URIs are fully resolved.

---

Quick reference

Form	Pattern	Wire Valid	Example
Local	claw://local/{kind}/{name}	Yes	claw://local/tool/web-fetch
Local + version	claw://local/{kind}/{name}@{ver}	Yes	claw://local/tool/[email protected]
Registry	claw://registry/{ns}/{name}@{ver}	Yes	claw://registry/community/[email protected]
Alias	claw://{kind}/{name}	No (manifest only)	claw://sandbox/network-sandbox