# Create, Evaluate, Publish, and Distribute a Skill with `/comet-any` This document only covers the recommended path for ordinary users in the current release: create, optimize, compose, evaluate, publish, and distribute a reusable Skill through `/comet-any`. Manually authoring `comet/skill.yaml`, `flow.yaml`, or Bundle state files is not the ordinary user path. ## One-line start Invoke this in your Agent surface: ```text /comet-any ``` Then describe the Skill you want to create or optimize. `/comet-any` is the Comet Skill creation guide: it reads project-level preferences, scans real local Skills, shows a composition proposal, and after confirmation generates a stable composed Skill Bundle that can be evaluated, reviewed, published, and distributed. Ordinary users only need to remember this path: ```text /comet-any create -> comet eval -> comet creator status/next -> comet publish review/approve/run -> comet publish distribute --preview -> comet publish distribute ``` `comet creator status` / `comet creator next` is the ordinary readiness and single-next-step entry. `comet publish` handles review, approval, publish, and distribution. `comet bundle` remains the Advanced Bundle backend for deterministic state, hashes, and deep debugging. `comet skill run` / `comet skill continue` is the advanced Engine Run debugging path. They are not the main entry point for ordinary users creating Skills. ## First-use project preferences The project-level preferences file lives at: ```text .comet/skill-preferences.yaml ``` It lives next to `.comet/config.yaml` and tells `/comet-any` which Skills this project prefers to reuse and how to handle missing, ambiguous, deviating, or executable candidates. If the file does not exist, `/comet-any` should first scan the Skills supported by Comet on the current platforms, group them by capability, and ask whether to save recommended preferences. The user does not need to retype a long Skill list every time. Writing `.comet/skill-preferences.yaml` always requires user confirmation first. Recommended starting point: ```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 ``` Field meanings: - `mode: advisory`: the default mode. It may add target-needed Skills, but must explain deviations. - `mode: strict`: team-standardized mode. Missing required Skills, ambiguity, or denied scripts/hooks block progress. - `prefer`: Skills the project prefers to reuse first; order is the preference priority. - `require`: Skills that must be satisfied when generating the composed Skill. - `policies.missing`: ask or fail when a preferred Skill is missing. - `policies.ambiguous`: ask or fail when a Skill name resolves to multiple sources. - `policies.deviation`: explain or fail when the plan deviates from preferences. - `policies.scripts` / `policies.hooks`: allow, disclose, or deny generated/distributed scripts/hooks. ## Hand-writing preferences Advanced users may edit `.comet/skill-preferences.yaml` directly. It is not an internal state file; it can be hand-written, committed to the project, or generated by `/comet-any` after the first scan. Example: create a more rigorous PR review Skill: ```yaml 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 ``` Then invoke: ```text /comet-any ``` Example goal: ```text Create a PR review assistant using the project-level preferences. It should clarify review scope first, then make a review plan, then execute the code review, and finally require verification evidence before completion. This Skill is meant for team reuse, not just the current task. ``` ## Composition proposal confirmation `/comet-any` must not write a Bundle draft immediately. It must first show a composition proposal and wait for user confirmation. The proposal must explain at least: - the new Skill name and target scenario - the Skills that will be reused, including source, hash, role, and call order - which candidates came from `prefer` and which from `require` - which candidates were added by target semantics - missing and ambiguous candidates - whether the plan deviates from preferred order, and why - what executable disclosures scripts/hooks introduce - which files will be generated The proposal should surface the user-facing summary, candidate actions, and `proposalHash`. The confirmation page must support at least: - `confirm-generate` - `revise-proposal` - `cancel` After user confirmation, `/comet-any` may write Skill Creator metadata. `proposalHash` is recorded and verified by metadata, not passed by the user as a CLI argument. The backend persists the normalized plan to `.comet/bundle-factory-plans//plan.json` and records `planHash`, `preferenceHash`, preference mode, policies, required Skills, resolved Skill evidence, and deviation reasons in Skill Creator metadata. If the proposal still has missing, ambiguous, or composition blockers, `/comet-any` should not confirm generation. When backend state is needed for candidate repair, it may temporarily store an unresolved Skill Creator state; after candidates and composition are resolved, it must show the generation-ready proposal again and record confirmation. Without that confirmation metadata, generation, review, and publish all refuse to continue. ## `/comet-any` output After a complete generation or optimization, output should look like: ```text / bundle.yaml skills// SKILL.md comet/ skill.yaml guardrails.yaml checks.yaml eval.yaml reference/ resolved-skills.json composition-report.md scripts/ rules/ hooks/ ``` Key files: - `SKILL.md`: the entry point the user actually invokes. - `reference/resolved-skills.json`: real Skill sources, hashes, summaries, selection reasons, and preference evidence. - `reference/composition-report.md`: proposal summary, deviation explanations, risk, and review evidence. - `comet/skill.yaml`: internal execution plan, not a hand-written user entry point. - `comet/guardrails.yaml`: constraints generated from preferences and risk policy. - `comet/checks.yaml`: completion and required-Skill checks. - `comet/eval.yaml`: Eval manifest. - `scripts/`, `rules/`, `hooks/`: the required control plane for stable composed Skill Bundles. ## Eval When `comet/eval.yaml` exists, start with the discovery precheck: ```bash comet eval ./generated-skill/comet/eval.yaml --collect ``` Then run the real evaluation and generate a browsable HTML report: ```bash comet eval ./generated-skill/comet/eval.yaml --html ``` Eval results must bind to the current draft hash. If current-hash eval evidence is missing, the eval fails, or eval is skipped, publish is blocked. ## Publish Before publishing, always review readiness. Ordinary users should let `/comet-any` drive the flow; for manual commands, prefer: ```bash comet creator status --json comet creator next --json comet publish review --platform --json comet publish approve --reviewer --json comet publish run --platform --json ``` The review summary must show: - `planHash` - `preferenceHash` - project-level preference mode and required Skills - resolved Skill evidence - composition proposal and deviation reasons - eval evidence - readiness, blockers, warnings, evidence - `Publish readiness:` - `User next steps:` Blocking cases include: - unresolved candidate - missing or ambiguous required Skill - preference drift in `strict` mode - missing current-hash eval evidence - missing current-hash human approval - required capability gap - unconfirmed executable disclosure ## Distribute After publish, `/comet-any` must ask the user whether to distribute. It must never distribute automatically. Before real execution, preview is mandatory: ```bash comet publish distribute --platform --scope project --preview --json ``` The user should first see: - `Distribution preview` - planned files - unsupported capability - executable disclosures - `No files were written` Only after user confirmation should the real command run: ```bash comet publish distribute --platform --scope project --json ``` If the target platform includes executable capabilities such as hooks or scripts, disclosures must be shown first. Only after user confirmation may the Skill add: ```bash --confirm-executables ``` If the user explicitly chooses to skip an optional capability, only then may the Skill add: ```bash --skip-capability ``` ## Resume an interrupted flow If the flow is interrupted halfway through, return and tell the Agent: ```text Continue the previous Skill creation ``` `/comet-any` should first scan resumable state and show the name, status, next action, blockers, and the last confirmed proposal summary. Resume checks include: - whether Skill Creator state exists - whether the draft hash changed - whether `.comet/skill-preferences.yaml` `preferenceHash` changed - whether resolved Skill hashes changed - whether eval evidence still matches the current hash - whether approval still matches the current hash Example resume copy: ```text resume summary Current step: review Suggested user command: comet creator next ``` If preferences or Skill sources changed, `advisory` mode should warn and let the user choose between continuing the old proposal or regenerating it. `strict` mode should block by default and require the user to confirm whether to continue or regenerate. ## Advanced backend reference Ordinary users usually let `/comet-any` call these commands. They exist for repairing candidate resolution, auditing authoring lanes, or explicit automation over the Skill Creator state. Use raw `comet bundle` commands only when you are debugging backend state directly. ```bash comet creator guide --project . --json comet creator propose --file --json comet creator init --file --json comet creator resolve --candidate --source --json comet creator init --file --confirmed-proposal --json comet creator generate --json comet creator authoring-plan --depth quick --json comet creator authoring-record --lane --file --json ``` `comet creator status` JSON includes the next action for `/comet-any` and automation. Ordinary users should read `comet creator status` / `comet creator next` for the user command. ## What the user needs to remember 1. `/comet-any` is the main entry point for creating, optimizing, and composing Skills. 2. `.comet/skill-preferences.yaml` is the project-level preference file; it may be hand-written or generated by `/comet-any`. 3. The composition proposal must be reviewed before a Bundle draft is written. 4. Eval is publish evidence, not the publish action itself. 5. Creator state uses `comet creator status` / `comet creator next` for the next step; publish and distribute stay under `comet publish`.