Skill 偏好与真实来源（进阶）

创建、优化或组合 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

策略	可选值	默认	作用
`missing`	`ask` / `fail`	`ask`	偏好 Skill 缺失时询问还是直接失败
`ambiguous`	`ask` / `fail`	`ask`	同名 Skill 有多个不同来源时询问还是失败
`deviation`	`explain` / `fail`	`explain`	偏离偏好顺序时解释还是失败
`scripts`	`allow` / `disclose` / `deny`	`disclose`	生成或分发 scripts 时的策略
`hooks`	`allow` / `disclose` / `deny`	`disclose`	生成或分发 hooks 时的策略

手写示例

偏严谨的 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 按以下规则使用偏好：

优先读取项目级偏好 .comet/skill-preferences.yaml。
偏好不存在时，扫描平台 Skill inventory，按能力分组推荐默认偏好，并询问是否保存。
用 find-skill 解析真实本地 Skill 来源与内容。
advisory 可在说明原因后补充目标需要的 Skill。
strict 遇到 required 缺失、歧义或禁止的 scripts/hooks 必须阻塞。

不得只按名字推测能力；/comet-any 必须读取最终候选的真实 SKILL.md、直接 reference、rules、scripts 和 hooks。

缺失和歧义候选

/comet-any 必须暂停并询问你如何处理 missing 和 ambiguous 项。它不能静默忽略缺失候选，也不能在多个来源中替你选择。

候选状态	advisory	strict
`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，你有两个选择：

继续旧组合方案：确认旧的组合仍然符合你的意图。旧方案基于旧偏好生成，可能在评审摘要里出现 [preference] 偏离提示。
重新生成：放弃旧 draft，基于新偏好重新走 /comet-any 流程。这会生成新的 planHash、preferenceHash 和 resolved-skills 证据。

下一步

创建 Skill 的完整流程 — 完整 /comet-any 流程
发布和分发 Skill — readiness 如何使用偏好和 eval 证据
Skill Creator 概览 — 三种起点和受保护边界

快速上手（基础）

深入掌握（进阶）

相关命令

Skill 偏好与真实来源（进阶）

文件位置

完整字段

version

mode

prefer

require

policies

推荐起点

手写示例

偏严谨的 PR 评审 Skill

团队标准化（strict 模式）

完全禁止可执行能力

偏好如何影响生成

缺失和歧义候选

resolved-skills.json

preferenceHash 和偏好漂移

偏好漂移怎么处理

下一步

​文件位置

​完整字段

​version

​mode

​prefer

​require

​policies

​推荐起点

​手写示例

​偏严谨的 PR 评审 Skill

​团队标准化（strict 模式）

​完全禁止可执行能力

​偏好如何影响生成

​缺失和歧义候选

​resolved-skills.json

​preferenceHash 和偏好漂移

​偏好漂移怎么处理

​下一步

文件位置

完整字段

version

mode

prefer

require

policies

推荐起点

手写示例

偏严谨的 PR 评审 Skill

团队标准化（strict 模式）

完全禁止可执行能力

偏好如何影响生成

缺失和歧义候选

resolved-skills.json

preferenceHash 和偏好漂移

偏好漂移怎么处理

下一步