Skip to main content
facet build produces the canonical .facet archive from the author’s source tree and writes it to dist/<name>-<version>.facet. This is the artifact of record: the bytes facet publish will later verify and upload. There is a single source of truth for what a .facet is: the two-layer archive format, whose content-hash contract is described in the Integrity Model.

​
Steps

  1. Adapter compatibility preflight. Every installed adapter MUST declare an adapter API the CLI supports. An installed adapter with a missing, malformed, or unsupported declaration MUST fail the build here — before manifest metadata validation and before any adapter method is invoked — with diagnostics identifying each incompatible adapter and its reinstall command. This gate applies to installed adapters; adapters that are named in the manifest but not installed are handled in step 4.
  2. Parse and validate the manifest. Read the facet manifest (facet.json) and validate it against the manifest schema. Invalid manifests MUST be rejected with a descriptive error. The manifest’s name MUST be a valid facet identity; the version MUST be a semver string; at least one text asset MUST be declared.
  3. Resolve prompts. Read each declared asset file from its conventional path: skills/<name>/SKILL.md for skills, agents/<name>.md for agents, commands/<name>.md for commands. Missing files are build errors. Primary asset files MUST NOT contain YAML front matter — the manifest is the single source of asset metadata, and a primary file that carries front matter is a build error. (Authoring tools strip front matter before writing.)
  4. Resolve supplementary files. Read each declared supplementary file as opaque bytes: top-level entries from the manifest’s files array, and each skill’s companions from its files array (relative to the skill directory). Supplementary bytes are shipped verbatim — binary and empty files are valid, and front matter is never parsed or stripped. A declared-but-missing file, a path that resolves to a symlink or non-regular file, an unsafe or non-portable path, or a resolved-path collision is a build error.
  5. Validate content. A declared primary asset MUST NOT be empty (zero bytes or whitespace only). Asset names MUST be single-segment Agent Skills names; skills and commands share one namespace and MUST NOT collide, while agents are separate. Compact facets[] entries MUST match the name@version shape.
  6. Validate adapter metadata. For each asset with an adapters block, validate the adapter-specific metadata against each installed adapter’s schema. Unknown adapters SHOULD produce a warning. Invalid metadata for an installed adapter MUST be a build error.
  7. Assemble the archive. Drive collection and hashing from the shared archive plan derived from the manifest. Compute a per-entry SHA-256 hash for every entry — facet.json, primaries, and supplementary files alike. Assemble the deterministic inner tar. Compute the integrity hash over the uncompressed inner tar. Gzip the inner tar (archive.tar.gz). Assemble the outer tar containing build-manifest.json (recording the integrity hash and the complete files hash map) plus the gzipped inner archive. Write the result to dist/<name>-<version>.facet. The layout, determinism rules, and hash domains are specified in Facet Archive.
Every build emits the current facetVersion: 0.2 format — including asset-only facets, which carry no supplementary files. Validation happens before cleanup: all source inputs (steps 1–5) are validated before dist/ is touched, so a build that fails validation leaves the previous dist/ output intact. Only after validation succeeds does facet build purge dist/ and write, so the directory contains exactly one .facet after a successful build: the archive for the current source’s name and version. For a scoped facet identity, the name’s / renders as a nested path under dist/ — @acme/cowsay at 1.0.0 is written to dist/@acme/cowsay-1.0.0.facet, with parent directories created as required. Build output displays the emitted format version, the complete entry listing, and the integrity hash.

​
Boundaries

Building never contacts the registry and never mutates the manifest. What happens to the built artifact next — verification, upload, drift handling — is defined in Publish. Command usage and flags are documented at facet build.