Skip to main content
This is advanced configuration. You do not need it for first use. /comet-any can recommend defaults automatically. Read this when you want to hand-edit preferences or debug composition behavior.
.comet/skill-preferences.yaml is a project-level preference file. It tells /comet-any which Skills this project prefers to reuse and how to handle missing, ambiguous, deviating, script, and hook cases. It is not a strict allowlist and not internal runtime state. You can write it by hand, commit it to the project, or let /comet-any create it after the first scan.

Xiaoyu calibrates prefer, require, advisory, strict, and real source evidence with a compass and balance scale

Preferences express direction and hard constraints; real Skill sources still have to be resolved, not guessed by name.

​
File location

.comet/skill-preferences.yaml
It sits next to .comet/config.yaml.

​
Full shape

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
Top-level keys are limited to version, mode, prefer, require, and policies. Unknown fields produce warnings. version must be 1.

​
mode

ModeBehaviorBest for
advisoryDefault. Can add goal-specific Skills if it explains the deviation.Individuals and small teams.
strictBlocks on missing required Skills, ambiguity, forbidden scripts/hooks, or preference deviation.Standardized teams.

​
prefer and require

prefer is an ordered list. /comet-any tries to respect it when composing a workflow. require lists Skills that must be satisfied. Missing or ambiguous required Skills block the plan.

​
policies

PolicyValuesDefaultMeaning
missingask / failaskAsk or fail when preferred Skills are missing.
ambiguousask / failaskAsk or fail when multiple sources match.
deviationexplain / failexplainExplain or fail when order is not followed.
scriptsallow / disclose / denydisclosePolicy for generated or distributed scripts.
hooksallow / disclose / denydisclosePolicy for generated or distributed hooks.
Use the example above if you are unsure. It prefers the Superpowers method chain and requires verification before completion.

​
Strict team example

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

​
How preferences affect generation

/comet-any uses preferences in this order:
  1. Read .comet/skill-preferences.yaml.
  2. If missing, scan platform Skill inventory and propose defaults.
  3. Resolve real local Skill content with find-skill.
  4. In advisory mode, add extra Skills when justified.
  5. In strict mode, block when required conditions are not met.
/comet-any must not infer capability from names alone. It must read the final candidate SKILL.md, direct references, rules, scripts, and hooks.

​
resolved-skills.json

Generated packages include source evidence: 
reference/resolved-skills.json
It records two things:
  • resolvedSkills: real Skill source, hash, status (available, missing, ambiguous).
  • workflow: node-to-Skill bindings, required Skill calls, and output schemas.
Review this file before publishing. It proves the composition was based on real local content and lets you trace each workflow node back to the Skill that implements it.

​
preferenceHash drift

Comet hashes the preference file and stores the preferenceHash in Skill Creator metadata. If preferences change after Factory initialization:
ModeDrift behavior
advisoryWarn and ask whether to continue or regenerate.
strictBlock until you choose continue or regenerate.

​
Next steps

Last modified on July 1, 2026