跳转到主要内容
创建、优化或组合 Skill 时，通常只需要在 Agent 里调用 /comet-any 并按提示确认。首次使用时它会自动推荐默认偏好；除非你要手写偏好或排查组合问题，不需要先关心本页的配置细节。
.comet/skill-preferences.yaml 是项目级偏好文件。它表达这个项目希望 /comet-any 优先复用哪些 Skill，以及遇到缺失、歧义、偏离和 scripts/hooks 时怎么处理。 它不是严格白名单，也不是内部状态文件——你可以手写、提交到项目，也可以由 /comet-any 首次扫描后生成。

小鱼用指南针和砝码秤校准 prefer、require、advisory、strict 和真实来源

偏好文件表达组合方向和硬约束；真实来源仍要被解析，不能只按名字猜

​
文件位置

.comet/skill-preferences.yaml
它和 .comet/config.yaml 同级。

​
完整字段

version: 1
mode: advisory

prefer:
  - brainstorming
  - writing-plans
  - systematic-debugging
  - test-driven-development
  - requesting-code-review
  - verification-before-completion

require:
  - verification-before-completion

policies:
  missing: ask
  ambiguous: ask
  deviation: explain
  scripts: disclose
  hooks: disclose
顶层只允许这四个 key：version、mode、prefer、require、policies。任何未知字段会触发 unknown-field 警告。version 必须是 1。

​
version

必须是 1。用于未来 schema 演进。

​
mode

模式行为适合
advisory默认。可以补充目标需要的 Skill，但必须解释偏离原因个人/小团队，灵活优先
strict团队标准化模式。required Skill 缺失、歧义或禁止 scripts/hooks 时阻塞团队标准化，一致性优先

​
prefer

希望优先复用的 Skill 列表。顺序代表偏好优先级——/comet-any 会尽量按这个顺序构建调用链。列表里不允许重复（重复会触发 duplicate-prefer 警告）。

​
require

生成组合 Skill 时必须满足的 Skill。这些 Skill 缺失或歧义时，组合方案不能通过。同样不允许重复。

​
policies

策略可选值默认作用
missingask / failask偏好 Skill 缺失时询问还是直接失败
ambiguousask / failask同名 Skill 有多个不同来源时询问还是失败
deviationexplain / failexplain偏离偏好顺序时解释还是失败
scriptsallow / disclose / denydisclose生成或分发 scripts 时的策略
hooksallow / disclose / denydisclose生成或分发 hooks 时的策略

​
推荐起点

如果你不确定怎么写，可以从这个配置开始： 
version: 1
mode: advisory

prefer:
  - brainstorming
  - writing-plans
  - systematic-debugging
  - test-driven-development
  - requesting-code-review
  - verification-before-completion

require:
  - verification-before-completion

policies:
  missing: ask
  ambiguous: ask
  deviation: explain
  scripts: disclose
  hooks: disclose
/comet-any 也会在偏好不存在时主动扫描平台 Skill inventory，按能力分组推荐默认偏好，并询问你是否保存为项目级偏好。comet creator guide 返回的 preference 字段会标记偏好状态为 missing / present / invalid。

​
手写示例

​
偏严谨的 PR 评审 Skill

version: 1
mode: advisory

prefer:
  - brainstorming
  - writing-plans
  - requesting-code-review
  - verification-before-completion

require:
  - requesting-code-review
  - verification-before-completion

policies:
  missing: ask
  ambiguous: ask
  deviation: explain
  scripts: disclose
  hooks: disclose

​
团队标准化（strict 模式）

version: 1
mode: strict

prefer:
  - writing-plans
  - test-driven-development
  - verification-before-completion

require:
  - verification-before-completion
  - test-driven-development

policies:
  missing: fail
  ambiguous: fail
  deviation: fail
  scripts: disclose
  hooks: deny
这个配置下：required Skill 缺失或歧义会直接阻塞；任何偏离偏好顺序都会失败；hooks 一律不允许。

​
完全禁止可执行能力

如果你的环境对脚本和钩子零容忍： 
version: 1
mode: strict

prefer: []
require: []

policies:
  missing: ask
  ambiguous: ask
  deviation: explain
  scripts: deny
  hooks: deny
/comet-any 会在生成阶段就拒绝任何带 scripts/hooks 的组合方案。

​
偏好如何影响生成

/comet-any 按以下规则使用偏好：
  1. 优先读取项目级偏好 .comet/skill-preferences.yaml。
  2. 偏好不存在时，扫描平台 Skill inventory，按能力分组推荐默认偏好，并询问是否保存。
  3. 用 find-skill 解析真实本地 Skill 来源与内容。
  4. advisory 可在说明原因后补充目标需要的 Skill。
  5. strict 遇到 required 缺失、歧义或禁止的 scripts/hooks 必须阻塞。
不得只按名字推测能力；/comet-any 必须读取最终候选的真实 SKILL.md、直接 reference、rules、scripts 和 hooks。

​
缺失和歧义候选

/comet-any 必须暂停并询问你如何处理 missing 和 ambiguous 项。它不能静默忽略缺失候选，也不能在多个来源中替你选择。
候选状态advisorystrict
missing 且 policies.missing=ask暂停询问暂停询问（若在 require 中则阻塞）
missing 且 policies.missing=fail阻塞阻塞
ambiguous 且 policies.ambiguous=ask暂停让你选来源暂停让你选来源
ambiguous 且 policies.ambiguous=fail阻塞阻塞
你明确选择来源后，/comet-any 会更新 Skill Creator metadata。你明确同意忽略缺失偏好时，它会记录原因，这个原因会进入评审摘要。

​
resolved-skills.json

生成物包含真实来源证据： 
reference/resolved-skills.json
它的结构（基于生成的 Workflow Contract）： 
{
  "schemaVersion": 1,
  "resolvedSkills": [
    {
      "query": "writing-plans",
      "preferenceIndex": 1,
      "status": "available",
      "sources": [
        {
          "name": "writing-plans",
          "preferenceIndex": 1,
          "platform": "claude",
          "scope": "global",
          "origin": "builtin",
          "root": "...",
          "description": "...",
          "hash": "..."
        }
      ]
    }
  ],
  "workflow": {
    "kind": "comet-five-phase-overlay",
    "nodes": [
      {
        "id": "plan",
        "label": "Plan",
        "implementation": { "skill": "comet-build", "operation": "default", "scope": "main" },
        "requiredSkillCalls": [],
        "outputSchemas": ["comet.plan.v1"]
      }
    ]
  },
  "preference": { "mode": "advisory", "source": "...", "hash": "..." }
}
它同时记录两件事：
  • resolvedSkills —— 真实 Skill 来源、hash 和状态（available / missing / ambiguous），证明组合基于本地真实内容，不是只按名字猜。
  • workflow —— 每个节点的实现 Skill、Required Skill Call 和 Output Schema，和 workflow-protocol.json 对齐。
这个文件是”不是按名字猜的”的证据，也记录了节点到 Skill 的绑定关系。准备发布或审查时优先看它——它证明组合基于本地真实内容，并能反查每个节点绑定了哪个 Skill。

​
preferenceHash 和偏好漂移

Comet 对偏好文件计算一个 SHA-256 hash（preferenceHash），存入 Skill Creator metadata。.comet/skill-preferences.yaml 在 Factory 初始化后发生变化时（preferenceHash 变化）：
模式漂移时
advisory给 warning，提示你选择继续旧组合方案或重新生成
strict阻塞，要求你确认继续或重新生成
生成物会记录 preferenceHash、模式、策略和 required Skill 作为项目级偏好证据。这些会出现在评审摘要里。

​
偏好漂移怎么处理

如果偏好漂移导致阻塞或 warning，你有两个选择：
  1. 继续旧组合方案：确认旧的组合仍然符合你的意图。旧方案基于旧偏好生成，可能在评审摘要里出现 [preference] 偏离提示。
  2. 重新生成：放弃旧 draft，基于新偏好重新走 /comet-any 流程。这会生成新的 planHash、preferenceHash 和 resolved-skills 证据。

​
下一步

最后修改于 2026年7月6日