Skill Gateway

7 min read

Why This Is Needed

Skills in the current system are static files SKILL.md and supporting assets committed to a repository and loaded by an agent harness at startup. This works well for small, stable skill sets owned by a single team. It does not scale to the requirements of an enterprise agentic platform:

Versioning. There is no reliable mechanism today to pin a skill to a specific version, roll back a bad change, or ship a breaking change to some agents while others stay on the previous version. Git tags on the whole repository are too coarse. Skills need their own independently addressable versions, just as packages in npm or pip do.

Centralisation. Skills are currently replicated wherever agents are deployed. There is no single source of truth for what exists, which version is current, or where an artifact can be obtained. A central registry makes that catalog queryable without deciding how each consumer installs a selected skill.

Governance. There is no policy layer over which skills can be used by which agents, no signing mechanism to verify skill provenance, and no audit trail of what was retrieved from the registry and by whom. Environments with meaningful security requirements need to establish which skill version was selected, where it came from, and whether the caller was authorised to access it.

Static and dynamic discovery. A workspace can declare skills before an agent starts, but open-ended orchestration also needs to search for capabilities during a task. Both cases need a registry that can resolve a requirement to a specific skill and version. Installation and activation remain local operations in either case.

These four requirements versioning, centralisation, governance, and dynamic discovery motivate the Skill Gateway architecture.

What a Skill Gateway Is

A Skill Gateway is a deployed registry and discovery service between skill producers and skill consumers. It handles:

Registry a queryable index of available skills, versions, capabilities, and metadata
Resolution mapping a skill requirement to an immutable artifact or source reference
Discovery tools exposing search and description operations to agents and orchestrators
Registry policy controlling which producers, artifacts, and versions are visible to a caller
Provenance returning hashes, signatures, source records, and publication metadata that a client can verify
Registry events and audit recording publication and retrieval activity and notifying consumers that catalog entries changed

The Gateway does not install a skill into an agent’s environment. It does not provision Node.js or Python, select a host-native binary, create a virtual environment, generate wrappers, write .skills/, or activate a skill in a running harness. Those are responsibilities of a CLI, harness integration, or another local installation tool.

The closest analogy is a package registry API, not a package manager. The Gateway answers what is available and where is the verified artifact? The installation client answers can this machine use it, and how should it be installed here?

Gateway and Installation Client

Keeping these components separate prevents a remote service boundary from being confused with local package management:

Concern	Skill Gateway	Installation client or harness tool
Search and describe skills	Yes	Calls the Gateway or another configured registry
Resolve versions and artifact references	Yes	Requests and records the selected resolution
Apply registry access policy	Yes	Supplies caller identity and honours the result
Inspect the host environment	No	Yes
Fetch and verify artifacts	Supplies source and provenance metadata	Yes
Provision runtimes and dependencies	No	Yes, where supported
Select OS- and architecture-specific binaries	Describes available variants	Yes
Write local skill directories and lock files	No	Yes
Adapt a skill to an agent harness	No	Yes
Activate or remove a skill	No	Yes

The skill interface remains based on SKILL.md, but the Gateway does not guarantee that every installed skill looks identical. Skill authors define an artifact, the registry describes it, and the installation client decides whether and how it can be represented in the target harness. Any normalization, wrapper generation, or directory layout is a client-side concern.

One installation client might produce this layout:

.skills/
└── <skill-name>/
    ├── SKILL.md         ← what the agent reads
    ├── scripts/         ← executables and helpers
    ├── references/      ← supplementary docs the agent may read
    ├── templates/
    ├── assets/
    └── skill.yaml       ← local installation metadata, never read by the agent

This is an installation convention, not the deployed Gateway’s filesystem contract. See Skill Format for the metadata exchanged between registry and installation tooling.

Static vs Dynamic Use

Static and dynamic use share the same registry. They differ in when discovery occurs and who invokes the local installation client.

Static setup

Skills are resolved at environment setup time, before agents start. The root skill.yaml in the workspace declares which skills are needed. A local skill install client queries the Gateway, fetches and verifies the selected artifacts, runs host pre-flight checks, and installs them into the agent’s environment. The agent starts with all required skills already present.

This is the right model for predictable workloads where the agent’s capability set is known in advance most scheduled or task-queue-driven agents.

Dynamic discovery and installation

A running agent or orchestrator searches the Gateway at runtime through a tool interface. After selecting a skill, it invokes a separate local installation tool. That tool resolves the artifact for the host, performs policy and compatibility checks, installs it, and asks the harness to activate it if the harness supports runtime activation.

This is the right model for open-ended orchestration, where the agent encounters task requirements it was not pre-loaded to handle. An orchestrator, for example, may spawn a specialised sub-agent only after analysing an incoming ticket and determining what capability is needed.

The boundary should remain visible in the tool surface.

Gateway operations:

search_skills find skills by capability tag or natural-language description
describe_skill inspect a skill, its versions, requirements, and provenance
resolve_skill return an immutable artifact reference and supported platform variants

Local installation operations:

install_skill fetch, verify, install, and optionally activate the resolved skill
list_installed enumerate skills in the local environment
remove_skill deactivate and remove a locally installed skill

The Gateway applies registry-side access and publication policy. The installation client must independently enforce host-side signature, runtime, architecture, credential, and sandbox requirements. A successful registry resolution is not proof that installation will succeed or that execution is safe on the target system.

Artifact Sources

The Gateway can index skills whose artifacts live in different backing systems. It returns source metadata and supported variants; the installation client implements the corresponding adapter.

Backing type	Gateway record	Installation-client responsibility
OCI	Artifact reference, digest, signature, platform manifests	Select the host manifest, fetch layers, verify, and unpack
npm	Package, version, registry, integrity, runtime requirements	Run the package manager and create any local adapter
pip	Package, version, index, hash, runtime requirements	Create or select an environment and install the package
Nix	Flake reference and lock metadata	Realise or enter the declared environment
WASM	Module reference, digest, and declared capabilities	Verify the module and configure a compatible runtime

OCI can be the preferred publication format without making the Gateway an OCI installer. Likewise, npm and pip records can be discoverable without the deployed Gateway running those package managers on the consumer’s machine.

Relationship to Existing Concepts

Skills The skill concept and lifecycle. The Gateway makes skills discoverable; local tooling installs them.
Skill Gateway Prior Art Comparative baseline for gateway design decisions.
Context Development Lifecycle The Gateway is a registry and discovery component in the distribution stage; installation clients complete delivery to an environment.
Skill Evaluation Evaluation results can be attached to registry entries so consumers can inspect evidence before selecting a version.
ACRI Harnesses can advertise support for Gateway discovery separately from support for local runtime installation and activation.
Orchestrator An orchestrator can search the Gateway for a capability, then delegate installation to the target environment’s local tool.