Skip to content

SKILL-CREATION.md

Latest commit

 

History

History
350 lines (267 loc) · 11.3 KB

SKILL-CREATION.md

File metadata and controls

350 lines (267 loc) · 11.3 KB
Raw

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:

/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:

/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:

.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:

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:

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:

/comet-any

Example goal:

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/<name>/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:

<bundle-draft>/
  bundle.yaml
  skills/<entry-skill>/
    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:

comet eval ./generated-skill/comet/eval.yaml --collect

Then run the real evaluation and generate a browsable HTML report:

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:

comet creator status <name> --json
comet creator next <name> --json
comet publish review <name> --platform <reference-platform> --json
comet publish approve <name> --reviewer <reviewer> --json
comet publish run <name> --platform <reference-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:

comet publish distribute <name> --platform <id> --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:

comet publish distribute <name> --platform <id> --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:

--confirm-executables

If the user explicitly chooses to skip an optional capability, only then may the Skill add:

--skip-capability <capability>

Resume an interrupted flow

If the flow is interrupted halfway through, return and tell the Agent:

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:

resume summary
Current step: review
Suggested user command: comet creator next <name>

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.

comet creator guide --project . --json
comet creator propose <name> --file <plan.json> --json
comet creator init <name> --file <plan.json> --json
comet creator resolve <name> --candidate <query> --source <root-or-hash> --json
comet creator init <name> --file <plan.json> --confirmed-proposal --json
comet creator generate <name> --json
comet creator authoring-plan <name> --depth quick --json
comet creator authoring-record <name> --lane <lane-id> --file <lane-output.json> --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.