Skip to main content

​
Usage

Creates a new facet project in the specified directory (defaults to the current directory). With no authoring flags, walks through an interactive wizard; with any authoring flag, scaffolds directly in headless mode. If a facet.json already exists in the target directory, the command prompts for confirmation before overwriting. Use --force to skip the prompt.

​
Examples

​
Flags

​
string
required
Facet name; required in headless mode. An unscoped slug or a scoped @scope/name — see the name grammar.
​
string
Facet description (headless mode).
​
semver
Facet version (headless mode). Defaults to 0.0.0; must be semver.
​
boolean
Mark the facet private (private: true).
​
repeatable
An asset to scaffold. Repeat per asset; at least one is required in headless mode. Asset names are single-segment Agent Skills names; a skill and command can’t share a name.
​
boolean
Skip the default README.md. facet create writes and declares an editable README.md (seeded from the name and description) by default; pass --no-readme to scaffold without it.
​
boolean
Overwrite an existing facet.json. Required in headless mode when a manifest already exists (there is no interactive confirm to fall back on).
​
boolean
Emit a structured result: the created facet’s name, version, target directory, and the list of files written (headless mode).

​
Exit codes

​
Headless mode

Headless scaffolding requires the facet CLI v0.24.0 or newer. On older CLIs only the interactive wizard is available; update with facet self-update.
Pass any authoring flag and facet create skips the interactive wizard and scaffolds directly — the path AI agents and scripts should use. See facet instructions authoring. After scaffolding, validate with facet build --verify, or make further changes with facet modify.

​
Wizard flow

  1. Name — the facet identity. Either an unscoped name (my-facet) or a scoped name (@scope/name, e.g. @acme/my-facet). See the Manifest Schema for the full name grammar.
  2. Description — a brief description of the facet.
  3. Version — defaults to 0.0.0.
  4. Privacy — choose Public (the default) or Private.
  5. Assets — add skills, agents, and commands by name.
  6. README — enabled by default. The wizard seeds README.md from the name and description; open the editor to customize it, or toggle it off. Edited content is preserved even if you change the name or description later.
  7. Confirmation — review the summary — which lists README.md when enabled — and confirm.

​
Generated files

On confirmation, the wizard writes:
  • facet.json — the manifest with named asset descriptors (and README.md in top-level files when README is enabled)
  • README.md — editable README, written and declared by default (skip with --no-readme)
  • skills/<name>/SKILL.md — starter skill template (Agent Skills directory convention)
  • agents/<name>.md — starter agent template
  • commands/<name>.md — starter command template
Content files are markdown. A primary asset file (skill, agent, command) carries no YAML front matter — asset metadata lives in the manifest. README.md and other supplementary files are written verbatim. After creating the project, use facet edit to iterate on your facet, or facet build to validate and package it.