Skip to main content
Facets are an open format and distribution system for modular AI assistant extensions. A facet packages skills, agents, and commands into a versioned, distributable unit with a well-defined manifest, publish flow, install pipeline, 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.

​
Security and trust

Facets enable arbitrary text injection into AI assistant contexts and arbitrary code execution via MCP servers. Implementors MUST address:
  1. Composition integrity — composed text MUST be assembled server-side from trusted sources.
  2. Content verification — hashes MUST be verified at install time and on every cache hit. A lockfile entry MUST NOT be created without registry confirmation.
  3. Server execution safety — the CLI MUST control exactly what executes. Servers MUST stop when the session ends.
  4. User consent — consumers SHOULD understand what a facet contains before installing it.

​
Sections

Terminology

Canonical terms and definitions.

Integrity Model

Content hashing, cache audit, OCI digests, API surface hashing.

Install & Resolve

How facets are installed and server references resolved.

Install Pipeline

Plan/commit pipeline, integrity chain, receipt, tri-write.

Publish Flow

How facets are built and published to the registry.

Architecture

Actors, artifact types, distribution model, design principles.

Manifest Schema

The facet.json format — fields, types, constraints.

MCP Server Assets

Source-mode and ref-mode server publication and execution.