Skip to main content
The vocabulary behind Facets. For normative rules, see the Specification.

​
Facets

A facet is a versioned bundle of assets. Your project declares the facets it wants, and an install resolves each one to an exact version, verifies its content, and materializes its assets into every AI tool you have connected. The same bundle is authored locally, published to the registry, and installed into a project. Its own identity and contents are declared in a facet manifest (facet.json) that ships inside the facet.

​
Project state

Two files in your repository describe what the project depends on. Commit both.

facets.json

What you declared: the facets you want, and how you want their assets named.

facets.lock

What that resolved to: exact versions, provenance, and integrity hashes.
You edit facets.json, usually through the CLI. The lockfile is written only by an install, so a teammate who clones the repository and runs facet install gets the same versions and the same bytes you did.

​
Assets

An asset is one unit a facet ships. Every asset is versioned with the facet, integrity-checked, and materialized into your tools on install.

Skills

Knowledge the assistant applies passively.

Commands

Workflows the user invokes.

Agents

Personas with a role and tool access.

MCP servers

Tools and data your assistant can reach.
Skills, commands, and agents are text assets: prompt content that materializes as files your project owns. Skills follow the Agent Skills specification; agents and commands are single-file conventions defined by the facet specification. An MCP server is the one asset that is not a text asset. It materializes as an entry inside your tool’s own configuration rather than a file your project owns, which is why it has its own identity space and needs your approval before it is written.

​
Adapters

An adapter is not something a facet ships. It is the layer that knows where one AI tool keeps files and configuration, and it materializes a facet’s assets into that tool. Install one per tool you use. See Adapters.