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	`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 <key=value>`	传入确认参数	`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 发现顺序

resolveSkill 按以下顺序查找，找到即停止：

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 事件。
decide 解析 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 是 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`	产出的 artifacts 映射

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

文本模式的恢复提示

comet skill 在文本模式下会直接打印 Pending action 和 Next: 恢复提示，让你不需要在暂停的 Run 或失败的 eval 后自己猜下一步。例如 run 输出：

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 失败时会提示：

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、评估和发布（进阶）

核心脚本

常用路径

子命令

通用选项

包管理

add

show

Skill 发现顺序

Run 生命周期

run：启动

continue：提交结果或恢复

check：按需检查

Run state 存储

文本模式的恢复提示

下一步

​常用路径

​子命令

​通用选项

​包管理

​add

​show

​Skill 发现顺序

​Run 生命周期

​run：启动

​continue：提交结果或恢复

​check：按需检查

​Run state 存储

​文本模式的恢复提示

​下一步

常用路径

子命令

通用选项

包管理

add

show

Skill 发现顺序

Run 生命周期

run：启动

continue：提交结果或恢复

check：按需检查

Run state 存储

文本模式的恢复提示

下一步