Overview - Agent Facets

Facets are an open format and distribution system for modular AI assistant extensions. A facet packages skills, agents, and commands — the text assets that shape how an AI assistant behaves — into a versioned, distributable unit with a well-defined manifest, publish flow, install flow, and integrity model. This specification defines the authoritative requirements for the Facets format and protocol. For introductory material, see Introduction and Key Concepts. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119 and RFC 8174.

Key Details

A facet is a named, versioned collection of text assets — skills, agents, and commands — defined by a manifest (facet.yaml). Facets MAY compose text from other facets and MAY reference MCP servers. When a facet is published, the registry assembles a facet archive — a self-contained artifact containing the manifest and all text assets (both locally authored and composed). The archive is the unit of distribution between the registry and consumers.

MCP Servers

MCP servers are code assets — separate from facets — that provide tool capabilities to AI assistants via the Model Context Protocol. A facet’s manifest references servers; it does not contain them. Two execution modes are defined:

Source-mode: Server source code is published to the facets registry and run using a managed runtime.
Ref-mode: The facet manifest references an OCI container image hosted in an external registry.

Integrity

Three integrity mechanisms protect the supply chain:

Content hashing: SHA-256 of facet archives and source-mode server artifacts. Verifies downloaded bytes match what was published.
OCI digest pinning: Immutable content hashes for ref-mode server container images. Pins exact images in the lockfile.
API surface hashing: SHA-256 of MCP server tool declarations. Detects structural breaking changes between server versions.

Lifecycle

Stage	What happens
Authoring	An author creates a facet — a manifest and text assets in a local directory.
Publishing	The facet is built into an archive — text assets assembled, hashes computed, stored in registry.
Installing	The archive is downloaded, verified, extracted. Server references are resolved and pinned.
Running	The installed facet is loaded by the AI assistant. Text assets are in context. Servers are running.

Security and Trust

Facets enable arbitrary text injection into AI assistant contexts and arbitrary code execution via MCP servers. Implementors MUST address these trust considerations:

Composition integrity: Composed text assets MUST be assembled server-side by the registry from trusted sources. Authors MUST NOT be able to upload pre-assembled composed content.
Content verification: Consumers MUST verify content hashes at install time. A hash mismatch MUST be a hard failure.
Server execution safety: The CLI MUST control exactly what executes. No arbitrary command or argument execution. Servers MUST be stopped when the AI assistant session ends.
User consent: Consumers SHOULD understand what a facet contains before installing it. Implementors SHOULD provide clear mechanisms for reviewing facet contents and server capabilities.