Skip to main content

​
Usage

Applies one change to facet.json and its text-asset files, then exits. This is the scriptable counterpart to facet edit, and the path agents should use. <target> is skill, agent, command, or facet. There is no server target: MCP server declarations are edited in facet.json directly. [directory] defaults to the current directory and must contain a facet.json.
Requires v0.24.0 or newer.

​
Examples

​
Flags

​
boolean
Add a new text asset: manifest entry plus a scaffolded starter file.
​
boolean
Remove a text asset: manifest entry plus its file.
​
string
Rename a text asset to the given name.
​
string
Set the text asset’s or facet’s description.
​
JSON object
Set a text asset’s config for the named adapter, replacing that block.
​
boolean
Remove a text asset’s config for the named adapter.
​
facet target only
Set facet-level metadata.
​
boolean
Emit a machine-readable change summary.

​
Exit codes

​
Details

​
Changing an asset

For the text-asset targets, pass the asset name and at most one lifecycle action, optionally with field changes. --add creates the manifest descriptor and scaffolds the starter file at its conventional path. --rename renames the manifest key and moves the primary file, removing a now-empty skill directory. --remove drops the descriptor and deletes the file.
facet modify operates on text-asset primaries. To adopt, move, or reconcile a skill’s companion files or top-level supplementary files, use facet edit.

​
Adapter configuration

Each text-asset descriptor may carry an adapters block: a map of adapter name to a config object the CLI passes to that adapter. Set one with a name-embedded flag whose value is a JSON object. The whole suffix after --adapter- is the adapter name, so hyphenated names such as claude-code work:
Setting an adapter replaces that adapter’s block wholesale. Remove one with --remove-adapter-<name>:
Adapter flags may accompany --add or --rename, or stand alone. Hand-edits to the adapters object round-trip safely, because unknown descriptor fields are preserved.

​
Facet metadata

The facet target takes no text-asset name and sets facet-level fields. Pass at least one of --name, --description, --version, or --private.

​
What you cannot combine

  • Exactly one lifecycle action per call. Combining --add, --remove, and --rename is an error.
  • --description and adapter flags may ride along with --add or --rename, or stand alone. --remove takes no field flags.
  • Text-asset flags are not valid for the facet target, and facet-metadata flags are not valid for text-asset targets.
After every change the resulting manifest is re-validated before anything is written.

​
Troubleshooting

Cause: --add names a text asset the manifest already declares, or another action names one it does not.Fix: check the current names with facet build --verify or by reading facet.json, then re-run against the right name.
Cause: the new name is already taken in that text asset’s namespace. Skills and commands share one namespace, so a skill cannot take a command’s name.Fix: choose a free name, or remove the existing text asset first.
Cause: facet modify facet was called with no metadata flag, so there is nothing to set.Fix: pass at least one of --name, --description, --version, or --private.
Cause: the result fails manifest validation, for example removing the last asset, or setting a name that breaks the name grammar.Fix: the error names the offending field. Nothing was written, so correct the invocation and re-run.

​
See also