Skip to main content
Facets are an open format for modular AI assistant extensions. A facet packages assets, which are skills, agents, commands, and MCP server declarations, into a versioned, distributable unit. This specification defines the requirements an implementation must satisfy to produce or consume facets. For introductory material, see Key Concepts. Terms are collected in Terminology. Because a facet injects text into an assistant’s context and its server declarations can make a tool run commands, content verification and execution consent are part of the core contract rather than optional hardening.

​
Project state

A consuming project holds two version-controlled files.

facets.json

The project manifest: which facets the project depends on, and how it wants their assets materialized.

facets.lock

The lockfile: what those dependencies resolved to, with verified integrity and per-file records.
The manifest records intent and the lockfile records resolution. Both are committed. An install also writes a machine-local ownership record, which is deliberately not.

​
The facet artifact

A facet is a named, versioned collection of assets: text assets and portable MCP server declarations, described by a facet manifest. It is built into a self-contained archive, and consumers receive exactly the bytes the author built.

Facet Manifest

facet.json: identity, assets, and declarations.

Facet Archive

The .facet container and its content rules.

Integrity Model

The hash domains, and when each MUST be verified.
Throughout this specification, uppercase key words such as MUST, MUST NOT, and MAY carry the meanings defined in RFC 2119 and RFC 8174. The same words in lowercase are ordinary prose.