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
| Command | Purpose |
|---|
comet skill add <path> | Install a local Skill into the project Skill pool |
comet skill show <skill> | View Skill content, source, and metadata |
comet skill run <skill> | Start an advanced Skill run |
comet skill continue | Submit the outcome of a pending action or resume a Run |
comet skill check | Check the runtime checks of the current Run |
--json.
Common options
| Option | Description | Applicable commands |
|---|
--project <dir> | Project root directory (default .) | All |
--json | Output structured JSON | All |
--overwrite | Overwrite an existing project Skill | add |
--change <dir> | Bind an OpenSpec change directory (mutually exclusive with --run-id) | run, continue, check |
--run-id <id> | Store Run state in .comet/runs/<run-id> (mutually exclusive with --change) | run, continue, check |
--confirm <key=value> | Pass a confirmation parameter | run, continue |
--status <succeeded|failed> | Submit the action outcome status | continue |
--summary <text> | Outcome summary (required with --status) | continue |
--artifact <key=value> | Submit an artifact (used with --status) | continue |
--state <key=value> | Submit state (used with --status) | continue |
--upgrade <skill> | Upgrade the current Run to a new Skill version | continue |
--scope <progress|step|completion> | Runtime check scope (default progress) | check |
—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
comet skill add ./my-skill --project .
comet skill add ./my-skill --project . --overwrite
.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
comet skill show my-skill --project .
Skill discovery order
resolveSkill looks in the following order and stops at the first match:
- explicit — the selector points to an existing directory and is loaded directly. A non-existent path errors out and does not continue searching.
- project —
<projectRoot>/.comet/skills/<selector>, takes precedence over built-in, so a project can override a built-in Skill by name.
- builtin —
assets/skills/<selector>.
- 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
# Bind to an OpenSpec change directory
comet skill run my-skill --change ./changes/demo
# Or use a standalone run-id
comet skill run my-skill --run-id demo-run --project .
- Rejects adaptive packages (for now).
- Rejects an already-existing Run (in change mode, a directory can only have one Run).
- Creates an immutable snapshot — freezes the entire Skill package into
.comet/skill-snapshots/<hash>/, with the hash locked to the Run’s skillHash.
- Initializes Run state:
currentStep = entry, status = running.
- Records a
run_started trajectory event.
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):
comet skill continue --change ./changes/demo --status succeeded --summary "Done" --artifact report=report.md
comet skill continue --run-id demo-run --project . --status succeeded --summary "Done"
comet skill continue --change ./changes/demo
comet skill continue --change ./changes/demo --upgrade my-skill --project .
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
comet skill check --change ./changes/demo --scope completion
comet skill check --run-id demo-run --project . --scope completion
--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.
| runnerMode | Storage location | Characteristics |
|---|
change | <changeDir>/.comet/ | Bound to an OpenSpec change directory; one Run per directory |
standalone | <projectRoot>/.comet/runs/<runId>/ | Independent Run, addressed by runId; multiple Runs coexist |
| File | Contents |
|---|
.comet/run-state.json | Run state (currentStep, pending, status, etc.) |
.comet/pending-action.json | The currently pending action |
.comet/trajectory.jsonl | Append-only trajectory audit log |
.comet/context.md | Current Agent context |
.comet/artifacts.json | Mapping of produced artifacts |
~, 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:
Run: demo-run
Status: paused
Current step: collect-evidence
Pending action: collect-evidence (tool, step collect-evidence)
Runtime checks: 1
Next: complete the pending action, then run comet skill continue
check fails, it suggests:
Next: record the missing artifact/state and rerun comet skill check
Next steps
