Skill Creator 概览（进阶）

创建、优化或组合 Skill 时，通常只需要在 Agent 里调用 /comet-any 并按提示确认。评估、发布、分发和恢复会由流程引导；除非排障或自动化集成，不需要先关心底层命令、内部状态或生成物结构。本页是进阶内容，如果只想快速创建一个 Skill，先看快速上手：组合任意 Skill。

/comet-any（也叫 Skill Creator）是 Comet 的 Skill Creator。你描述想要的工作流，它读取真实本地 Skill、把目标编译成一份 Workflow Contract，再生成可验证、可评审、可分发的 Skill Bundle，并把后端复杂度（Bundle、Factory、composition、resolved-skills）隐藏在内部。

核心设计原则

理解 /comet-any 的关键是一个两层分离：

层	内容	谁会接触
用户层	三种起点 + `保留 / 新增 / 替换 / 关闭` 的调整词汇 + 每个节点的职责说明	所有用户
内部层	Bundle、Factory、composition、Workflow Protocol、resolved-skills.json	仅审计/排障时查看

用户唯一需要记住的入口是 /comet-any。需要恢复创建状态时用 comet creator；进入发布后用 comet publish；comet bundle 只作为高级后端保留给审计和排障。

主线

/comet-any 创建  →  comet eval 验证  →  comet creator 查状态  →  comet publish 发布和分发

展开后的完整链路：

/comet-any 创建
  → comet eval --collect / --html（验证）
  → comet creator status / next（readiness 和唯一下一步）
  → comet publish review / approve / run（发布）
  → comet publish distribute --preview（强制预览）
  → comet publish distribute（真实分发）

comet creator 是 /comet-any 的恢复和创建状态表面；comet bundle 是高级 Bundle 后端；comet skill 是底层 Skill 工具，适合本地调试和 Engine Run。它们都不是日常创建 Skill 的主入口。

三种起点

用户第一层只需要从三种起点里选一个。它们对应三种 Skill Creator 意图（skillCreatorIntent），后端会把每条路径都编译到同一种 Workflow Contract：

起点（用户层）	Skill Creator 意图	含义	典型场景
基于 Comet 现有 Skill 的五阶段定制	`customize-comet`	在 `/comet` 受保护边界内做增量调整	给 `/comet` 增加 `grill-me` 需求澄清 Skill
创建全新 workflow Skill	`new-skill`	从目标描述生成新的 workflow-kernel	沉淀一个团队专属流程
整理已有 Skill	`upgrade-existing`	把现有 Skill 整理成可发布标准包	把散乱的 Skill 规范化

Workflow Contract：所有路径的共同模型

不管你选哪种起点，/comet-any 最终都会把目标编译成同一种 Workflow Contract。这是理解整个 Skill Creator 的核心概念：

概念	含义
Workflow Node	流程中的可恢复节点，例如 `open`、`design`、`plan`、`execute`、`review`、`verify`、`archive`
Node Responsibility	该节点在 Agent workflow 里承担的职责，用来解释它为什么存在、要产出什么、能否替换
Skill Binding	某个节点的实现 Skill 或辅助 Skill
Required Skill Call	要求节点内必须调用某个 Skill，但不替换节点的实现。例如要求 `open` 必须调用 `grill-me` 澄清需求
Output Schema	节点必须产出的文件、状态或 evidence。脚本、eval、readiness 只认 Output Schema，不认 Skill 名字
Guardrail	阻断或放行节点推进的检查
Handoff	子代理或跨节点交接时必须带回的 evidence
workflow-protocol.json	生成包的唯一运行事实源，runtime / eval / review / readiness 都读它

小鱼把新建、升级和组合三种起点整理到同一份 Workflow Contract 模板

不管从新建、升级还是组合开始，最终都要落到同一份 Workflow Contract

两类 Workflow

`comet-five-phase-overlay`

以 Comet 经典五阶段为骨架做增量调整。保留 /comet 主流程和 .comet.yaml 状态语义，内置 8 个节点。

`workflow-kernel`

全新自定义工作流。从零声明节点、Output Schema、Guardrail 和 Handoff，需要重新声明 state。

受保护边界：基于 Comet 现有 Skill 的五阶段定制

当你选择”基于 Comet 现有 Skill 的五阶段定制”时，/comet 被视为受保护边界。comet-five-phase-overlay 内置这 8 个节点：

节点	职责	类型	可用操作
`open`	接收需求、选定变更形态、初始化 Comet state	control	`require`、`augment`
`design`	把确认的需求变成设计产物和 OpenSpec delta	producer	`require`、`augment`、`override`
`plan`	产出可执行的实施计划	producer	`require`、`augment`、`override`
`execute`	直接执行实施计划	control	`require`、`augment`
`subagent-execute`	委派子代理执行并要求回传 evidence	handoff	`require`、`augment`
`review`	在验证前用审查 Skill 检查实现（可选）	guardrail	`require`、`augment`、`disable`
`verify`	运行验证、调和分支、决定是否完成	control	`require`、`augment`
`archive`	归档 OpenSpec 变更并同步 delta	control	`require`、`augment`

普通模式下有明确规则：

规则	说明
control 节点不能 override	`open`、`execute`、`verify`、`archive` 只能 `require`/`augment`（例如要求调用某个 Skill），不能替换实现
producer 节点可以 override	`design`、`plan` 可以替换实现，但必须 `satisfies` 对应的 Output Schema
可选节点可以 disable	`review` 标记为 `optional`，可以关闭
Required Skill Call 不替换实现	它要求节点内部调用某个 Skill，节点本身的实现 Skill 不变

想替换 control 节点（open/execute/verify/archive）？普通模式不允许。这时要改走高级 workflow-kernel，并重新声明 state、Output Schema 和 Guardrail。

8 个内置 Output Schema

/comet-any 内置 8 个 Output Schema，runtime/eval/readiness 据此判断节点是否达标，而不是看 Skill 名字：

Output Schema	节点	产出
`comet.intake.v1`	`open`	Comet state 初始化
`comet.design.v1`	`design`	设计文档 + OpenSpec delta
`comet.plan.v1`	`plan`	实施计划 + tasks
`comet.execution-evidence.v1`	`execute`	实现摘要 + 测试证据
`comet.handoff.v1`	`subagent-execute`	移交请求 + 回传结果
`comet.review.v1`	`review`	审查摘要（blockers 可选）
`comet.verify.v1`	`verify`	验证命令 + 验证结果
`comet.archive.v1`	`archive`	归档摘要 + 归档状态

producer 节点做 override 时，必须在 satisfies 里声明它满足哪个 Output Schema。例如替换 design 实现，必须 satisfies: [“comet.design.v1”]，否则校验会报 producer-missing-output-schema。

方案示例：给 /comet 增加 grill-me 需求澄清

下面这个 plan.json 用 Required Skill Call 在 open 节点强制调用 grill-me，让 /comet 在进入设计前先把需求问清楚——不替换任何节点实现：

{
  "goal": "基于 Comet 现有 Skill 的五阶段定制，在 open 节点加入 grill-me 澄清需求。",
  "skillCreatorIntent": "customize-comet",
  "workflow": {
    "kind": "comet-five-phase-overlay",
    "name": "comet-with-grill-me",
    "goal": "在 open 节点要求调用 grill-me 澄清需求。",
    "nodes": {
      "open": {
        "requiredSkillCalls": [
          {
            "skill": "grill-me",
            "reason": "在创建 OpenSpec change 前澄清目标、边界和验收标准。"
          }
        ]
      }
    }
  }
}

关键点：open 的实现 Skill 没变，只是在节点内部强制调用额外 Skill，并通过 Output Schema 收回澄清 evidence。

自定义节点（workflow-kernel）

workflow-kernel 允许声明全新节点。每个节点必须用 responsibility 说明职责，并声明 Output Schema 和 Guardrail：

{
  "id": "delegate-notes",
  "label": "Delegate Notes",
  "kind": "handoff",
  "responsibility": "Delegate release note drafting and require returned evidence.",
  "implementation": { "skill": "handoff-coordinator", "scope": "handoff" },
  "requiredSkillCalls": [
    { "skill": "release-notes", "scope": "handoff" }
  ],
  "operations": ["require", "augment"],
  "outputSchemas": ["release.notes.v1"],
  "guardrails": [
    { "id": "handoff-returned", "label": "Handoff returned evidence", "validation": "semantic" }
  ]
}

/comet-any 做什么

一次完整的 /comet-any 调用会按顺序做这些事：

先尝试恢复现有创作状态，而不是直接新建。
读取 .comet/skill-preferences.yaml 里的偏好顺序（advisory / strict 模式）。
用 find-skill 解析真实 Skill 内容（读 SKILL.md、references、rules、scripts、hooks），而不是只按名字猜测。
处理缺失或歧义候选，必须暂停询问用户。
把目标编译成 Workflow Contract（Workflow Nodes、Skill Bindings、Output Schemas、Guardrails、Handoffs）。
校验 Workflow Contract（control 不能 override、producer override 要 satisfy、Output Schema 要存在等）。
先展示 Skill Creator 方案确认页，用户确认后才写 draft。
通过 authoring lane 生成 entry Skill、每个节点的内部 Skill、reference/workflow-protocol.json、scripts 和平台 agent 定义。
生成 comet/eval.yaml 评估清单（Engine 启用时还有 Engine Package）。
通过 comet creator status/next 查看 readiness，再进入 review、approval、publish 和 distribute。

什么时候用 /comet-any

想把团队流程做成可复用 Skill。
想优化已有 Skill，使其可评估、可发布。
想在 /comet 五阶段基础上增加、替换或关闭某些环节。
想组合多个 Skill，并保留真实来源证据。
想把生成物分发到 Claude Code、Codex 等平台。

/comet-any 的产出

一次完整生成或优化后，产物包含：

<bundle-draft>/
  bundle.yaml                         # Bundle 清单
  skills/<entry-skill>/
    SKILL.md                          # 用户真正调用的入口
    comet/
      skill.yaml                      # Engine 运行计划（Engine 启用时）
      guardrails.yaml                 # 运行时约束
      checks.yaml                     # runtime check（运行期）
      eval.yaml                       # 创建期评估 manifest（发布前证据）
    reference/
      workflow-protocol.json          # 唯一运行事实源（runtime/eval/review/readiness 共用）
      resolved-skills.json            # 真实 Skill 来源证据 + workflow 节点信息
      composition-report.md           # 组合方案和偏离解释
      decision-points.md              # 决策点
      recovery.md                     # 恢复路径
      skill-review.md                 # 作者自审
      authoring-lanes.json            # 创作车道记录（含 protocolHash）
      subagents/                      # 便携子代理角色说明
    scripts/                          # required control plane
      workflow-state.mjs
      workflow-guard.mjs
      workflow-handoff.mjs
      comet-plan.mjs
      comet-check.mjs
      comet-hook-guard.mjs
    agents/claude/                    # Claude Code custom agents（目标平台支持时分发）
  rules/                              # required control plane
  hooks/                              # required control plane（portable hook descriptor）

关键文件职责

文件	生命周期	职责
`SKILL.md`	创建期 + 运行期	用户真正调用的入口
`reference/workflow-protocol.json`	创建期 + 运行期	唯一运行事实源：节点、边、Output Schema、state、evals
`reference/resolved-skills.json`	创建期	真实 Skill 来源、hash、workflow 节点绑定、偏好证据
`reference/composition-report.md`	创建期	组合方案、偏离解释、风险和 review evidence
`comet/skill.yaml`	运行期	内部运行计划（goal、orchestration、steps），不是用户手写入口
`comet/guardrails.yaml`	运行期	由偏好和风险策略生成的约束（允许列表、预算）
`comet/checks.yaml`	运行期	runtime check（progress/step/completion）
`comet/eval.yaml`	创建期	Eval manifest（`comet eval` 的输入）

workflow-protocol.json 是核心。runtime、eval、review、publish readiness 全部读这一份协议，保证”创建时校验通过”和”运行时能恢复”指向同一个事实。

必需能力集合（required capability set）

稳定组合 Skill Bundle 的 required capability set 是 skills / scripts / rules / hooks / references / agents：

skills：入口 Skill 和各节点内部 Skill。
scripts / rules / hooks：required control plane，不是可随意删除的附属文件。它们负责状态推进、守卫、移交的确定性。
references：真实来源证据和创作审计。
agents：平台原生 agent 定义。Claude Code 分发会把生成的 custom agents 写到目标平台预览里。

hooks/*.yaml 是 Comet portable hook descriptor，只有通过 comet publish distribute 编译到目标平台配置后才会生效。

/comet-any 不应把手动 comet bundle 命令当成用户主流程。Bundle 是确定性后端，由 /comet-any 在内部调用。

硬规则（hard gates）

/comet-any 有几条不可妥协的硬规则，理解它们能避免踩坑：

用户只调用这个 Skill，CLI 是内部后端。
必须用 find-skill 解析真实 Skill，不能只按名字推测能力。
缺失/歧义候选必须暂停询问用户，绝不静默忽略或替用户选择。
必须先展示方案确认页，用户确认后才写 draft。
Required Skill Call 不替换节点实现。
producer override 必须声明 satisfies 的 Output Schema。
control 节点普通模式不得 override。
eval、review、publish readiness 必须读取同一份 workflow-protocol.json。
生成物不能残留 AUTHORING PENDING 标记；入口 Decision Core 或 substance 节点没写完会阻塞发布。
子代理 Handoff 必须要求子代理加载 Required Skill Call 并回传 evidence。
脚本只读取 protocol 和 state，不把 Skill 名称当成校验依据。
Eval 被跳过或失败 → 永远不进入 ready。
缺少人工批准 → 永远不 ready。
分发前必须先 preview，用户确认后才写入。
安装前必须询问用户，不得自动安装。

校验失败码（validation findings）

/comet-any 在编译 Workflow Contract 时会校验，失败会给出明确 finding code：

finding code	含义
`unknown-node`	patch 引用了当前 kind 不存在的节点
`unsupported-operation`	节点不支持该操作（例如对 control 节点 override）
`control-node-override`	control 节点普通模式被 override
`producer-missing-output-schema`	producer override 没有声明 satisfies 的 Output Schema
`missing-output-schema`	节点引用了未定义的 Output Schema
`orphan-output-schema`	Output Schema 已定义，但没有挂到任何 Workflow Node
`duplicate-node`	重复定义了相同 id 的节点
`disabled-required-node`	必需节点被 disable（只有 optional 节点能 disable）

下一步

创建 Skill 的完整流程 — 从准备偏好到生成、评估、发布、分发
Skill 偏好与真实来源 — 配置 .comet/skill-preferences.yaml
发布和分发 Skill — readiness、approval、publish 和 distribute
Skill 与 Engine — Skill 包结构和 Engine 运行时
评估系统概览 — eval 如何为发布提供证据

快速上手（基础）

深入掌握（进阶）

相关命令

Skill Creator 概览（进阶）

核心设计原则

主线

三种起点

Workflow Contract：所有路径的共同模型

两类 Workflow

`comet-five-phase-overlay`

`workflow-kernel`

受保护边界：基于 Comet 现有 Skill 的五阶段定制

8 个内置 Output Schema

方案示例：给 /comet 增加 grill-me 需求澄清

自定义节点（workflow-kernel）

/comet-any 做什么

什么时候用 /comet-any

/comet-any 的产出

关键文件职责

必需能力集合（required capability set）

硬规则（hard gates）

校验失败码（validation findings）

下一步

​核心设计原则

​主线

​三种起点

​Workflow Contract：所有路径的共同模型

​两类 Workflow

​comet-five-phase-overlay

​workflow-kernel

​受保护边界：基于 Comet 现有 Skill 的五阶段定制

​8 个内置 Output Schema

​方案示例：给 /comet 增加 grill-me 需求澄清

​自定义节点（workflow-kernel）

​/comet-any 做什么

​什么时候用 /comet-any

​/comet-any 的产出

​关键文件职责

​必需能力集合（required capability set）

​硬规则（hard gates）

​校验失败码（validation findings）

​下一步

核心设计原则

主线

三种起点

Workflow Contract：所有路径的共同模型

两类 Workflow

`comet-five-phase-overlay`

`workflow-kernel`

受保护边界：基于 Comet 现有 Skill 的五阶段定制

8 个内置 Output Schema

方案示例：给 /comet 增加 grill-me 需求澄清

自定义节点（workflow-kernel）

/comet-any 做什么

什么时候用 /comet-any

/comet-any 的产出

关键文件职责

必需能力集合（required capability set）

硬规则（hard gates）

校验失败码（validation findings）

下一步