Skill preferences and real sources

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

Mode	Behavior	Best for
`advisory`	Default. Can add goal-specific Skills if it explains the deviation.	Individuals and small teams.
`strict`	Blocks 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

Policy	Values	Default	Meaning
`missing`	`ask` / `fail`	`ask`	Ask or fail when preferred Skills are missing.
`ambiguous`	`ask` / `fail`	`ask`	Ask or fail when multiple sources match.
`deviation`	`explain` / `fail`	`explain`	Explain or fail when order is not followed.
`scripts`	`allow` / `disclose` / `deny`	`disclose`	Policy for generated or distributed scripts.
`hooks`	`allow` / `disclose` / `deny`	`disclose`	Policy for generated or distributed hooks.

Recommended starting point

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:

Read .comet/skill-preferences.yaml.
If missing, scan platform Skill inventory and propose defaults.
Resolve real local Skill content with find-skill.
In advisory mode, add extra Skills when justified.
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:

Mode	Drift behavior
`advisory`	Warn and ask whether to continue or regenerate.
`strict`	Block until you choose continue or regenerate.

Quickstart

Advanced

Related commands

Skill preferences and real sources

File location

Full shape

mode

prefer and require

policies

Recommended starting point

Strict team example

How preferences affect generation

resolved-skills.json

preferenceHash drift

Next steps

​File location

​Full shape

​mode

​prefer and require

​policies

​Recommended starting point

​Strict team example

​How preferences affect generation

​resolved-skills.json

​preferenceHash drift

​Next steps

File location

Full shape

mode

prefer and require

policies

Recommended starting point

Strict team example

How preferences affect generation

resolved-skills.json

preferenceHash drift

Next steps