Create Your First Facet

By the end of this guide you will have a working .facet file ready to publish or share. Make sure you have the CLI installed first — see Setup & Prerequisites. Scaffold a facet in one command. Pass the assets you want and the CLI writes the manifest plus a starter file for each:

facet create my-facet \
  --name my-facet --description "My first facet" \
  --skill code-review --agent reviewer --command review-pr

Prefer a guided setup? Run facet create my-facet with no flags for an interactive wizard. See facet create.

That gives you:

my-facet/
├── facet.json
├── README.md
├── skills/code-review/SKILL.md
├── agents/reviewer.md
└── commands/review-pr.md

Each asset type has a conventional path: skills at skills/<name>/SKILL.md, agents at agents/<name>.md, commands at commands/<name>.md. Asset names are single-segment Agent Skills names (lowercase ASCII, digits, and hyphens; no slashes), even when the facet identity is scoped (@scope/name); skills and commands share one namespace and can’t reuse a name. facet create also writes an editable README.md by default and declares it in the manifest’s top-level files — pass --no-readme to skip it.

Understand the manifest

facet.json is the source of truth for what the facet contains:

{
  "name": "my-facet",
  "version": "0.0.0",
  "description": "My first facet",
  "skills":   { "code-review": { "description": "A Code Review skill" } },
  "agents":   { "reviewer":    { "description": "A Reviewer agent" } },
  "commands": { "review-pr":   { "description": "A Review Pr command" } },
  "files":    ["README.md"]
}

Each asset type is a map of name to descriptor. A descriptor needs a description and may carry optional adapters metadata. The name maps to the file at its conventional path. At least one asset is required. The full schema and name grammar live in the manifest specification.

Ship supporting files

The top-level files array declares supplementary files — non-asset files like README.md, LICENSE, or design notes. They ship inside the archive and are integrity-protected, but never materialize on disk at install. A skill can also declare files of its own — companion files (references, scripts, templates) that install and remove atomically with the skill:

{
  "skills": {
    "code-review": {
      "description": "A Code Review skill",
      "files": ["references/style-guide.md", "scripts/lint.ts"]
    }
  },
  "files": ["README.md", "LICENSE"]
}

Declare exact paths only (no globs). Top-level paths can’t point under skills/, and a skill’s files are relative to its own directory and can’t list SKILL.md. Supplementary bytes ship verbatim — binary and empty files are fine, and front matter is never parsed.You rarely hand-edit facet.json for routine changes — facet modify does it for you:

facet modify skill code-review --description "Guidelines for reviewing code"
facet modify facet --version 0.1.0

Write your content

Open each starter file and replace the template with your content. The files are plain markdown. Asset metadata lives in the manifest, not the file, so a primary asset file MUST NOT carry YAML front matter — set description and adapter config with facet modify instead.skills/code-review/SKILL.md — a skill provides reusable guidelines, following the Agent Skills specification:

# Code Review

- Check new files are in the right directory and imports are tidy.
- Look for off-by-one errors, unawaited async, and missing error handling.
- Every new function needs a test; cover edge cases (empty, null, boundaries).

agents/reviewer.md — an agent’s content is its system prompt:

You are a code reviewer. Review changes for correctness, style, and
maintainability. Distinguish blocking issues from suggestions, and when
you find a bug, explain why and suggest a fix.

commands/review-pr.md — a command is a user-invokable workflow:

Review the current pull request: read the diff against the base branch,
check each changed file for logic errors, missing error handling, and
untested paths, then summarize findings as "blocking" or "suggestion".

Adapter-specific settings (tool lists, model preferences, permissions) live in the manifest, not the content file.Set them with facet modify:

facet modify agent reviewer --adapter-opencode '{"tools":{"grep":true,"bash":true}}'

Verify, then build

Check that the manifest and every asset are valid — without producing an artifact — using --verify:

facet build --verify

When it passes, build the distributable .facet:

facet build

On success the archive lands in dist/:

dist/
└── my-facet-0.0.0.facet

A scoped identity renders as a nested path: @acme/my-facet at 0.0.0 writes to dist/@acme/my-facet-0.0.0.facet. The .facet file is the single distributable artifact; pass --emit-manifest to also write a loose build-manifest.json for debugging. See facet build.

Keep editing

Two ways to change a facet after scaffolding:

facet modify — scriptable, one change per command. Add, remove, rename, or re-describe assets, set adapter config, or update facet metadata. This is the fastest path (and what agents use).
facet edit — an interactive workbench that also reconciles drift between facet.json and files you added, renamed, or removed on disk, adopts skill companions and root files like LICENSE, and has a dedicated panel for authoring README.md.

Whichever you use, finish with facet build --verify to confirm the facet still builds.

Agent Facets

Guides

Asset Types

Create Your First Facet

Scaffold a new facet

Understand the manifest

Ship supporting files

Write your content

Verify, then build

Keep editing

​Scaffold a new facet

​Understand the manifest

​Ship supporting files

​Write your content

​Verify, then build

​Keep editing

Scaffold a new facet

Understand the manifest

Ship supporting files

Write your content

Verify, then build

Keep editing