Output and exit codes

This page is the contract for scripts, CI jobs, and AI agents that run skc. See Use SkillCatalog in scripts and CI.

• Where output goes
• JSON envelope
• Raw output
• Parse errors
• Exit codes
  • Codes every command can return
  • Codes shared by install, update, uninstall, and deliver
  • skc sync
  • skc deliver
  • skc install and skc profile install
  • skc update
  • skc init and skc profile init
  • skc uninstall and skc profile uninstall
  • skc validate and skc hook run
  • skc status
  • skc catalog
  • skc profile
  • skc settings
  • skc proposal
  • skc skill, skc stack, and skc bundle: list and show
  • Scoring and improvement commands
  • skc scoring providers

Where output goes

skc writes results to standard output and problems to standard error.

In text mode, most errors start with a line Error: <outcome>, followed by the message and a Hint: line with the next step. In scripts, use the exit code or JSON output instead of this text.

skc skill list, skc sync, skc profile add, skc install, and skc catalog add print their warnings in text mode only.

--quiet hides the success summary of skc sync, skc deliver, skc install, skc uninstall, skc update, skc init, skc validate, skc status, skc catalog add, and skc catalog remove. For skc catalog add, that includes the line that names the catalog's metrics address. The warning about an address it did not save still prints.

JSON envelope

With --json, a command prints one JSON object on one line: to standard output when it succeeds, and to standard error when it fails. The object always has the same six keys, in no fixed order. A few commands print raw JSON instead. See Raw output.

skc catalog policy show acme-skills --json

{"command":"catalog.policy.show","data":{"catalog_id":"acme-skills","sync_policy":{"mode":"direct"}},"error":null,"exit_code":0,"outcome":"catalog-policy","status":"ok"}

A command that fails fills error:

skc sync acme-skill --json

{"command":"sync","data":null,"error":{"details":null,"message":"catalog(s) not found: acme-skill","recovery_hint":"Choose registered catalog ids from `skc status` and rerun `skc sync`."},"exit_code":17,"outcome":"catalog-not-found","status":"error"}

A command with two names reports the one you ran: skc install reports install, and skc profile install reports profile.install. The same holds for uninstall and init. skc score-history reports skill.score-history.

skc proposal show, skc proposal discard, and skc hook run print some of their errors as plain text. With --json, those errors arrive with outcome set to internal-error, the command's own exit code, and the plain text in error.message. The tables below mark these outcome names "text only".

Raw output

These commands print their result without the envelope, even with --json:

Their errors still go to standard error. skc skill score, skc skill score-history, and skc skill improve print scoring failures as a JSON envelope even without --json. Problems with choosing the catalog print as text unless you pass --json.

Parse errors

When skc cannot parse its arguments, it prints the problem to standard error and exits 2. That covers an unknown command or flag, a missing or invalid value, and two flags that cannot be combined. Running skc with no command prints the help to standard error and also exits 2. --help and --version print to standard output and exit 0.

If the arguments include --json, the error is a JSON envelope on standard error, with command set to skc and outcome set to cli-parse-error:

skc settings enable vim --json

{"command":"skc","data":null,"error":{"details":{"parser_error_kind":"InvalidValue","rendered":"error: invalid value 'vim' for '<TARGET_ID>'\n  [possible values: claude-code, cursor, codex]\n\nFor more information, try '--help'."},"message":"error: invalid value 'vim' for '<TARGET_ID>'","recovery_hint":"Run `skc --help` for usage or `skc help-json` for the machine-readable command tree."},"exit_code":2,"outcome":"cli-parse-error","status":"error"}

Exit codes

0 means the command succeeded. Any other code means it failed or found a problem. The same number means different things in different commands. Read a code together with the command that returned it, or branch on outcome in JSON output.

Rows that ask you to run skc validate mean that a profile file (profile.yml) or a delivery record (delivery-manifest.json) in the SkillCatalog folder is damaged. See Report a problem.

Codes every command can return

skc completions and skc help-json return only these codes. When the reader closes the pipe early, as in skc help-json | head, skc help-json stops quietly and exits 0. Any other failure to write its output exits 70.

Codes shared by install, update, uninstall, and deliver

These codes mean the same in each command named in the row. The tables for those commands leave them out.

The <effect> part is one of local-yaml, local-privacy, installed-clear, profile-save, catalog, catalog-refresh, delivery-target, or delivery-manifest, and names what SkillCatalog had written.

skc sync

A failed catalog stops delivery for the whole run. For example, a catalog fails when:

• its Git host cannot be reached, or refuses the push. For a refused push, the catalog's report.push.message in JSON holds the host's reason.
• its pre-commit check refuses the commit.
• a pull conflicts. The message names every file that Git could not merge.
• its clone's own Git data is missing or damaged, so Git would use another repository. Nothing is committed or pushed.

A review-branch catalog also fails when:

• an edit cannot be merged onto the proposal already waiting for that item. The edit stays in the clone, uncommitted.
• the Git host refuses a proposal push. Edits from this run go back into the clone, uncommitted. Local commits on the primary branch stay there, and the next sync tries again.
• local commits on the primary branch conflict with new commits on origin. The message prints a git -C '<clone>' reset --soft <commit> command that stages only those local commits.
• its clone has an unfinished merge, rebase, or cherry-pick.

See Sync refuses one catalog and Local commits conflict with the Git host.

Sync delivers only when every selected catalog committed, pulled, and pushed. When that delivery reports a problem, skc sync exits 25, as skc deliver does, and data.result.delivery holds the report in JSON. Edited files that delivery kept are not a problem, so sync still exits 0 for them. With --json, when some reported files already match the catalog version, error.recovery_hint names skc deliver <profile-id> --adopt-matching.

When delivery stops with an error, data.result.delivery_error holds the outcome and exit code that skc deliver gives for that error. For example, when no profile could be delivered because a proposal's state is unknown, that is delivery-blocked-by-remote-status-unknown and 45.

In text mode, sync ends with one warning line for each synced catalog that has recovery files from syncs that did not finish. The warning does not change the exit code. See Recover unpublished changes.

skc deliver

skc deliver <profile-id> for a project profile whose checkout, or --target-dir folder, cannot be found exits 43 with profile-parent-path-invalid. The hint says to mount the folder. For a missing checkout, it also names skc profile delete <profile-id>; for a missing --target-dir folder, skc install --target-dir . run in the checkout. See A profile's folder cannot be found.

Partial delivery

When a profile or a skill cannot be delivered for one of the reasons in the table below, skc deliver withholds it, delivers the rest, and exits 25. A withheld skill keeps the files it delivered earlier. When no profile with entries could be delivered, the run instead exits with the error of the first withheld profile, such as bound-catalog-clone-missing (43), delivery-composition-gap (44), or delivery-blocked-by-remote-status-unknown (45). A profile with no entries does not count.

Only the reasons in the table withhold part of a run. Any other error stops the whole run for every profile, for example a special file or a file over 10 MiB in a skill folder, a Git-ignored SKILL.md, or an unreadable proposal record.

Each problem is a row in data.delivery.failures (data.preview.failures for a dry run), with the profile_id, the install_path, the reason, and the remedies that apply:

--adopt-matching takes over only files that are exactly what delivery would write. It never overwrites a file with different content. When some rows can be taken over, the text output and the JSON error.recovery_hint of skc deliver, skc install, skc update, and skc sync name the command.

skc install and skc profile install

skc install and skc update clone and register each catalog that the manifests declare and this machine has not registered. For each one they print Registered catalog '<catalog-id>' from <source> (declared in <manifest path>). on standard output, also with --quiet, and also when the run fails afterwards. When the catalog names a metrics address, the next line names it too.

The JSON output of a successful skc install, or of skc update without --check, always has data.registered_catalogs. It lists these catalogs and is empty when there are none. When the run fails after registering a catalog, error.details.registered_catalogs lists it instead. Each entry has catalog_id and source, and metrics_url when the catalog names a metrics address.

skc update

skc update --check does not pull catalogs, so it never returns 42.

When skc update cannot register a declared catalog, it reports catalog-refresh-failed (42). A declared id that differs from the id of the cloned catalog reports manifest-malformed (11) instead.

skc init and skc profile init

skc uninstall and skc profile uninstall

skc validate and skc hook run

skc hook run, which a catalog's pre-commit hook calls, runs skc validate --path <clone> --warnings-ok --no-drift and returns the same codes. Edited delivered copies therefore never block a commit.

skc validate --profiles reports profile-slug-conflict, an error, when two entries of one profile deliver different skills with the same slug.

skc status

skc catalog

skc catalog add checks --metrics-url while it reads its arguments, so an invalid address is a parse error, and nothing is cloned.

skc profile

skc profile add, remove, and reorder exit 0 when the profile changed, even if the delivery that follows fails. They print the warning after the success message, and JSON output holds it in data.delivery_warning. When no AI tool is turned on, skc profile add and skc install also print a warning on standard error that nothing was delivered.

skc settings

An unknown tool id is a parse error, and so is skc settings telemetry with both --enable and --disable.

With --json, skc settings telemetry returns data.enabled and data.metrics_catalogs. That is one {catalog_id, name, metrics_url} object for each catalog with a metrics address, or null when the registered catalogs cannot be read.

skc proposal

skc skill, skc stack, and skc bundle: list and show

skc skill list leaves out a skill it cannot read, such as one whose front matter lacks description, and still exits 0. Text output prints one warning line on standard error for each such skill, also with --quiet. JSON output lists them in invalid_items, each with slug, path, and error. skc validate still reports the skill. See A skill is missing from the list.

Scoring and improvement commands

These codes apply to skc skill score, skc skill score-history, skc score-history, skc skill improve, and skc skill publish-accepted.

skc scoring providers