Skill Gateway

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. When a skill is updated, there is no propagation mechanism every consumer must discover and pull the change manually. A centralised registry with push-based invalidation and pull-based install fixes this.

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 installed where and when. Regulated environments, or any environment with meaningful security requirements, need to be able to answer: which version of this skill ran in this agent at this time, and who authorised it?

Static and dynamic delivery. Skills today are only static: loaded at startup, fixed for the lifetime of the agent session. A number of real orchestration patterns require dynamic skill injection an orchestrator determines mid-task that it needs a capability it was not started with, and needs to acquire it at runtime from a registry without restarting the agent. Static and dynamic delivery are two modes of the same distribution problem, not two separate systems.

These four requirements versioning, centralisation, governance, dynamic delivery are what motivate the Skill Gateway architecture.

What a Skill Gateway Is

A skill gateway is a service that mediates between skill producers (teams that author and publish skills) and skill consumers (agents that use them). It handles:

Registry a queryable index of available skills, versions, and metadata
Distribution fetching the right skill artifact for the requesting agent’s platform
Install unpacking the skill into the local .skills/ directory so the agent can load it
Validation pre-flight checks for runtime requirements, platform compatibility, and signatures
Dynamic injection serving skills to running agents on demand via an MCP interface

The gateway is the skill equivalent of what npm, pip, or a package registry does for code dependencies but purpose-built for AI skill artifacts.

How the Skill Interface Works

The skill interface is unchanged from the existing Hermes SKILL.md format. This is a deliberate constraint: agents do not need to know anything about how a skill was packaged, distributed, or installed. They read a SKILL.md, which describes the capability, and use whatever is in the skill directory.

The gateway’s job is to ensure that after installation, every skill looks identical to the agent regardless of how it was sourced.

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

See Skill Format for the full specification of both files.

Static vs Dynamic Delivery

Skills can be delivered to agents in two modes. Both modes use the same registry and the same skill format they differ only in when delivery happens.

Static delivery

Skills are resolved at environment setup time, before agents start. The root skill.yaml in the workspace declares which skills are needed. Running skill install resolves versions, runs pre-flight checks, and populates .skills/. 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 delivery

A running agent requests a skill from the gateway at runtime via an MCP server interface. The gateway resolves, installs, and activates the skill within the agent’s current session without restarting it.

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 MCP interface exposes four operations to the running agent:

search_skills find skills by capability tag or natural language description
describe_skill read a skill’s SKILL.md before committing to install it
install_skill pull and activate a skill for the current session
list_installed enumerate currently active skills

The gateway enforces the same signing and policy checks for dynamic installs as for static ones.

Backing Systems

The gateway supports multiple backing systems for skill distribution. The agent sees none of this it always receives the same <skill-name>/SKILL.md + scripts/ structure regardless of what backs the skill.

Backing type	Description
OCI	Primary. Skill directory packaged as an OCI artifact in any OCI-compatible registry. Versioned, signed, multi-arch.
npm	Skill backed by an npm package. Gateway runs `npm install` into `.skills/<name>/.npm/`, generates a wrapper in `scripts/`.
pip	Skill backed by a Python package. Gateway creates a venv at `.skills/<name>/.venv/`, generates a wrapper in `scripts/`.
Nix	Skill backed by a Nix derivation. Gateway uses `nix shell` to provide a hermetic runtime environment.
WASM	Skill packaged as a WebAssembly module. Cross-arch, sandboxed, no host runtime required.

The preferred backing for new skills authored by this organisation is OCI. npm and pip backing exist to proxy skills that are primarily distributed through those ecosystems, not as first-choice formats for new work.

Relationship to Existing Concepts

Skills The skill concept and format. The gateway distributes skills; it does not change what a skill is.
Skill Gateway Prior Art Comparative baseline for gateway design decisions.
Context Development Lifecycle The gateway is the distribution layer in the generate → evaluate → distribute → observe loop.
Skill Evaluation Evaluation artifacts (scenario suites, results reports) are bundled with the skill in the OCI layer and distributable through the same gateway.
ACRI Agents acquire skills through the gateway. ACRI-compliant harnesses should support the gateway’s dynamic injection interface as a capability advertisement.
Orchestrator The orchestrator is the primary consumer of dynamic skill injection: it determines capability requirements per task and requests skills from the gateway accordingly.