Install Facets in Your Project

Bring facets into a project in two moves: connect an adapter for your AI tool, then add the facets you want. This guide walks the whole loop — add, list, reinstall, and remove.

Connect an adapter

An adapter is the bridge between facets and your AI coding tool — it tells the CLI where to place assets on disk so your tool can find them. You need at least one before adding facets.

facet adapter install claude-code

The first-party adapters are claude-code, opencode, and codex. Run facet adapter install with no name for an interactive picker, or pass a name to install it directly. Third-party adapters install the same way from an npm package, git URL, or local path.

If you skip this step, facet add and facet install will launch the adapter picker for you on first use.

Search the registry (optional)

facet search viper # as an example

facet search lists matching facets with their latest version, author, and asset counts. Run it with no term to browse everything published.

Add it

facet add viper-plans

facet add brings a facet into your project in one step: it writes the entry to facets.json and runs the install pipeline. There is no separate “install after add”.The registry is the default source (hosted at agentfacets.io) — a bare name resolves to the latest published version. You can also pin a version, use a wildcard, or point at other sources.

Show facet add version examples

facet add sources

facet add viper-plans                       # latest from the registry
facet add viper-plans@1.2.3                 # exact version
facet add viper-plans@1.*                   # latest 1.x
facet add @acme/deploy-tools                # scoped registry facet
facet add github:owner/repo#main            # a GitHub repo at a ref
facet add ./local-facets/my-plans           # a local directory
facet add viper-plans rezi planner@2.*      # several at once

A bare name is pinned to its resolved version in facets.json; a wildcard like 1.* is preserved there, with the specific version recorded in the lockfile. See facet add for the full source grammar.

Your project now has two version-controlled files — commit both so teammates and CI resolve identical versions. (A third, the machine-local install receipt, lives outside your project and is not committed.)facets.json — the project manifest: which facets belong to the project, at what version, and how you want their assets named. It is the source of truth for your dependencies.facets.lock — the lockfile: exact resolved versions, , and per-file asset records for reproducible installs. It is managed by the CLI; you never hand-edit it.

{
  "manifestVersion": 0.1,
  "facets": {
    "cowsay": "1.*",
    "viper-plans": "1.0.0"
  }
}

{
  "lockfileVersion": 0.3,
  "facets": {
    "cowsay": {
      "source": { "kind": "registry", "registry": "https://api.agentfacets.io" },
      "version": "1.0.0",
      "integrity": "sha256:70fe8f9f0ba1…",
      "assets": [
        {
          "scope": "project", "type": "skill", "name": "cowsay-rules",
          "materialization": { "kind": "authored" },
          "files": [
            { "path": "skills/cowsay-rules/SKILL.md", "integrity": "sha256:11aa22…" },
            { "path": "skills/cowsay-rules/references/moods.md", "integrity": "sha256:22bb33…" }
          ]
        },
        { "scope": "project", "type": "agent", "name": "cowsay",
          "materialization": { "kind": "authored" },
          "files": [{ "path": "agents/cowsay.md", "integrity": "sha256:33cc44…" }] },
        { "scope": "project", "type": "command", "name": "cowchat",
          "materialization": { "kind": "authored" },
          "files": [{ "path": "commands/cowchat.md", "integrity": "sha256:44dd55…" }] },
        { "scope": "project", "type": "command", "name": "cowsay",
          "materialization": { "kind": "authored" },
          "files": [{ "path": "commands/cowsay.md", "integrity": "sha256:55ee66…" }] }
      ]
    }
  }
}

The full schema — every field, the tagged source kinds, and the exact-version rules — is specified in Lockfile.Note this facet ships an agent cowsay and a command cowsay. That is legal: skills and commands share one namespace, and agents have their own. What is not legal is two facets claiming the same name in the same namespace — see Two facets, one name.

The lockfile honors the manifest. A pinned entry is reused as long as it still satisfies facets.json; when you bump a version or widen a wildcard, facet install re-resolves and updates the lock.

Where assets land

facet add writes each materialized asset into every connected adapter’s project-local directory, so your tool picks them up immediately. With the opencode adapter, adding cowsay writes:

.opencode/
├── skills/cowsay-rules/SKILL.md
├── skills/cowsay-rules/references/moods.md
├── agents/cowsay.md
├── commands/cowsay.md
└── commands/cowchat.md

A skill’s companion files land beside its SKILL.md, and a skill installs and removes as one atomic bundle. Archive-only files — a facet’s top-level README.md or LICENSE — ship in the archive but are never written into your adapters. Other adapters use their own conventional location (Claude Code under .claude/, and so on). These files are project-scoped — the same scope you see in the lockfile — so they belong to the checkout, not your machine. facet remove deletes them again — including a skill’s owned companions, while preserving any files you added into a skill directory yourself — and facet install recreates them from the lockfile after a clone. Deletion is driven by your machine’s install receipt: files this machine never installed are left in place rather than removed on the lockfile’s word.Sooner or later two facets will publish an asset with the same name. Facets cannot know about each other, so your project decides.Adding a second facet whose skill is also called planning pauses the install:

Installation is paused: two or more facets want the same name.
1 group · 1 still to resolve · nothing has been written yet

  project skills and commands — "planning"
    ✕ unresolved   viper-plans  skill planning
    ✕ unresolved   team-tools   skill planning

Press Enter on the group to open it, then give each one an outcome:

Keep — leave it under the published name.
Alias — type a different name for it.
Omit — do not install it at all.

Move with ↑↓, highlight a choice with ←→, and press Enter to apply it. They only have to differ from each other, so aliasing one of them is enough. Once every group shows ✓ resolved, confirm and the install continues.Your decision is saved to facets.json, so it happens once:

facets.json

{
  "manifestVersion": 0.1,
  "facets": {
    "viper-plans": "1.0.0",
    "team-tools": {
      "source": "1.*",
      "materialization": {
        "skills": { "planning": { "kind": "aliased", "as": "team-planning" } }
      }
    }
  }
}

Both skills now install, and your teammates get the same layout from the same manifest:

.opencode/skills/planning/SKILL.md
.opencode/skills/team-planning/SKILL.md

Aliasing renames the file, not the facet. team-tools is still team-tools, its published skill is still planning, and every integrity hash is unchanged — which is why an alias can never smuggle different content in under a familiar name. See Materialization.

CI cannot prompt. If a collision reaches an automated run, the install fails and prints every claimant with the exact facets.json edit to make. Resolve collisions locally and commit facets.json so CI never sees one.

Reinstall after a git clone

When you clone a project that already has facets.json and facets.lock, materialize into your adapters with:

facet install

facet install fetches and installs every declared facet at the exact versions in the lockfile — so you get precisely what is pinned.

For CI, add --frozen-lockfile. It never re-resolves or writes the lockfile and fails if facets.json and facets.lock disagree — catching a forgotten facet add or a hand-edited manifest instead of silently mutating the lock. That includes disagreement about asset names: a recorded alias you changed by hand but never installed is drift, exactly like a changed version. Frozen mode also never prompts, so an unresolved name collision fails rather than waiting for input.

Manage what’s installed

See what’s declared:

facet list

facet list shows every facet in facets.json with its resolved version (from the lockfile), or its source specifier if it hasn’t been installed yet.Move to a newer version:

facet add viper-plans@2.0.0    # re-add at the new version

Re-adding at a new version updates both facets.json and the lockfile. A dedicated facet upgrade command is on the roadmap; its page documents the manual paths until it ships.Remove a facet:

facet remove viper-plans          # aliased: facet rm
facet remove viper-plans rezi     # several at once, in one transaction

facet remove takes a facet out of facets.json, deletes the assets it still owns from every connected adapter, and rewrites the lockfile without it. Several removals commit together or not at all. A name that isn’t declared is ignored rather than fatal, so re-running a removal is safe and a command whose names are all already gone succeeds as a no-op.Manage adapters:

facet adapter list                # what's connected
facet adapter remove opencode     # disconnect one

See the adapter reference for details.

Agent Facets

Guides

Asset Types

Install Facets in Your Project

Connect an adapter

Find and add a facet

What `facet add` writes

Where assets land

Two facets, one name

Reinstall after a git clone

Manage what’s installed

​Connect an adapter

​Find and add a facet

​What facet add writes

​Where assets land

​Two facets, one name

​Reinstall after a git clone

​Manage what’s installed

Connect an adapter

Find and add a facet

What `facet add` writes

Where assets land

Two facets, one name

Reinstall after a git clone

Manage what’s installed