comet skill

comet skill is a low-level Skill package and Skill Engine Run tool. It discovers explicit Skill directories, project overwrites under .comet/skills/, and built-in skills, and provides local Skill package management and advanced runtime debugging. When creating reusable skills, it is preferred to use /comet-any]. comet skill run/comet skill continue are more suitable for debugging advanced Skill runs

If you only want to put a local Skill into the project, start with comet skill add and comet skill show. Running, restoring, and runtime checks are advanced debugging capabilities, mainly for Engine-enabled skills.

First, distinguish between platform skills and project skills

** Platform Skill** : Installed from comet init or comet update to platform directories such as .claude/skills/ and .agents/skills/, and directly discovered by the Agent platform.
** Project Skill** : Installed from comet skill add to .comet/skills/<name>/, resolved by name by Comet Engine, and will not automatically become platform commands.

They solve different problems. In day-to-day /comet usage, project Skill management is rarely needed. These commands are mainly for installing a custom Engine Skill, overriding a built-in Skill, or debugging an Engine Run.

Common paths

Objective	Command	Explanation
Install the local Skill	`comet skill add ./my-skill --project .`	Copy to the project Skill pool
View the source and content of the Skill	`comet skill show my-skill --project .`	Confirm which Skill is being loaded
Debug Engine Run once	`comet skill run my-skill --change ./changes/demo`	Advanced debugging is not an ordinary creation entry
Continue pending action	`comet skill continue ...`	Submit the result or resume Run
Check runtime checks	`comet skill check ...`	A runtime check that only examines a specific Run

Subcommand

Command	Purpose
`comet skill add <path>`	Install the local Skill to the project Skill pool
`comet skill show <skill>`	View the content, source and metadata of the Skill
`comet skill run <skill>`	Start the advanced Skill run
`comet skill continue`	Submit the result of the pending action or resume the Run
`comet skill check`	Check the runtime checks of the current Run

All subcommands support --json.

General Options

Options	Explanation	Applicable command
`--project <dir>`	Project root directory (default: `.`)	All
`--json`	Output structured JSON	All
`--overwrite`	Overwrite the existing project Skill	`add`
`--change <dir>`	Bind the OpenSpec change directory (mutually exclusive with `--run-id`)	`run`、`continue`、`check`
`--run-id <id>`	Store Run state with `.comet/runs/<run-id>` (mutually exclusive with `--change`)	`run`、`continue`、`check`
`--confirm <ref>`	Confirm a guardrail-protected action; can be passed multiple times. When `run` prints `User confirmation required for: <ref>`, re-run with the corresponding ref	`run`、`continue`
`--status <succeeded\|failed>`	Submit the result status of the action	`continue`
`--summary <text>`	Result summary (Required when `--status`)	`continue`
`--artifact <key=value>`	Submit artifact (used when `--status`)	`continue`
`--state <key=value>`	Submit state (used when `--status`)	`continue`
`--upgrade <skill>`	Upgrade the current Run with the new Skill version	`continue`
`--scope <progress\|step\|completion>`	runtime check range (default: `progress`)	`check`

—change and —run-id are mutually exclusive: only one of them can be bound at a Run. —change bind to the OpenSpec change directory, —run-id use .comet/runs/< run-id> stores an independent Run state.

Package management

add

comet skill add ./my-skill --project .
comet skill add ./my-skill --project . --overwrite

Copy the Skill to .comet/skills/<name> (reject symbolic links and use atomic rename with a backup). The project Skill will override the built-in Skill by name. Invalid overwrite will fail closed, directly report an error and prohibit silent rollback to the built-in version.

show

comet skill show my-skill --project .

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

Skill discovery sequence

Skill resolution searches in the following order. Stop once found:

explicit -Selector points to an existing directory and loads directly. If the path does not exist, an error will be reported and the search will not continue.
project - <projectRoot>/.comet/skills/<selector>, ** takes precedence over built-in **, so the project can override the built-in Skill by name.
builtin — assets/skills/<selector>。
None of them were found → fail closed, no silent rollback.

The bare name must match ^[A-Za-z0-9][A-Za-z0-9._-]*$. When a project Skill overrides a built-in Skill by name, an invalid project Skill will fail directly and be prohibited from falling back. This can prevent silent downgrading when the custom version is invalid.

”Run Lifecycle”

run: Start

# Bind the OpenSpec change directory
comet skill run my-skill --change ./changes/demo

# Or use an independent run-id
comet skill run my-skill --run-id demo-run --project .

Do these things when starting up

Reject the adaptive package (currently).
Reject existing runs (in change mode, there can only be one Run per directory).
** Create an immutable snapshot ** - Freeze the entire Skill package to .comet/skill-snapshots/<hash>/ and hash lock it to Run’s skillHash.
Initialize the Run state: currentStep = entry, status = running.
Record the run_started trajectory event.
The engine parses entry step, constructs the first action, passes guardrails, writes pending action, status = waiting.

continue: Submit the result or restore

With 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 "Completed"

Without outcome (view/redecide)

comet skill continue --change ./changes/demo

Upgrade the current Run to the new Skill version:

comet skill continue --change ./changes/demo --upgrade my-skill --project .

Upgrades are strictly guarded: there cannot be pending actions, Skill names must match, orchestration patterns must match, and the current step must still exist in the new version. After the upgrade, record the state_migrated event.

—upgrade cannot be combined - status, - summary, - artifact, - state are used in combination. - summary, - artifact, - state must be used in conjunction with - status.

check: Check as needed

comet skill check --change ./changes/demo --scope completion

comet skill check --run-id demo-run --project . --scope completion

--scope can be selected as progress, step or completion (default is progress). Read the runtime checks of comet/checks.yaml.

comet skill check only checks the completion degree of a certain Skill run and is not a general Skill assessment. To evaluate the capability of a Skill product, please use comet eval. For details, please refer to Runtime check.

Run state store

Run state is machine-owned. ** Do not edit manually **. Only run_id will be mirrored to .comet.yaml.

runnerMode	Storage location	Features
`change`	`<changeDir>/.comet/`	Bind the OpenSpec change directory, with one Run for each directory
`standalone`	`<projectRoot>/.comet/runs/<runId>/`	Independent Run, addressed by runId, multiple runs coexist

Attached files (all in the change/run directory) :

“File	”Content
`.comet/run-state.json`	Run state (currentStep, pending, status, etc.)
`.comet/pending-action.json`	The pending action currently waiting
`.comet/trajectory.jsonl`	append-only trajectory audit record
`.comet/context.md`	Current Agent context
`.comet/artifacts.json`	The mapping of the produced artifacts

All file I/O operations are sandboxed within the “change/run” directory, and absolute paths, ~, drive letters, and .. path traversals are rejected. The write is atomic (write to tmp and then rename).

Text mode recovery prompt

In text mode, comet skill prints Pending action and Next: so you can see what to do after a paused Run or failed eval. For example, run outputs:

Run: demo-run
Status: paused
Current step: collect-evidence
Pending action: 4f3a9c1d7e2b8056 (tool, step collect-evidence)
Runtime checks: 1
Next: complete the pending action, then run comet skill continue

When check fails, it will prompt:

Next: record the missing artifact/state and rerun comet skill check

Next step

Skill and Engine (Advanced) - Understand the semantics of Skill packages and Skill Run (Engine Run), pending action, immutable snapshots
Runtime check - Distinguish between comet skill check and comet eval
Overview of Skill Creator - The main entry point for Creating Reusable Skills

Install and health checks

Skills, evals, and publishing

Core scripts

First, distinguish between platform skills and project skills

Common paths

Subcommand

General Options

Package management

add

show

Skill discovery sequence

”Run Lifecycle”

run: Start

continue: Submit the result or restore

check: Check as needed

Run state store

Text mode recovery prompt

Next step

​First, distinguish between platform skills and project skills

​Common paths

​Subcommand

​General Options

​Package management

​add

​show

​Skill discovery sequence

​”Run Lifecycle”

​run: Start

​continue: Submit the result or restore

​check: Check as needed

​Run state store

​Text mode recovery prompt

​Next step

First, distinguish between platform skills and project skills

Common paths

Subcommand

General Options

Package management

add

show

Skill discovery sequence

”Run Lifecycle”

run: Start

continue: Submit the result or restore

check: Check as needed

Run state store

Text mode recovery prompt

Next step