跳转到主要内容
创建、优化或组合 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 加一个评审环节、要求用组件库
创建全新 workflow Skillnew-skill从目标描述生成新的 workflow-kernel沉淀一个团队专属流程
整理已有 Skillupgrade-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，但不替换节点的实现。例如要求 execute 必须调用 elementui
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 statecontrolrequire、augment
design把确认的需求变成设计产物和 OpenSpec deltaproducerrequire、augment、override
plan产出可执行的实施计划producerrequire、augment、override
execute直接执行实施计划controlrequire、augment
subagent-execute委派子代理执行并要求回传 evidencehandoffrequire、augment
review在验证前用审查 Skill 检查实现（可选）guardrailrequire、augment、disable
verify运行验证、调和分支、决定是否完成controlrequire、augment
archive归档 OpenSpec 变更并同步 deltacontrolrequire、augment
普通模式下有明确规则：
规则说明
control 节点不能 overrideopen、execute、verify、archive 只能 require/augment（例如要求调用某个 Skill），不能替换实现
producer 节点可以 overridedesign、plan 可以替换实现，但必须 satisfies 对应的 Output Schema
可选节点可以 disablereview 标记为 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.v1openComet state 初始化
comet.design.v1design设计文档 + OpenSpec delta
comet.plan.v1plan实施计划 + tasks
comet.execution-evidence.v1execute实现摘要 + 测试证据
comet.handoff.v1subagent-execute移交请求 + 回传结果
comet.review.v1review审查摘要（blockers 可选）
comet.verify.v1verify验证命令 + 验证结果
comet.archive.v1archive归档摘要 + 归档状态
producer 节点做 override 时，必须在 satisfies 里声明它满足哪个 Output Schema。例如替换 design 实现，必须 satisfies: [“comet.design.v1”]，否则校验会报 producer-missing-output-schema。

​
方案示例：给 /comet 加组件库和白盒审查

下面这个 plan.json 用 Required Skill Call 给 execute/subagent-execute 加组件库、给 review 加白盒审查——不替换任何节点实现： 
{
  "goal": "基于 Comet 现有 Skill 的五阶段定制，要求组件库和白盒审查。",
  "skillCreatorIntent": "customize-comet",
  "workflow": {
    "kind": "comet-five-phase-overlay",
    "name": "team-comet",
    "goal": "要求组件库和白盒审查。",
    "nodes": {
      "execute": {
        "requiredSkillCalls": [
          {
            "skill": "elementui",
            "reason": "Use project component library during direct implementation."
          }
        ]
      },
      "subagent-execute": {
        "requiredSkillCalls": [
          { "skill": "elementui", "scope": "handoff" }
        ]
      },
      "review": {
        "requiredSkillCalls": [
          { "skill": "whitebox-code-standard", "scope": "review" }
        ]
      }
    }
  }
}
关键点：execute/subagent-execute/review 的实现 Skill 没变，只是在节点内部强制调用额外 Skill，并通过 Handoff / 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 调用会按顺序做这些事：
  1. 先尝试恢复现有创作状态，而不是直接新建。
  2. 读取 .comet/skill-preferences.yaml 里的偏好顺序（advisory / strict 模式）。
  3. 用 find-skill 解析真实 Skill 内容（读 SKILL.md、references、rules、scripts、hooks），而不是只按名字猜测。
  4. 处理缺失或歧义候选，必须暂停询问用户。
  5. 把目标编译成 Workflow Contract（Workflow Nodes、Skill Bindings、Output Schemas、Guardrails、Handoffs）。
  6. 校验 Workflow Contract（control 不能 override、producer override 要 satisfy、Output Schema 要存在等）。
  7. 先展示 Skill Creator 方案确认页，用户确认后才写 draft。
  8. 通过 authoring lane 生成 entry Skill、每个节点的内部 Skill、reference/workflow-protocol.json、scripts 和平台 agent 定义。
  9. 生成 comet/eval.yaml 评估清单（Engine 启用时还有 Engine Package）。
  10. 通过 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-nodepatch 引用了当前 kind 不存在的节点
unsupported-operation节点不支持该操作（例如对 control 节点 override）
control-node-overridecontrol 节点普通模式被 override
producer-missing-output-schemaproducer override 没有声明 satisfies 的 Output Schema
missing-output-schema节点引用了未定义的 Output Schema
orphan-output-schemaOutput Schema 已定义，但没有挂到任何 Workflow Node
duplicate-node重复定义了相同 id 的节点
disabled-required-node必需节点被 disable（只有 optional 节点能 disable）

​
下一步

最后修改于 2026年7月6日