comet publish

comet publish is the user-facing entry for releasing /comet-any artifacts. Once eval evidence is ready, it handles review, approval, publishing, and distribution. Creation state, recovery, and “what to do next” are handled by comet creator. The intended way to work is:

/comet-any creates, recovers, and optimizes the Skill
comet eval validates the generated output
comet creator status / comet creator next are the entry points for normal users to check readiness and what to run next
comet publish handles review, human approval, publish, and distribution

comet publish is a thin facade over the comet bundle backend. Every publish subcommand delegates to the corresponding bundle function. Normal users use publish; use bundle directly only for auditing or troubleshooting.

Subcommands

Command	Purpose	Required arguments
`comet publish review <name>`	Generate a pre-publish review summary	`<name>`, `--platform`
`comet publish approve <name>`	Approve the candidate at the current hash	`<name>`, `--reviewer`
`comet publish run <name>`	Publish the approved candidate	`<name>`, `--platform`
`comet publish distribute <name>`	Distribute the published candidate to a platform	`<name>`, `--platform`

Every subcommand supports --json.

comet publish has no reject subcommand. approve is the only approval entry for users, and internally records this review with a fixed outcome of approved. To reject, use the advanced comet bundle review <name> —reject —reviewer <name>.

The publishing phase runs review → approve → run → distribute. The authoritative description of the state machine, readiness conclusions, and blocker codes is in Publishing and distributing Skills.

Full example

# Read the full readiness and blockers
comet creator status review-helper --project . --json

# Only want to know the next command to run
comet creator next review-helper --project . --json

# Generate a review summary
comet publish review review-helper --platform claude --json

# Human approval
comet publish approve review-helper --reviewer alice --json

# Publish the approved candidate
comet publish run review-helper --platform claude --json

# Distribution preview (mandatory)
comet publish distribute review-helper --platform claude --scope project --preview --json

# Real distribution
comet publish distribute review-helper --platform claude --scope project --json

Common options

Option	Description
`--project <dir>`	Project root (default `.`)
`--json`	Output structured JSON
`--platform <id>`	Target platform (repeatable)
`--scope <project\|global>`	Distribution scope
`--reviewer <name>`	Reviewer (required for `approve`)
`--locale <locale>`	Language
`--overwrite`	Overwrite an existing publish candidate (`run`) or existing distribution (`distribute`)
`--preview`	Distribution preview
`--confirm-executables`	Confirm executable disclosure
`--skip-capability <cap>`	Skip an optional capability (repeatable)

Only want the next step: comet creator next

comet creator status gives you the full readiness conclusion and blockers. If you only want to know which single command to run now, use comet creator next — it prints one recommended next step and exposes no backend Bundle commands:

comet creator next review-helper --project . --json

The text output looks roughly like this:

Next step for review-helper
Status: draft
Current step: review
Action: request-review
Command: comet publish review review-helper --platform claude --json
Reason: Current draft hash is missing review approval
Requires confirmation: yes

The --json mode additionally returns structured fields:

Field	Meaning
`status` / `currentStep`	The candidate’s current status and stage
`nextStep.action` / `nextStep.label`	The category of the recommended action and a human-readable label
`nextStep.command`	The command you should run directly (arguments already filled in)
`nextStep.reason`	Why this step is recommended
`nextStep.requiresUserConfirmation`	Whether you must confirm first (e.g., approve, distribute)
`preferenceDrift.changed`	Whether the project Skill preferences drifted after this flow started

comet creator next is for resuming an interrupted /comet-any flow: it translates the backend Bundle’s next action into one user command, so you never have to read internal state. When preference drift ( preferenceDrift.changed) is true, advisory mode warns and strict mode blocks by default — you decide whether to keep the old plan or regenerate.

Distribution preview is mandatory

Before performing a real distribution, you must run the preview first:

comet publish distribute review-helper --platform claude --scope project --preview --json

The preview shows:

Install preview and planned files
Unsupported capabilities
Executable disclosures
No files were written

Only after you confirm the preview results may you remove --preview and run the real distribution.

Handling executable disclosure and capability gaps

If the target platform includes executable capabilities such as hooks or scripts:

comet publish distribute review-helper --platform claude --scope project --confirm-executables --json

If you explicitly choose to skip an optional capability:

comet publish distribute review-helper --platform claude --scope project --skip-capability <capability> --json

Capability type	How the gap is handled
Required capability gap	Cancel that platform; it cannot be skipped
Optional capability gap	You must explicitly choose to skip it
Hook/script disclosure	You must confirm it before distribution

hooks/*.yaml are Comet portable hook descriptors; they take effect only after comet publish distribute compiles them into the target platform configuration.

Next steps

Publishing and distributing Skills — readiness state chain and gates in detail
comet creator — creation state, recovery, and the unique next step
comet bundle — the advanced Bundle backend
comet eval — the evidence entry before publishing

Install and health checks

Skills, evals, and publishing

Core scripts

Subcommands

Full example

Common options

Only want the next step: comet creator next

Distribution preview is mandatory

Handling executable disclosure and capability gaps

Next steps

​Subcommands

​Full example

​Common options

​Only want the next step: comet creator next

​Distribution preview is mandatory

​Handling executable disclosure and capability gaps

​Next steps

Subcommands

Full example

Common options

Only want the next step: comet creator next

Distribution preview is mandatory

Handling executable disclosure and capability gaps

Next steps