Skill 与 Engine（进阶）

​

你是否需要读本页

• SKILL.md 是人和 Agent 看到的入口说明。
• comet/ 目录是运行时控制面，决定如何执行、恢复、检查和评估。
• comet eval 看发布前证据，comet skill check 看某次 Run 的运行期检查；两者不是同一件事。

​

三类 Skill

​

Skill 发现顺序

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

​

Skill 包结构

​

各文件职责

​

Skill 定义：skill.yaml

apiVersion: comet/v1alpha1
kind: Skill
metadata:
  name: comet-classic
  version: "1"
goal:
  statement: "驱动五阶段可恢复工作流"
  inputs: []
  outputs: []
  success: []
orchestration:
  mode: deterministic
  entry: full.open
  steps:
    - id: full.open
      action:
        type: invoke_skill
        ref: comet-open
      next: full.design
    # ...更多步骤
skills: [comet-open, comet-design, comet-build, ...]
agents: []
tools: []

​

步骤动作类型

​

两种编排模式

​

deterministic（确定性）

• 步骤是一个静态图，entry 指定起点，每个 step 的 next 指定下一步。
• Engine 自己解析当前 step → 构造动作 → 过 guardrails → 暂停等结果。
• 成功后推进到 next；失败则增加重试计数、停留在当前 step。
• next 为空时 Run 完成。comet skill run 目前只支持 deterministic 端到端执行。

​

adaptive（自适应）

• 不能定义 entry 或 steps。
• Engine 不自己提议动作——由外部 Agent 提议，通过 acceptAdaptiveAction 注入，同样过 guardrails。
• 完成由 evals/Agent 驱动，没有 next: null 终止 step。
• 循环层已就绪并有测试覆盖，但 comet skill run 的公开入口目前会拒绝 adaptive 包。

​

Engine 运行循环

Engine 只提议、约束和记录；真正的副作用由外部执行后再 resume

​

pending action：为什么暂停

​

Run 生命周期

​

run：启动

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。

​

resume：提交结果或恢复

1. 验证提交的 outcome 对应当前 pending action id。
2. 合并 outcome 的 artifacts 到 artifacts 存储。
3. 记录 action_completed trajectory 事件。
4. recordOutcome：清除 pending，失败则增加重试，成功则推进 currentStep。
5. 运行 step-scope evals。
6. 如果 next 为空，status = completed，运行 completion-scope evals。
7. 否则再次 decide 提议下一个动作。

• 返回当前 pending action（如果存在）。
• 或在没有 pending 时重新提议下一个动作。

​

eval：按需检查

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

​

不可变快照

​

hash 怎么算

​

为什么重要

• Run 锁定到启动时的 Skill 版本——之后修改 skill.yaml 不影响进行中的 Run。恢复时从快照重新加载，不是读工作区的最新文件。
• 防篡改——重新加载快照时会重算 hash 验证完整性。
• 可复现——同一个快照 + 同样的 outcome 序列产生同样的 Run 轨迹。

​

升级运行中 Skill

comet skill continue --run-id demo-run --upgrade my-skill --project .

​

guardrails

​

默认值

​

约束检查

​

示例

# comet-classic 的 guardrails
allowedSkills: [comet-open, comet-design, comet-build, comet-verify, comet-archive, comet-hotfix, comet-tweak]
allowedAgents: []
allowedTools: []
maxIterations: 500
maxRetriesPerAction: 3
confirmationRequiredFor: []

​

runtime checks

​

两种检查类型

​

三个作用域

​

示例

# comet-classic 的 runtime check（evals.yaml）
runtime:
  - id: classic-completed
    scope: completion
    type: state_equals
    field: status
    equals: completed

​

产物通道（authoring lanes）

​

评审门禁

• 必需通道是否齐全（workflow-entry / skill-core / script-contract / reference / skill-review，Engine 启用时还有 eval）。
• 必需 artifact 是否存在（SKILL.md、reference/workflow-protocol.json、decision-points.md、recovery.md、composition-report.md、resolved-skills.json、skill-review.md、六个控制面脚本等）。
• 必需 claim 是否存在且引用的 artifact 存在（workflow-entry、script:workflow-state 等）。
• 产物与 Workflow Contract 一致（节点、Output Schema、Required Skill Call 对得上）。

​

Run state 存储

​

两种存储位置

​

run-state.json 字段

{
  "runId": "demo-run",
  "skill": "my-skill",
  "skillVersion": "1",
  "skillHash": "<sha256>",
  "orchestration": "deterministic",
  "currentStep": "step-1",
  "iteration": 3,
  "pending": "<action-id>",
  "status": "waiting",
  "retries": {}
}

​

五个附属文件

​

经典工作流和 Engine 的关系

​

.comet.yaml 和 run-state.json 的边界

• .comet.yaml 保存用户可理解的工作流投影（phase、build_mode、verify_result 等），只通过 run_id 链接到 Engine Run。
• 完整的 Run 细节（currentStep、pending、trajectory、artifacts）在 .comet/run-state.json，不写进 .comet.yaml。
• 首次进入一个 change 时，ensureClassicRun 从 .comet.yaml 的 classic 字段推导当前 step，创建快照和 Run state，建立 run_id 链接。

​

Classic 控制包的打包方式

​

什么时候用 /comet-any

/comet-any -> comet eval -> comet publish

​

常见命令

# 包管理
comet skill add ./my-skill --project .
comet skill show my-skill --project .
comet skill show my-skill --json

# Run 生命周期
comet skill run my-skill --run-id demo-run --project .
comet skill continue --run-id demo-run --status succeeded --summary "完成"
comet skill check --run-id demo-run --scope completion

# 升级进行中的 Run
comet skill continue --run-id demo-run --upgrade my-skill --project .

​

下一步

• 工作流概念 — /comet 如何在底层使用 Engine
• comet skill — 完整命令参考
• Runtime check — comet skill check 和 comet eval 的区别
• Skill Creator 概览 — 用 /comet-any 创建 Engine-enabled Skill