Create a Facet

By the end of this guide you will have a working .facet file ready to publish or share. Install the CLI first: see Setup. 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

Run facet create my-facet with no authoring 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 text-asset type has a conventional path. Asset names are single segment: lowercase ASCII, digits, and hyphens, with no slashes. Skills and commands share one namespace, so they cannot reuse a name. See Asset names.

Understand the manifest

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

facet.json

{
  "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 text-asset type maps a name to a descriptor. A descriptor needs a description and may carry optional adapters metadata. A facet needs at least one asset, which can be an MCP server instead. The full schema lives in the manifest specification.

Ship supporting files

The top-level files array declares supplementary files such as README.md or LICENSE. They ship in the archive and are integrity-protected, but never install onto disk. A skill can declare its own files, which install and remove with it:

facet.json

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

Declare exact paths, not globs. Top-level paths cannot point under skills/, and a skill’s paths are relative to its own directory and cannot list SKILL.md. Binary and empty files are fine.For routine manifest changes, use facet modify:

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

Write your content

Replace each starter file with your own markdown.skills/code-review/SKILL.md holds 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 empty, null, and boundary cases.

agents/reviewer.md is the agent’s 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 is a workflow the user invokes:

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".

Asset identity lives in the manifest. A primary file may carry YAML front matter, which ships verbatim, but at install time the manifest’s name and description are merged over it. Set metadata with facet modify rather than in front matter.

Adapter-specific settings such as tool lists or model preferences also live in the manifest:

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

Verify, then build

Validate without producing an artifact:

facet build --verify

When it passes, build the distributable archive:

facet build

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

A scoped identity nests: @acme/my-facet writes to dist/@acme/my-facet-0.0.0.facet. See facet build.

Keep editing

facet modify makes one scriptable change at a time. This is the fastest path.
facet edit is an interactive workbench that also reconciles facet.json with files you added, renamed, or removed on disk.

Finish with facet build --verify to confirm the facet still builds.

Agent Facets

Guides

Concepts

Adapter Development

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