> ## Documentation Index > Fetch the complete documentation index at: https://docs.comet.rpamis.com/llms.txt > Use this file to discover all available pages before exploring further. # Skill 偏好与真实来源（进阶） > 配置 .comet/skill-preferences.yaml 表达组合偏好，理解 advisory/strict 模式、策略、preferenceHash 漂移和 resolved-skills.json 真实来源证据。 创建、优化或组合 Skill 时，通常只需要在 Agent 里调用 /comet-any 并按提示确认。首次使用时它会自动推荐默认偏好；除非你要手写偏好或排查组合问题，不需要先关心本页的配置细节。 `.comet/skill-preferences.yaml` 是项目级偏好文件。它表达这个项目希望 `/comet-any` 优先复用哪些 Skill，以及遇到缺失、歧义、偏离和 scripts/hooks 时怎么处理。 它**不是**严格白名单，也**不是**内部状态文件——你可以手写、提交到项目，也可以由 `/comet-any` 首次扫描后生成。

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

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

## 文件位置 ```text theme={null} .comet/skill-preferences.yaml ``` 它和 `.comet/config.yaml` 同级。 ## 完整字段 ```yaml theme={null} 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 时的策略 | ## 推荐起点 如果你不确定怎么写，可以从这个配置开始： ```yaml theme={null} 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 ```yaml theme={null} 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 模式） ```yaml theme={null} 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 一律不允许。 ### 完全禁止可执行能力 如果你的环境对脚本和钩子零容忍： ```yaml theme={null} 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` 项。它不能静默忽略缺失候选，也不能在多个来源中替你选择。 | 候选状态 | 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 生成物包含真实来源证据： ```text theme={null} reference/resolved-skills.json ``` 它的结构（基于生成的 Workflow Contract）： ```json theme={null} { "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 证据。 ## 下一步 * [创建 Skill 的完整流程](/zh/skill-creator/workflow) — 完整 `/comet-any` 流程 * [发布和分发 Skill](/zh/skill-creator/publishing) — readiness 如何使用偏好和 eval 证据 * [Skill Creator 概览](/zh/skill-creator/overview) — 三种起点和受保护边界