> ## Documentation Index
> Fetch the complete documentation index at: https://docs.comet.rpamis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# comet skill

> 管理本地 Comet Skill 包，并调试高级 Skill 运行。

`comet skill` 是低层 Skill 包和 Skill 运行（Engine Run）工具。它发现显式 Skill 目录、`.comet/skills/` 下的项目覆盖和内置 Skill，并提供本地 Skill 包管理和高级运行调试。

创建可复用 Skill 时优先用 [`/comet-any`](/zh/skill-creator/overview)。`comet skill run` / `comet skill continue` 更适合调试高级 Skill 运行。

<Note>
  如果你只想把一个本地 Skill 放进项目，通常只需要 <code>comet skill add</code> 和 <code>comet skill show</code>。运行、恢复和 runtime check 是高级调试能力，主要面向 Engine-enabled Skill。
</Note>

## 常用路径

| 目标                | 命令                                                 | 说明               |
| ----------------- | -------------------------------------------------- | ---------------- |
| 安装本地 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`                  |

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

## 包管理

### add

```bash theme={null}
comet skill add ./my-skill --project .
comet skill add ./my-skill --project . --overwrite
```

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

### show

```bash theme={null}
comet skill show my-skill --project .
```

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

## Skill 发现顺序

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

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

<Warning>
  bare 名字必须匹配 <code>^\[A-Za-z0-9]\[A-Za-z0-9.\_-]\*\$</code>。项目 Skill 按名称覆盖内置 Skill 时，如果项目 Skill 无效，会直接失败而不是回退到内置。这避免"你以为在用自定义版本，实际静默用了内置"的问题。
</Warning>

## Run 生命周期

### run：启动

```bash theme={null}
# 绑定 OpenSpec change 目录
comet skill run my-skill --change ./changes/demo

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

启动时做这些事：

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

### continue：提交结果或恢复

带 outcome（实际推进）：

```bash theme={null}
comet skill continue --change ./changes/demo --status succeeded --summary "Done" --artifact report=report.md
```

```bash theme={null}
comet skill continue --run-id demo-run --project . --status succeeded --summary "完成"
```

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

```bash theme={null}
comet skill continue --change ./changes/demo
```

升级当前 Run 到新 Skill 版本：

```bash theme={null}
comet skill continue --change ./changes/demo --upgrade my-skill --project .
```

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

<Warning>
  <code>--upgrade</code> 不能和 <code>--status</code>、<code>--summary</code>、<code>--artifact</code>、<code>--state</code> 组合使用。<code>--summary</code>、<code>--artifact</code>、<code>--state</code> 必须配合 <code>--status</code> 使用。
</Warning>

### check：按需检查

```bash theme={null}
comet skill check --change ./changes/demo --scope completion
```

```bash theme={null}
comet skill check --run-id demo-run --project . --scope completion
```

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

<Warning>
  <code>comet skill check</code> 只检查某次 Skill 运行的完成度，不是通用 Skill 评估。评估一个 Skill 产品能力，请用 <a href="/zh/cli/eval">comet eval</a>。详见 <a href="/zh/eval/runtime">Runtime check</a>。
</Warning>

## 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` 输出：

```text theme={null}
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` 失败时会提示：

```text theme={null}
Next: record the missing artifact/state and rerun comet skill check
```

## 下一步

* [Skill 与 Engine（进阶）](/zh/skill-creator/engine) — 理解 Skill 包和 Skill 运行（Engine Run）的语义、pending action、不可变快照
* [Runtime check](/zh/eval/runtime) — 区分 `comet skill check` 和 `comet eval`
* [Skill Creator 概览](/zh/skill-creator/overview) — 创建可复用 Skill 的主入口