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, integrity model, install pipeline, and publish flow. 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.

​
Actors

Author

Creates facets for agentic use. Publishes to the registry.

CLI

Installs facets, manages the lockfile and caches.

Registry

Stores archives, provides provenance, and acts as an integrity authority.

AI assistant

Loads facets into context.

​
The facet artifact

A facet is a named, versioned collection of text assets — skills, agents, and commands — defined by a manifest. The author’s CLI builds it into a self-contained facet archive (.facet): the manifest plus every text asset. The registry verifies and stores that archive, and consumers receive exactly the bytes the author built — no text is fetched or assembled at install time.
Stale text is safe (suboptimal, not broken). Changed text is a trust concern (prompt injection). That is why content is locked into the archive at build time and every install verifies the published hashes.

​
Lifecycle

1

Author

Create a facet.json manifest and text asset files in a local directory.
2

Build & publish

The CLI builds the archive and computes its ; the registry verifies the upload, stores it, and publishes the hashes. A published version is immutable. See Build and Publish.
3

Install

The plan/commit pipeline resolves versions, verifies integrity (cache self-audit + lockfile comparison or registry confirmation), materializes assets, and writes manifest + lockfile + receipt atomically.
4

Run

Text assets in the assistant’s context.

​
Security and trust

Facets enable arbitrary text injection into AI assistant contexts. Implementors MUST address:
  1. Content verification — hashes MUST be verified at download, on every cache hit, and at lockfile-entry creation. A lockfile entry for a registry facet MUST NOT be created without registry confirmation.
  2. User consent — consumers SHOULD understand what a facet contains before installing it.

​
Sections

Project Manifest

The facets.json format — declared facets and entry semantics.

Lockfile

The facets.lock format — resolved versions and integrity.

Facet Manifest

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

Facet Archive

The two-layer .facet format — layout, determinism, hashes.

Integrity Model

Content hashing and cache audit.

Installation

Two-phase pipeline: planning, then commit.

Planning

Phase 1 — turn a command into a delta.

Commit

Phase 2 — resolve, compose, materialize, write atomically.

Materialization

Authored vs. effective names, aliasing, omission, collisions.

Build

Produce the canonical .facet archive.

Publish

Verify and upload to the registry.

Terminology

Canonical terms and definitions.