Skip to main content
comet skill is the low-level Skill package and Skill run (Engine Run) tool. It discovers explicit Skill directories, project overrides under .comet/skills/, and built-in Skills, and provides local Skill package management plus advanced run debugging. For regular users creating reusable Skills, prefer /comet-any. comet skill run / comet skill continue are better suited for debugging advanced Skill runs.

​
Subcommands

All subcommands support --json.

​
Common options

—change and —run-id are mutually exclusive: a single Run can only bind to one of them. —change binds to an OpenSpec change directory, while —run-id stores independent Run state in .comet/runs/<run-id>.

​
Package management

​
add

Copies the Skill to .comet/skills/<name> (symbolic links are rejected; an atomic rename with backup is used). Project Skills override built-in Skills by name; invalid overrides fail closed (error directly, instead of silently falling back to the built-in).

​
show

Parses the Skill and returns the name, version, source, root directory, content hash, steps, guardrails, and runtime checks.

​
Skill discovery order

resolveSkill looks in the following order and stops at the first match:
  1. explicit — the selector points to an existing directory and is loaded directly. A non-existent path errors out and does not continue searching.
  2. project — <projectRoot>/.comet/skills/<selector>, takes precedence over built-in, so a project can override a built-in Skill by name.
  3. builtin — assets/skills/<selector>.
  4. None found → fail closed, no silent fallback.
A bare name must match ^[A-Za-z0-9][A-Za-z0-9._-]*$. When a project Skill overrides a built-in Skill by name and the project Skill is invalid, it fails directly instead of falling back to the built-in. This avoids the “you think you’re using your custom version but are silently using the built-in” problem.

​
Run lifecycle

​
run: starting

On startup it does the following:
  1. Rejects adaptive packages (for now).
  2. Rejects an already-existing Run (in change mode, a directory can only have one Run).
  3. Creates an immutable snapshot — freezes the entire Skill package into .comet/skill-snapshots/<hash>/, with the hash locked to the Run’s skillHash.
  4. Initializes Run state: currentStep = entry, status = running.
  5. Records a run_started trajectory event.
  6. decide resolves the entry step, constructs the first action, runs it through guardrails, writes the pending action, and sets status = waiting.

​
continue: submit an outcome or resume

With an outcome (actual progress):
Without an outcome (inspect / re-decide):
Upgrade the current Run to a new Skill version:
Upgrades have strict guards: there must be no pending action, the Skill name must match, the orchestration mode must match, and the current step must still exist in the new version. After an upgrade, a state_migrated event is recorded.
—upgrade cannot be combined with —status, —summary, —artifact, or —state. —summary, —artifact, and —state must be used together with —status.

​
check: on-demand check

--scope can be progress, step, or completion (default progress). It reads the runtime checks from comet/checks.yaml.
comet skill check only checks the completeness of a single Skill run, not a general Skill evaluation. To evaluate a Skill’s product capability, use comet eval. See Runtime check.

​
Run state storage

Run state is machine-owned — do not edit it manually. Only run_id is mirrored into .comet.yaml. Associated files (all within the change/run directory): All file IO is sandboxed within the change/run directory, rejecting absolute paths, ~, drive letters, and .. path traversal. Writes are atomic (write to tmp then rename).

​
Recovery hints in text mode

In text mode, comet skill prints Pending action and Next: recovery hints directly, so you don’t have to guess the next step yourself after a paused Run or a failed eval. For example, run output:
When check fails, it suggests:

​
Next steps

Last modified on July 2, 2026