Skip to main content

​
Usage

Requires the facet CLI v0.24.0 or newer. If facet modify reports “Unknown command”, update with facet self-update.
facet modify is the headless, flag-driven counterpart to the interactive facet edit wizard. It applies one change to a facet’s facet.json (and its asset files) and exits — the path AI agents and scripts should use for authoring. See facet instructions authoring. <target> is one of skill, agent, command, or facet. [directory] defaults to the current directory and must contain a facet.json.

​
Flags

​
boolean
Add a new asset (scaffold + manifest entry).
​
boolean
Remove an asset (delete file + manifest entry).
​
string
Rename an asset to the given name.
​
string
Set the asset’s (or facet’s) description.
​
JSON object
Set an asset’s config for the named adapter (replaces the block).
​
boolean
Remove an asset’s config for the named adapter.
​
facet target only
Set facet-level metadata (facet modify facet ...).
​
boolean
Emit a machine-readable change summary.

​
Exit codes

​
Editing an asset

For the asset targets (skill, agent, command), pass the asset name and at most one lifecycle action, optionally with field changes.

​
Add an asset

Creates the manifest descriptor and scaffolds the starter file (skills/<name>/SKILL.md, agents/<name>.md, or commands/<name>.md). May carry a description and adapter config in the same call.

​
Change a description

​
Rename an asset

Renames the manifest key and moves the asset’s file (removing the now-empty skill directory, for skills).

​
Remove an asset

Removes the manifest descriptor and deletes the asset’s file.

​
Adapter configuration

Each asset descriptor may carry an adapters block: a map of adapter name to a free-form config object that the CLI passes through to that adapter at install time. 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 like 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. You can also hand-edit the adapters object in facet.json directly; edits round-trip safely because the CLI preserves unknown descriptor fields.

​
Editing facet metadata

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

​
Validation

After every mutation the resulting manifest is re-validated before anything is written. A change that would make facet.json invalid (for example, removing the only asset) is rejected and nothing is written.

​
Rules

  • Exactly one lifecycle action per call: --add, --remove, or --rename. Combining them is an error.
  • --description and adapter flags may ride along with --add or --rename, or stand alone as an update. --remove takes no field flags.
  • Asset flags (--add/--remove/--rename) are not valid for the facet target, and facet-metadata flags (--name/--version/--private) are not valid for asset targets.