> ## 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.

# Skill 的类型与用途

> 理解 Comet Skill 的三类来源，Skill 的发现优先级，以及经典 Spec 模式用户需要知道的 Skill 边界。

Comet 的核心能力通过 Skill 组织。用户正常只调用 `/comet`；它按项目配置选择 Native 或 Classic。进入经典 Spec 模式后，也不需要深入理解 Skill 的底层机制。

## Skill 存放在哪里

理解 Skill 的关键，是知道它们安装到哪个目录、由谁发现：

| 安装方式              | 目标目录                      | 谁发现它                                 | 说明                     |
| ----------------- | ------------------------- | ------------------------------------ | ---------------------- |
| `comet init`      | 平台目录（如 `.claude/skills/`） | AI 平台直接发现，显示为斜杠命令                    | 内置工作流 Skill 装在这里       |
| `comet skill add` | `.comet/skills/<name>`    | **Comet Engine** 发现，不直接进平台           | 这就是"项目 Skill"          |
| `/comet-any` 生成   | Bundle draft 目录           | 评估发布后由 `comet publish distribute` 分发 | Skill Creator 生成 Skill |

<p align="center">
  <img src="https://mintcdn.com/comet-bb5f5294/sd_slIArmm0kHnD4/assets/skills-illustrations/01-skill-source-greenhouse.png?fit=max&auto=format&n=sd_slIArmm0kHnD4&q=85&s=d2d438cec343869b84ee80323ed8c558" alt="小鱼在小温室里按平台 Skill、项目 Skill 和生成 Skill 三种来源整理 Skill 标签" width="800" data-path="assets/skills-illustrations/01-skill-source-greenhouse.png" />
</p>

<p align="center">
  不同来源的 Skill 由不同机制发现；项目 Skill 可以覆盖内置，但不会在失败时静默回退
</p>

<Note>
  <strong>平台 Skill</strong>和<strong>项目 Skill</strong>的区别：平台 Skill（
  <code>comet init</code> 装到 <code>.claude/skills/</code> 等）由 AI
  平台直接发现并变成斜杠命令；项目 Skill（<code>comet skill add</code> 装到{' '}
  <code>.comet/skills/</code>）是 Comet Engine 自己的 Skill 池，不直接暴露给平台，而是由 Engine
  在运行时按名称解析。
</Note>

## 项目 Skill 是什么

项目 Skill 是安装到 **项目内** `.comet/skills/<name>/` 目录的 Skill 包。它们和平台 Skill 不是一回事：

* **位置**：`.comet/skills/<name>/`，和 `.comet/config.yaml` 同级，属于项目本身（可以提交到 Git）。
* **谁发现**：Comet Engine 的 `resolveSkill`，发现顺序是 **explicit（显式路径）→ project（项目 Skill）→ builtin（内置 Skill）**。项目 Skill 优先于内置 Skill。
* **不直接进平台**：它们不会自动变成 `.claude/skills/` 里的斜杠命令，而是由 Engine 在 `/comet-classic` 调用时按名称解析。

### 为什么要用项目 Skill

| 用途              | 说明                                                                                |
| --------------- | --------------------------------------------------------------------------------- |
| 覆盖内置 Skill      | 在 `.comet/skills/comet-build/` 放一个自定义 `comet-build`，Engine 优先用它而不是内置版本。团队统一流程时有用。 |
| 安装 Engine Skill | `/comet-any` 生成的 Skill 或社区 Skill 可以装到这里，让 Engine 运行它们。                            |
| 项目内可复用          | 提交到 Git 后，团队成员 clone 仓库就有同一套 Skill。                                               |

### 怎么安装项目 Skill

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

这会把 `./my-skill` 目录校验、计算 hash 后复制到 `.comet/skills/<metadata.name>/`。已存在时需要 `--overwrite`。安装拒绝符号链接，保证 Skill 包内容是真实的。

### Skill 创作工具链

除了 `add`，`comet skill` 还提供一整套本地 Skill 工具：

| 命令                     | 作用                                                 |
| ---------------------- | -------------------------------------------------- |
| `comet skill add`      | 安装 Skill 包到 `.comet/skills/`                       |
| `comet skill show`     | 查看 Skill 来源、结构、hash、步骤、guardrails 和 runtime checks |
| `comet skill run`      | 启动高级 deterministic Engine Run                      |
| `comet skill continue` | 提交 pending action 结果或恢复 Run                        |
| `comet skill check`    | 运行 Engine Run 的 runtime checks                     |

<Warning>
  项目 Skill 按名称覆盖内置 Skill 时，如果项目 Skill 无效（校验失败），Engine 会
  <strong>直接失败</strong>
  而不是回退到内置。这避免"你以为在用自定义版本，实际静默用了内置"的问题（fail-closed，而非静默降级）。
</Warning>

## 经典模式用到的 Skill

经典 Spec 模式的五阶段流程由这些内置 Skill 驱动（`comet init` 安装到平台目录）：

| Skill                            | 作用                         |
| -------------------------------- | -------------------------- |
| `/comet-classic`                 | Classic 主入口，检测状态并路由到当前阶段   |
| `/comet-open`                    | open 阶段：创建 OpenSpec change |
| `/comet-design`                  | design 阶段：深度技术设计           |
| `/comet-build`                   | build 阶段：计划并执行             |
| `/comet-verify`                  | verify 阶段：验证实现             |
| `/comet-archive`                 | archive 阶段：归档              |
| `/comet-hotfix` / `/comet-tweak` | 轻量预设                       |

这些 Skill 随 Comet 包分发，Classic 初始化会安装到平台目录。正常只需调用 `/comet`；配置选择 Classic 后，内部 `/comet-classic` 会检测状态并调用对应阶段 Skill。

## 用 /comet-any 创建可复用 Skill

`/comet-any`（Skill Creator）是普通用户创建或优化 Skill 的主入口。你只需要描述想创建的工作流，它会：

1. 读取项目级偏好 `.comet/skill-preferences.yaml`。
2. 用 `find-skill` 解析**真实本地 Skill 内容**——不靠名字推测能力。
3. 展示 Skill Creator 确认页，列出每个 Skill 的来源、hash、角色和调用顺序，等你确认。
4. 确认后生成**稳定组合 Skill Bundle**（含 skills/scripts/rules/hooks/references），而不是单个 `SKILL.md`。
5. 内部走 CLI 后端做校验、生成 install-candidate、可选安装。

`.comet/skill-preferences.yaml` 支持 `prefer`/`require`/`advisory` 三类条目，确认后会计算 `preferenceHash` 绑定到产物。

<Note>
  普通用户不需要理解 Bundle、Factory、组合、Phase Recipe
  这些内部概念——它们只存在于实现和审计证据里。用户视角只有三个起点：
  <strong>定制 /comet-classic</strong>、<strong>创建新 Skill</strong>、
  <strong>升级已有 Skill</strong>。
</Note>

正常用户路径是：

```text theme={null}
/comet-any -> comet eval -> comet creator status/next -> review/approve/run -> distribute
```

详见[组合任意 Skill 快速上手](/zh/skill-creator/getting-started)。

## Engine：进阶内容

如果你用 `/comet-any` 创建可复用 Skill，或用 `comet skill` 做本地调试和 Engine Run，你需要理解 Skill Engine——Comet 的确定性运行时。Engine 涉及 Skill 包结构、pending action/resume 循环、不可变快照、guardrails 和 runtime checks。

经典 `/comet-classic` 用户**不需要理解 Engine**就能使用五阶段工作流。想深入了解时，看[Skill 与 Engine（进阶）](/zh/skill-creator/engine)——完整的 Engine 机制详解，位于组合任意 Skill tab。

## 下一步

* [工作流概念](/zh/concepts/workflow) — `/comet-classic` 如何串联五阶段
* [状态与配置](/zh/concepts/state-management) — `.comet.yaml` 字段和配置
* [Skill 与 Engine（进阶）](/zh/skill-creator/engine) — 深入理解 Engine 运行时