comet skill

comet skill 是低层 Skill 包和 Skill 运行（Engine Run）工具。它发现显式 Skill 目录、.comet/skills/ 下的项目覆盖和内置 Skill，并提供本地 Skill 包管理和高级运行调试。创建可复用 Skill 时优先用 /comet-any。comet skill run / comet skill continue 更适合调试高级 Skill 运行。

如果你只想把本地 Skill 放进项目，先用 comet skill add 和 comet skill show。运行、恢复和 runtime check 是高级调试能力，主要面向 Engine-enabled Skill。

先区分平台 Skill 与项目 Skill

平台 Skill：由 comet init 或 comet update 安装到 .claude/skills/、.agents/skills/ 等平台目录，由 Agent 平台直接发现。
项目 Skill：由 comet skill add 安装到 .comet/skills/<name>/，由 Comet Engine 按名称解析，不会自动变成平台命令。

两者解决的问题不同。日常使用 /comet 时大多不需要管理项目 Skill。只有安装自定义 Engine Skill、覆盖内置 Skill 或调试 Engine Run 时，才需要本页命令。

常用路径

目标	命令	说明
安装本地 Skill	`comet skill add ./my-skill --project .`	复制到项目 Skill 池
查看 Skill 来源和内容	`comet skill show my-skill --project .`	确认加载的是哪个 Skill
调试一次 Engine Run	`comet skill run my-skill --change ./changes/demo`	高级调试，不是普通创建入口
继续 pending action	`comet skill continue ...`	提交结果或恢复 Run
检查 runtime checks	`comet skill check ...`	只检查某次 Run 的运行期检查

子命令

命令	用途
`comet skill add <path>`	安装本地 Skill 到项目 Skill 池
`comet skill show <skill>`	查看 Skill 内容、来源和元数据
`comet skill run <skill>`	启动高级 Skill 运行
`comet skill continue`	提交 pending action 的结果或恢复 Run
`comet skill check`	检查当前 Run 的 runtime checks

所有子命令都支持 --json。

通用选项

选项	说明	适用命令
`--project <dir>`	项目根目录（默认 `.`）	所有
`--json`	输出结构化 JSON	所有
`--overwrite`	覆盖已存在的项目 Skill	`add`
`--change <dir>`	绑定 OpenSpec change 目录（与 `--run-id` 互斥）	`run`、`continue`、`check`
`--run-id <id>`	用 `.comet/runs/<run-id>` 存放 Run state（与 `--change` 互斥）	`run`、`continue`、`check`
`--confirm <ref>`	确认受 guardrail 保护的动作，可多次传入；`run` 输出 `User confirmation required for: <ref>` 时带上对应 ref 重新运行	`run`、`continue`
`--status <succeeded\|failed>`	提交 action 结果状态	`continue`
`--summary <text>`	结果摘要（`--status` 时必需）	`continue`
`--artifact <key=value>`	提交 artifact（`--status` 时使用）	`continue`
`--state <key=value>`	提交 state（`--status` 时使用）	`continue`
`--upgrade <skill>`	用新 Skill 版本升级当前 Run	`continue`
`--scope <progress\|step\|completion>`	runtime check 范围（默认 `progress`）	`check`

—change 和 —run-id 互斥：一次 Run 只能绑定其中一个。—change 绑定 OpenSpec change 目录，—run-id 用 .comet/runs/<run-id> 存放独立 Run state。

包管理

add

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

把 Skill 复制到 .comet/skills/<name>（拒绝符号链接，用原子 rename 加备份）。项目 Skill 会按名称覆盖内置 Skill。无效覆盖会 fail closed，直接报错并禁止静默回退到内置版本。

show

comet skill show my-skill --project .

解析 Skill 并返回名称、版本、来源、根目录、内容 hash、steps、guardrails 和 runtime checks。

Skill 发现顺序

Skill 解析按以下顺序查找，找到即停止：

explicit — selector 指向一个已存在的目录，直接加载。路径不存在会报错，不会继续找。
project — <projectRoot>/.comet/skills/<selector>，优先于内置，所以项目可以按名称覆盖内置 Skill。
builtin — assets/skills/<selector>。
都没找到 → fail closed，不静默回退。

bare 名字必须匹配 ^[A-Za-z0-9][A-Za-z0-9._-]*$。项目 Skill 按名称覆盖内置 Skill 时，无效的项目 Skill 会直接失败并禁止回退。这可以防止自定义版本无效时静默降级。

Run 生命周期

run：启动

# 绑定 OpenSpec change 目录
comet skill run my-skill --change ./changes/demo

# 或用独立 run-id
comet skill run my-skill --run-id demo-run --project .

启动时做这些事：

拒绝 adaptive 包（目前）。
拒绝已存在的 Run（change 模式一个目录只能有一个 Run）。
创建不可变快照。把整个 Skill 包冻结到 .comet/skill-snapshots/<hash>/，hash 锁定到 Run 的 skillHash。
初始化 Run state：currentStep = entry，status = running。
记录 run_started trajectory 事件。
引擎决策：解析 entry step、构造第一个动作、过 guardrails、写入 pending action、status = waiting。

continue：提交结果或恢复

带 outcome（实际推进）：

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 "完成"

不带 outcome（查看/重新决定）：

comet skill continue --change ./changes/demo

升级当前 Run 到新 Skill 版本：

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

升级有严格守卫：不能有 pending action、Skill 名称必须匹配、编排模式必须匹配、当前 step 必须在新版本里仍存在。升级后记录 state_migrated 事件。

—upgrade 不能和 —status、—summary、—artifact、—state 组合使用。—summary、—artifact、—state 必须配合 —status 使用。

check：按需检查

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

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

--scope 可选 progress、step 或 completion（默认 progress）。读 comet/checks.yaml 的 runtime checks。

comet skill check 只检查某次 Skill 运行的完成度，不是通用 Skill 评估。评估一个 Skill 产品能力，请用 comet eval。详见 Runtime check。

Run state 存储

Run state 由 Engine 自动维护（machine-owned），不要手工编辑。只有 run_id 会镜像到 .comet.yaml。

runnerMode	存储位置	特点
`change`	`<changeDir>/.comet/`	绑定 OpenSpec change 目录，一个目录一个 Run
`standalone`	`<projectRoot>/.comet/runs/<runId>/`	独立 Run，用 runId 寻址，多个 Run 并存

附属文件（都在 change/run 目录内）：

文件	内容
`.comet/run-state.json`	Run state（currentStep、pending、status 等）
`.comet/pending-action.json`	当前等待的 pending action
`.comet/trajectory.jsonl`	append-only 轨迹审计记录
`.comet/context.md`	当前 Agent 上下文
`.comet/artifacts.json`	产出的产物映射

所有文件 IO 都限制在 change/run 目录内，拒绝绝对路径、~、盘符和 .. 路径穿越。写入是原子的（写 tmp 再 rename）。

文本模式的恢复提示

comet skill 在文本模式下会打印 Pending action 和 Next:，说明 Run 暂停或 eval 失败后的下一步。例如 run 输出：

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

check 失败时会提示：

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

下一步

Skill 与 Engine（进阶） — 理解 Skill 包和 Skill 运行（Engine Run）的语义、pending action、不可变快照
Runtime check — 区分 comet skill check 和 comet eval
Skill Creator 概览 — 创建可复用 Skill 的主入口

安装和健康检查

Skill、评估和发布（进阶）

核心脚本

先区分平台 Skill 与项目 Skill

常用路径

子命令

通用选项

包管理

add

show

Skill 发现顺序

Run 生命周期

run：启动

continue：提交结果或恢复

check：按需检查

Run state 存储

文本模式的恢复提示

下一步

​先区分平台 Skill 与项目 Skill

​常用路径

​子命令

​通用选项

​包管理

​add

​show

​Skill 发现顺序

​Run 生命周期

​run：启动

​continue：提交结果或恢复

​check：按需检查

​Run state 存储

​文本模式的恢复提示

​下一步

先区分平台 Skill 与项目 Skill

常用路径

子命令

通用选项

包管理

add

show

Skill 发现顺序

Run 生命周期

run：启动

continue：提交结果或恢复

check：按需检查

Run state 存储

文本模式的恢复提示

下一步