> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentfacets.io/llms.txt
> Use this file to discover all available pages before exploring further.

# facet create

> Scaffolds a new facet project

## Usage

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
facet create [directory] [--force]
```

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](#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

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
facet create                       # interactive wizard in the current directory
facet create ./my-facet \
  --name my-facet \
  --description "What it does" \
  --version 0.1.0 \
  --skill greet --agent helper --command run \
  --json                           # headless scaffold, machine-readable result
facet create ./bare --name bare --skill greet --no-readme  # skip the default README
```

## Flags

<ResponseField name="--name" type="string" required>
  Facet name; required in headless mode. An unscoped slug or a scoped `@scope/name` — see the [name grammar](/specification/manifest#facet-name-grammar).
</ResponseField>

<ResponseField name="--description" type="string">
  Facet description (headless mode).
</ResponseField>

<ResponseField name="--version" type="semver">
  Facet version (headless mode). Defaults to `0.0.0`; must be semver.
</ResponseField>

<ResponseField name="--private" type="boolean">
  Mark the facet private (`private: true`).
</ResponseField>

<ResponseField name="--skill / --agent / --command" type="repeatable">
  An asset to scaffold. Repeat per asset; at least one is required in headless mode. Asset names are single-segment [Agent Skills names](/specification/manifest#asset-names); a skill and command can't share a name.
</ResponseField>

<ResponseField name="--no-readme" type="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.
</ResponseField>

<ResponseField name="--force" type="boolean">
  Overwrite an existing `facet.json`. Required in headless mode when a manifest already exists (there is no interactive confirm to fall back on).
</ResponseField>

<ResponseField name="--json" type="boolean">
  Emit a structured result: the created facet's name, version, target directory, and the list of files written (headless mode).
</ResponseField>

## Exit codes

| Code | Meaning                                         |
| ---- | ----------------------------------------------- |
| `0`  | Facet created successfully                      |
| `1`  | Cancelled, declined overwrite, or invalid input |

## Headless mode

<Note>
  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`](/cli/self-update).
</Note>

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`](/cli/instructions).

After scaffolding, validate with [`facet build --verify`](/cli/authoring/build), or make further changes with [`facet modify`](/cli/authoring/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](/specification/manifest#facet-name-grammar) 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](/specification/manifest#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.