Skip to main content

​
Usage

Opens an interactive editor for the facet in the specified directory (defaults to the current directory). The edit command is the full authoring workbench — everything facet create can do, plus automatic reconciliation of disk state versus the manifest.
facet edit is interactive (TTY only). For scripted or agent-driven edits, use facet modify — the headless, flag-driven counterpart.

​
Exit codes

​
What it does

The edit command has two phases:

​
Reconciliation

If the edit command detects drift between the manifest and the files on disk, it enters a reconciliation phase first. Drift includes:
  • New assets on disk not tracked in the manifest — choose “Add to manifest” or “Ignore for now”
  • Undeclared files inside a declared skill directory — adopt them into that skill’s companion files, or ignore
  • Common root files like LICENSE — adopt them into the top-level files, or ignore
  • Missing files declared in the manifest but absent from disk — choose “Scaffold template” or “Remove from manifest” (at the exact declared path, for both assets and supplementary files)
README.md and the extensionless README are handled by their own README panel, not generic reconciliation, so they never appear twice. Ignored files stay on disk and undeclared. All reconciliation items must be resolved before proceeding to editing.

​
Editing

After reconciliation (or immediately if no drift), the edit phase allows:
  • Identity editing — modify the facet name, description, and version
  • Privacy editing — inspect the facet’s current visibility intent without opening facet.json, and switch between Public and Private.
  • Asset management — add, remove, or rename skills, agents, and commands. Deleting a skill removes its declared companion files too, while any files you added to the skill directory yourself are preserved.
  • Description editing — press Enter on an asset to edit its name, or press ↓ during name editing to open the description in your terminal editor ($VISUAL / $EDITOR / vi)
A primary asset file carries no YAML front matter — asset metadata lives in the manifest, and edit writes confirmed content without front matter. All changes are transactional — nothing is written to disk until you review and confirm on the confirmation page. Exit at any point with Esc Esc to discard all changes.

​
README panel

Both conventional README paths — README.md and the extensionless README — get a dedicated panel, managed independently. The actions offered depend on each path’s current state: Adopt preserves the existing bytes unless you explicitly edit them. Every README operation is queued until Apply, like all other edits.

​
Confirmation

Before applying, a summary shows the final state of your facet — identity fields, the privacy intent, and all assets with their descriptions — along with a reminder that a privacy change is embedded at build time (rebuild to apply it, and bump the version if it was already published). Choose “Apply” to write changes or “Go back” to continue editing. The confirmation lists every queued file operation with its exact path. On apply, the edit command transactionally:
  • Writes the updated facet.json
  • Scaffolds template files for new assets
  • Deletes files for removed assets (and a removed skill’s declared companions)
  • Writes or deletes README files per the README panel choices
  • Scaffolds or removes reconciled supplementary files

​
See also