CLI reference

This page lists every skc command with its arguments and notes on output, side effects, follow-on behavior, and exit status. It is generated from the help text built into skc. Run skc <command> --help to read the same notes in a terminal, or skc help-json to get them as JSON.

In usage lines, <VALUE> is required, [VALUE] is optional, and ... means the argument can be repeated. Exit codes and the JSON envelope are described in Output and exit codes.

Global options

These options work with every command, before or after the command name.

skc [OPTIONS] <COMMAND>

Commands

skc init

Alias for skc profile init, with the same arguments and behavior.

skc install

Alias for skc profile install, with the same arguments and behavior.

skc uninstall

Alias for skc profile uninstall, with the same arguments and behavior.

skc update

Refresh only the catalogs and project profile of the checkout where you run it.

skc update [OPTIONS]

This command reads .skillcatalog/skillcatalog.yml only from the folder where you run it. A root-level skillcatalog.yml is read when .skillcatalog/skillcatalog.yml is absent; having both is an error. It does not search parent folders for a manifest. It fails when this folder has no team manifest, when that manifest is malformed, or when no project profile is installed for this checkout. It never installs a profile and never syncs other catalogs. A catalog the manifests declare that this machine has not registered yet is cloned and registered first, as a first install does, and the output names it.

Use --check to report how many files delivery would create, update, or remove in this checkout, without syncing catalogs or applying delivery.

Output

• By default this command prints the refresh result of each catalog, plus a summary of the delivery for this profile.
• --check is read-only and prints how many files delivery would create, update, or remove in this checkout for its project profile; --json also lists each planned action with its path.
• --json returns the standard SkillCatalog JSON envelope; with --check, its data includes mode: "check", needs_update, and create/update/remove counts.

Side effects

• Successful runs pull upstream catalog changes for the catalogs this checkout's manifests declare and refresh the checkout's project profile.
• --check is read-only: it does not write log files, tidy the SkillCatalog folder, sync catalogs, deliver, or lock delivery records.

Follow-on behavior

• Each run then delivers the refreshed profile, and only that profile, right away.
• --check does not repair anything. Run skc update to apply the changes it reports.
• If delivering the profile reports conflicts or failed writes, the command exits non-zero with delivery-failed.

Exit status

• This command exits non-zero, without installing anything, when no project profile is installed for the checkout.
• --check exits non-zero with update-needed when the selected checkout would create, update, or remove delivered files, and with delivery-blocked when nothing is pending but drifted files or files SkillCatalog did not write block delivery.
• --check exits non-zero with delivery-failed when delivery would withhold a skill or the profile, and lists what it would withhold.
• update-needed and delivery-blocked both exit 24 in skc update. The same exit code can mean different things in different commands, so scripts should check the JSON command and outcome fields.
• --check only reports this checkout's pending delivery changes; it does not check other installed profiles.
• This command exits non-zero when delivering the profile reports conflicts or failed writes.

skc sync

Sync registered catalogs (optional commit, pull, push, deliver).

skc sync [OPTIONS] [CATALOG_ID]...

Bidirectional sync across registered catalogs.

For each registered catalog (or the named subset), sync first commits pending changes when you give a message (--message, or an interactive prompt), then pulls, then pushes, and finally runs delivery once for every profile unless --no-deliver is set. On a review-branch catalog, commits go to proposal branches, and the primary branch is never pushed.

Dirty-tree handling:

• With --message <msg>: commit pending changes, then pull, push, deliver.
• Interactive terminal, no --message: reviews each dirty writable catalog and prompts for its own commit message; empty input or end of input cancels the whole sync with exit 0 and says that nothing was synced.
• stdin or stdout is not a terminal, no --message: refuses with the typed dirty-tree envelope at exit 33.

Commit-message validation:

• Empty --message "" is rejected with empty-message at exit 10.
• Trimmed messages whose byte length exceeds 1000 are rejected with commit-message-too-long at exit 11.

Before a commit (with --message, or before a prompt), sync refuses with missing-config at exit 12 when git config user.email or user.name is unset. A sync that only pulls needs neither.

Output

• By default this command prints per-catalog results and any delivery follow-up summary.
• --json returns the standard SkillCatalog JSON envelope with per-catalog reports and command: "sync".

Side effects

• Successful syncs update the local clone of each requested catalog.
• When --message <msg> is supplied, each requested catalog with uncommitted changes is committed before the pull and push; the Essentials catalog is never committed to, even when it has changes.
• Every commit created via --message <msg> lands with a subject prefixed by [skillcatalog] so SkillCatalog's commits are easy to find in the catalog's Git history.
• On a review-branch catalog, commits on the primary branch that origin lacks are pushed as a new proposal branch, and the primary branch then returns to origin/<primary>.

Follow-on behavior

• Unless --no-deliver is set, successful syncs automatically rerun skc deliver for every profile. Delivery runs only when every requested catalog synced.
• If delivery fails with an error after an otherwise complete sync, for example because SkillCatalog could not check a review-branch catalog's proposals on the Git host, the command exits non-zero with delivery-failed. Delivery conflicts and failed writes make the command exit non-zero with delivery-failed.

Exit status

• With no registered catalogs, sync exits 0 with outcome: "no-catalogs"; unknown requested catalog ids exit non-zero with catalog-not-found before sync starts.
• --message "" exits non-zero with empty-message; messages over 1,000 bytes exit non-zero with commit-message-too-long.
• When a commit is about to happen (--message is supplied, or sync is about to prompt for a message) and Git user.email or user.name is unset, the command exits non-zero with missing-config.
• When a catalog has uncommitted changes, --message is not supplied, and standard input or standard output is not a terminal, the command refuses with dirty-tree and exit code 33 without committing or pushing.
• When another sync or save is already running on the same catalog, or another Git operation holds its index lock, the command exits non-zero with another-sync-running.
• When the commit of any catalog fails (for example, because its pre-commit hook fails), the other catalogs are skipped; their message reads "Skipped after peer catalog failed earlier in the run.", and sync exits non-zero.
• When any requested catalog fails to sync, the command exits non-zero (sync-partial or sync-all-failed) and skips delivery.
• When the Git host refuses the proposal push of a sync commit, or a change cannot be merged onto its waiting proposal, the command exits non-zero and puts those changes back in the catalog folder, uncommitted. When it refuses the proposal for local commits on the primary branch, the commits stay there and the next sync retries.
• When local commits on a review-branch catalog conflict with new commits on origin, the command exits non-zero, skips delivery, and prints a git -C <clone> reset --soft <commit> command that stages only those local commits.

skc deliver

Deliver profiles to the enabled delivery targets, without pulling or pushing catalogs.

skc deliver [OPTIONS] [PROFILE_ID]

This command is local-apply only and never touches Git. To pull upstream catalog changes and run delivery, use skc sync.

Flags:

• --dry-run: compute the delivery report without writing files.
• --check: only check for drift between delivered files and the manifest. Exits non-zero (26) when drift is detected.
• --adopt-matching: take over existing files that already match what delivery would write, such as after the delivery record was lost. Use skc deliver <PROFILE_ID> --adopt-matching for one profile. Files with different content are never overwritten. Cannot be combined with --dry-run or --check.

Without --adopt-matching, delivery never takes over a file it did not write: an existing file at a delivery path is reported as unmanaged_target_exists and the command exits 25.

When some profiles or skills cannot be delivered, such as a profile entry that does not resolve, a missing checkout, a symbolic link in a skill folder, or a catalog whose proposal state is unknown, the healthy profiles and skills are still delivered, the rest are listed, and the command exits 25. Withheld skills keep the files they delivered earlier. The command exits 43, 44, or 45 only when no profile with entries could be delivered.

Positional PROFILE_ID is optional; when omitted every profile is delivered.

Output

• Execute mode writes enabled target files and prints the delivery summary.
• --dry-run computes the delivery report without writing files.
• --check inspects drift without changing files.
• --json returns the standard SkillCatalog JSON envelope with command: "deliver" in every delivery mode.

Side effects

• Execute mode writes or removes files under enabled delivery targets; this command never pulls, commits, or pushes catalog changes.
• --dry-run and --check do not write or remove delivered files.

Follow-on behavior

• To pull upstream catalog changes and run delivery in the same step, use skc sync instead of skc deliver.

Exit status

• --check exits non-zero when drift is found.
• --dry-run and --check cannot be combined.
• Execute mode exits non-zero for delivery conflicts, delivery failures, or composition failures.

skc profile

Manage profiles and team manifests.

skc profile [OPTIONS] <COMMAND>

skc profile list

List every known profile.

skc profile list [OPTIONS]

skc profile show

Show one profile's name, folder, and entries.

skc profile show [OPTIONS] <PROFILE_ID>

skc profile create

Create a personal profile for one folder.

skc profile create [OPTIONS] <NAME> <DIRECTORY>

--entry is repeatable and accepts KIND:CATALOG_ID:SLUG. Each --entry adds one entry to the new profile; the referenced catalog id must already be registered with SkillCatalog and have a ready local clone. Supplying an --entry whose catalog id is not registered or not ready fails the whole command and saves no profile.

Output

• By default this command prints the created profile id, display name, and folder.
• --json returns the created profile in the standard SkillCatalog JSON envelope.

Side effects

• Successful runs save the profile in the SkillCatalog folder.

Exit status

• This command exits non-zero for invalid profile names, unsafe folders, id conflicts, unreadable profile files, or catalogs that are not ready, including --entry catalog ids that are not registered or have no ready local clones.

skc profile delete

Delete a profile and the skills it delivered.

skc profile delete [OPTIONS] <PROFILE_ID>

Output

• By default this command prints the deleted profile id and delivery cleanup summary.
• --json returns the deleted profile id plus cleanup report in the standard SkillCatalog JSON envelope.

Side effects

• Successful runs remove the profile from the SkillCatalog folder.
• Successful runs clean delivered files that belonged to the deleted profile.

Exit status

• This command exits non-zero when the profile cannot be deleted, when the Home profile is selected, or when delivery cleanup fails.

skc profile add

Add one entry to a profile.

skc profile add [OPTIONS] --kind <KIND> --slug <SLUG> --catalog-id <CATALOG_ID> <PROFILE_ID>

Output

• By default this command prints a summary of the change and any delivery warning.
• --json returns the updated profile and any delivery warning in the standard JSON envelope.

Side effects

• For the Home profile and personal profiles, this command rewrites the profile's file in the SkillCatalog folder.
• For a project profile, it writes the change to the local manifest, .skillcatalog/skillcatalog.local.yml, in the profile's checkout, and makes sure Git ignores that file.

Follow-on behavior

• After the change, SkillCatalog automatically reruns delivery for that profile and reports delivery conflicts, failed writes, or preserved edited files as warnings in the success output.

Exit status

• This command exits non-zero for missing profiles, invalid entries, or catalog clones that cannot be read.

skc profile remove

Remove one entry from a profile.

skc profile remove [OPTIONS] --kind <KIND> --slug <SLUG> --catalog-id <CATALOG_ID> <PROFILE_ID>

Output

• By default this command prints a summary of the change and any delivery warning.
• --json returns the updated profile and any delivery warning in the standard JSON envelope.

Side effects

• For the Home profile and personal profiles, this command rewrites the profile's file in the SkillCatalog folder.
• For a project profile, it writes the change to the local manifest, .skillcatalog/skillcatalog.local.yml, in the profile's checkout, and makes sure Git ignores that file.

Follow-on behavior

• After the change, SkillCatalog automatically reruns delivery for that profile and reports delivery conflicts, failed writes, or preserved edited files as warnings in the success output.

Exit status

• This command exits non-zero for missing profiles, invalid entries, or catalog clones that cannot be read.

skc profile reorder

Replace a profile's entry ordering.

skc profile reorder [OPTIONS] --catalog-id <CATALOG_ID> --entry <KIND:CATALOG_ID:SLUG> <PROFILE_ID>

Output

• By default this command prints the reorder summary and any delivery warning.
• --json returns the updated profile and any delivery warning in the standard JSON envelope.

Side effects

• For the Home profile and personal profiles, this command rewrites the profile's file in the SkillCatalog folder with the --entry order exactly as provided.
• For a project profile, it writes the new order to the local manifest, .skillcatalog/skillcatalog.local.yml, in the profile's checkout, and makes sure Git ignores that file.

Follow-on behavior

• After the reorder, SkillCatalog automatically reruns delivery for that profile and reports delivery conflicts, failed writes, or preserved edited files as warnings in the success output.

Exit status

• This command exits non-zero for missing profiles, badly formed --entry values, or catalog clones that cannot be read.
• --entry is required; without it, the command fails while the arguments are parsed. Reorder cannot delete entries. Use profile remove to remove individual entries.

skc profile init

Create the team manifest, .skillcatalog/skillcatalog.yml, in the folder where you run it.

skc profile init [OPTIONS]

This command does not search parent folders or use any other folder. It fails if this folder already contains .skillcatalog/skillcatalog.yml or a root-level skillcatalog.yml. --source accepts remote Git URLs only. Sources must not include passwords, tokens, query strings, or fragments.

--catalog-id is repeatable. When a --catalog-id is supplied without a paired --source, the URL comes from the registered catalog with that id. An unregistered catalog id without a paired --source is a user-input error.

--source is repeatable and positionally paired with the --catalog-id values: the i-th --source pairs with the i-th --catalog-id. Supply a remote Git URL.

Missing values are asked for only in a terminal. Without a terminal on standard input, or with --json, pass --catalog-id, --id, and --display-name; otherwise the command fails at once and names the missing flags.

Output

• By default this command prints the manifest path it wrote.
• --json returns the standard SkillCatalog JSON envelope.

Side effects

• Successful runs create .skillcatalog/skillcatalog.yml in the folder where you run the command.

Exit status

• This command exits non-zero when the current folder is not usable, when that folder already has a team manifest, when the manifest cannot be written, when the catalog source is not a remote Git URL without passwords, tokens, query strings, or fragments, or when required flags are missing and there is no terminal to ask for them.

skc profile install

Install the project profile for the checkout where you run it, refreshing declared catalogs that are already registered.

skc profile install [OPTIONS]

This command reads .skillcatalog/skillcatalog.yml only from the folder where you run it. A root-level skillcatalog.yml is read when .skillcatalog/skillcatalog.yml is absent; having both is an error. It does not search parent folders for a manifest. It fails when this folder has no team manifest, when that manifest is malformed, or when profiles already on this machine conflict with it.

Delivery destination: --target-dir PATH selects an existing folder to deliver into. Relative paths resolve from the folder where you run the command; the resolved absolute path is saved only with the project profile in the SkillCatalog folder. Enabled tools keep their standard .agents/skills, .claude/skills, and .cursor/skills folders below it. Source manifests always come from the checkout where you run the command, even when the destination has its own manifest. Later installs without the flag, delivery, and updates reuse the saved destination. Without a saved override, delivery stays in the source checkout. Passing another destination moves the same profile there. Delivery removes obsolete delivered files you did not edit, and keeps edited files and files SkillCatalog did not write. A failed delivery can leave the new destination saved and some files changed; rerun after fixing the reported problem. Uninstall from the source checkout removes the delivered files, except edited ones.

Catalog refresh: a repeated install, or a first install whose declared catalogs were all already registered, refreshes those catalogs from their upstream sources before delivery; a first install that clones a catalog does not refresh anything. A declared catalog that this machine has not registered is cloned and registered, on a repeated install as on a first one, and the output names each catalog it registered. Only the catalogs this checkout's team and local manifests declare are refreshed, never every registered catalog. Each qualifying run fetches per declared catalog, so it needs network access to those sources; a failed refresh stops the install with catalog-refresh-failed instead of delivering stale content.

Output

• By default this command prints a summary of the install and of the delivery for this profile.
• --json returns the standard SkillCatalog JSON envelope.

Side effects

• Successful installs create or refresh the checkout's project profile in the SkillCatalog folder.
• --target-dir PATH saves an existing folder as the project profile's delivery destination; relative paths resolve from the checkout and are saved as absolute paths. Source manifests still come from that checkout.
• Later installs without the flag, delivery, and updates reuse the saved destination. Enabled tools keep their standard skills folders. A different destination moves the same profile there, removing obsolete delivered files you did not edit and keeping edited files and files SkillCatalog did not write.
• A repeated install, or a first install whose declared catalogs were all already registered, updates those catalogs' clones from their upstream sources; a first install that clones a catalog does not.

Follow-on behavior

• Qualifying installs refresh the catalogs this checkout's team and local manifests declare, never every registered catalog, before delivery reads them.
• Each install then delivers the installed profile, and only that profile, right away.
• If that delivery reports conflicts or failed writes, the command exits non-zero with delivery-failed.

Exit status

• This command exits non-zero for missing or malformed manifests, missing catalog content, profile conflicts, or delivery failures.
• A target that is empty, missing, or not a folder exits with target-directory-invalid before profile save or destination writes. A failed delivery can leave the saved destination and partial file changes available for retry.
• A declared catalog that cannot be refreshed exits non-zero with catalog-refresh-failed before any profile is saved or delivered.

skc profile uninstall

Remove the project profile for the checkout where you run it.

skc profile uninstall [OPTIONS]

This command removes the project profile installed for the folder where you run it. It does not search parent folders for a profile. It fails when no project profile is installed for this checkout.

Output

• By default this command prints a summary of the removed project profile and the delivered files it removed.
• --json returns the standard SkillCatalog JSON envelope.

Side effects

• Successful uninstalls remove this checkout's project profile from the SkillCatalog folder.

Follow-on behavior

• Successful uninstalls clean delivered files that belong only to the removed profile.

Exit status

• This command exits non-zero when no installed profile matches the checkout, when checkout ownership is inconsistent, or when delivery cleanup fails.

skc settings

Inspect or update application settings.

skc settings [OPTIONS] <COMMAND>

skc settings show

Show the current settings.

skc settings show [OPTIONS]

skc settings list

Alias for skc settings show, with the same arguments and behavior.

skc settings enable

Enable a delivery target.

skc settings enable [OPTIONS] <TARGET_ID>

Output

• By default this command prints whether the delivery target is now on or off, and any delivery warning.
• --json returns the target id, its new enabled value, any delivery warning, and the updated settings, in the standard SkillCatalog JSON envelope.

Side effects

• Successful runs save whether the delivery target is on or off in settings.toml.

Follow-on behavior

• After saving settings, SkillCatalog attempts delivery for all profiles and reports delivery conflicts, failed writes, or preserved edited files as warnings while keeping the settings change.

Exit status

• This command exits non-zero for unsupported target ids, or when settings.toml cannot be saved.

skc settings disable

Disable a delivery target.

skc settings disable [OPTIONS] <TARGET_ID>

Output

• By default this command prints whether the delivery target is now on or off, and any delivery warning.
• --json returns the target id, its new enabled value, any delivery warning, and the updated settings, in the standard SkillCatalog JSON envelope.

Side effects

• Successful runs save whether the delivery target is on or off in settings.toml.

Follow-on behavior

• After saving settings, SkillCatalog attempts delivery for all profiles and reports delivery conflicts, failed writes, or preserved edited files as warnings while keeping the settings change.

Exit status

• This command exits non-zero for unsupported target ids, or when settings.toml cannot be saved.

skc settings telemetry

Inspect or change shared usage metrics.

skc settings telemetry [OPTIONS]

Inspect or change shared usage metrics for the SkillCatalog desktop app and skc.

A catalog's owner can name a metrics address in the catalog's catalog.yaml. While usage metrics are on, SkillCatalog sends anonymous usage counts to that address. Metrics contain command outcomes and durations, and counts about that catalog and its skills, stacks, and bundles, named by id and slug. Counts about catalogs without an address are never sent.

Usage metrics are on by default. With no flag, this command shows the switch and the catalogs that declare a metrics address.

skc catalog

Manage registered catalogs and their sync policy.

skc catalog [OPTIONS] <COMMAND>

skc catalog add

Register and clone a catalog from a remote Git URL.

skc catalog add [OPTIONS] <URL>

This command accepts only remote Git URLs via SSH, ssh://, or HTTP(S) without passwords, tokens, query strings, or fragments.

Output

• By default this command prints the added or already-registered catalog and its clone path when known.
• --json returns the catalog registration in the standard SkillCatalog JSON envelope.
• When SkillCatalog does not save the --metrics-url address, it prints a warning on standard error, and --json holds it in data.metrics_url_warning.

Side effects

• Successful fresh additions register the catalog and clone it into the SkillCatalog folder, under catalogs/.
• When the remote repository is empty, a fresh addition also writes starter files (catalog.yaml, README.md, and skills, stacks, and bundles folders), commits them, and pushes that commit.
• With --metrics-url, adding an empty repository also writes the address into the new catalog.yaml as metrics_url.
• Fresh additions add SkillCatalog's pre-commit hook to the clone, which checks each commit to the catalog without the drift checks.
• SkillCatalog rewrites its own block in that hook when it syncs or saves the catalog, so the hook runs the current skc; a hook without SkillCatalog's markers is left alone.
• Adding a source that is already registered changes nothing.
• For a repository that already has a catalog, or a source that is already registered, --metrics-url saves nothing. The add runs as it would without the flag, and SkillCatalog prints a warning.

Exit status

• This command exits non-zero for non-remote sources, sources with passwords, tokens, query strings, or fragments, clone failures, unreadable clones, or registry conflicts.

skc catalog list

List registered catalogs.

skc catalog list [OPTIONS]

skc catalog remove

Unregister a catalog by id.

skc catalog remove [OPTIONS] <CATALOG_ID>

Output

• By default this command prints the removed catalog and whether the clone was removed or kept.
• --json returns the removed catalog plus kept_clone and clone_removed fields in the standard SkillCatalog JSON envelope.

Side effects

• Successful runs unregister the catalog.
• By default this command removes the catalog's clone folder when the registration records one.
• --keep-clone leaves the clone folder on disk after unregistering.
• Removing a catalog deletes its local folder, including changes not yet synced; --keep-clone keeps the folder.

Exit status

• This command exits non-zero with catalog-remove-in-use when any profile still uses the catalog: through its own entries, its checkout's local manifest, or its team manifest.
• The refusal lists one skc profile remove <profile-id> --kind <kind> --slug <slug> --catalog-id <id> command per entry, including entries in a checkout's local manifest. A catalog that a team manifest declares stays in use after its entries are excluded, until skc uninstall runs in that checkout.
• Rerun with --force to unregister anyway. Profiles with entries from the catalog are not delivered until those entries are removed; other profiles still deliver, and delivery exits non-zero.
• This command exits non-zero for unknown catalog ids or when the clone folder cannot be deleted safely.

skc catalog stats

Count readable skills, stacks, and bundles in one catalog.

skc catalog stats [OPTIONS] <CATALOG_ID>

skc catalog changes

Show pending local changes across registered catalogs.

skc catalog changes [OPTIONS] [CATALOG_ID]...

skc catalog policy

Show or change a catalog's sync policy.

skc catalog policy [OPTIONS] <COMMAND>

skc catalog policy show

Show a catalog's sync policy.

skc catalog policy show [OPTIONS] <CATALOG_ID>

skc catalog policy set

Set a catalog's sync policy.

skc catalog policy set [OPTIONS] <CATALOG_ID> <COMMAND>

skc catalog policy set direct

Pull and push SkillCatalog commits on the same branch.

skc catalog policy set <CATALOG_ID> direct [OPTIONS]

skc catalog policy set review-branch

Pull from primary and push each change as a proposal on its own branch.

skc catalog policy set <CATALOG_ID> review-branch [OPTIONS] --primary <PRIMARY> --review <REVIEW>

skc proposal

Manage active local proposal records and remote-only branches.

skc proposal [OPTIONS] <COMMAND>

skc proposal list

List active local proposal records.

skc proposal list [OPTIONS]

skc proposal show

Show one proposal record by id.

skc proposal show [OPTIONS] <PROPOSAL_ID>

skc proposal refresh

Check one or every active proposal on the Git host and update its record.

skc proposal refresh [OPTIONS] [PROPOSAL_ID]

skc proposal discard

Discard an active proposal record (transitions to Discarded).

skc proposal discard [OPTIONS] <PROPOSAL_ID>

skc proposal verify-clean

Check the local setup that proposals need in registered catalog clones.

skc proposal verify-clean [OPTIONS] [CATALOG_ID]

skc skill

Inspect, score, and improve skills in registered catalogs.

skc skill [OPTIONS] <COMMAND>

skc skill list

List skills from every registered catalog, or from one catalog.

skc skill list [OPTIONS] [CATALOG_ID]

Without a filter, the command lists every registered catalog, one group per catalog. Pass --catalog-id <CATALOG_ID> to list only that catalog.

A positional CATALOG_ID also works as an alias for --catalog-id. Supplying both the positional and --catalog-id with different values is a user-input error.

A skill that cannot be read is left out of the list and does not stop the listing: text output prints a warning line for it on standard error, and --json lists it under invalid_items with its slug, path, and error. skc validate still reports it.

skc skill show

Show one skill from a registered catalog.

skc skill show [OPTIONS] <ARGS>...

Use either the positional form skc skill show <CATALOG_ID> <SLUG> or the explicit flag form skc skill show <SLUG> --catalog-id <CATALOG_ID>.

The catalog id must match a registered catalog; unknown ids fail with catalog-not-found.

skc skill score

Score one skill from a catalog.

skc skill score [OPTIONS] <SLUG>

Output

• On success, this command prints its result as raw JSON to standard output.
• Successful scoring output contains the appended history plus the new_run_id for the run that just completed, and may include provider_failures when one or more providers failed after another provider succeeded.
• It can also include provider_warnings, which lists AI providers that failed while another succeeded, and AI provider text that SkillCatalog cleaned up before using it.
• --quiet prints the same JSON and hides the AI provider's progress and output.
• Successful scoring output does not use the standard SkillCatalog JSON envelope, even when --json is present.
• --json also hides the AI provider's progress and output, so --quiet --json prints the same as --json.
• Scoring rates the skill against a rubric built into SkillCatalog, using the AI providers enabled in settings.toml.
• --catalog-id selects a registered catalog explicitly; when omitted, the catalog last chosen in the desktop app is used.
• Failures print a JSON error envelope on standard error, even without --json. Problems choosing the catalog print as plain text unless --json is present. The command fails only when no AI provider's result can be saved, or another check fails.

Side effects

• Successful runs add the run to the skill's SCORE.json, with the scores of the AI providers that succeeded.
• This command does not modify SKILL.md or other catalog source files.

Exit status

• This command exits non-zero when no catalog can be selected, when the selected catalog clone is unreadable, when the selected catalog is the Essentials catalog, which is read-only, when no enabled AI provider is usable, when every AI provider that runs fails, when the skill is a single file such as skills/review-checklist.md or skills/review-checklist.yaml, which scoring does not support (move it to skills/review-checklist/SKILL.md and retry), or when a scoring run for the same catalog and skill is already in progress.

skc skill improve

Generate, save, or apply a scored improvement proposal for one skill from a catalog.

skc skill improve [OPTIONS] [SLUG]

Output

• By default this command prints a scored improvement proposal: the AI provider and model, the old score, the new score, the change, any AI provider warnings, and the diff between the current SKILL.md and the rewrite.
• --dry-run is the same as the default preview mode, which changes nothing.
• --proposal-out <path> writes a reviewed proposal document during preview, without changing the catalog.
• --apply-proposal <path> applies that reviewed proposal document as it is, without generating a new proposal or calling the AI providers again.
• --apply generates and applies a new proposal in one run, then adds the rewrite's scores to SCORE.json.
• --json returns the standard SkillCatalog JSON envelope with mode: dry-run, mode: reviewed-apply, or mode: generate-and-apply.
• --quiet prints a shorter summary, still with any warnings and publish guidance, and hides the AI provider's progress and output.
• --json also hides the AI provider's progress and output, so --quiet --json returns the same JSON envelope as --json.
• With --json, data.provider_warnings lists AI providers that failed while another succeeded, and AI provider text that SkillCatalog cleaned up before using it.
• --catalog-id selects a registered catalog explicitly; when omitted, the catalog last chosen in the desktop app is used.

Side effects

• Default and --dry-run mode never write SKILL.md, SCORE.json, delivery targets, commits, or remote branches.
• --proposal-out <path> writes only the reviewed proposal document, at the path you give.
• --apply-proposal <path> writes the reviewed proposal's SKILL.md and adds the rewrite's scores to that skill's SCORE.json.
• --apply writes the generated proposal's SKILL.md and adds the rewrite's scores to that skill's SCORE.json.
• The AI providers never edit SCORE.json; only SkillCatalog's scoring writes it.

Follow-on behavior

• Review the preview before you use --proposal-out or --apply.
• After --apply-proposal, the output tells you how to publish the rewrite with skc skill publish-accepted.
• skc skill publish-accepted checks the accepted SKILL.md and its scores, commits only SKILL.md and SCORE.json, then runs delivery only when the push settled and no unrelated changes are pending.

Exit status

• --apply-proposal cannot be combined with --dry-run, --proposal-out, or --apply, and --dry-run cannot be combined with --apply; these combinations fail while the arguments are parsed. Combining --proposal-out with --apply fails with a proposal-out-with-apply error before any provider runs, because --apply generates and applies in one run and does not produce a reviewed proposal document.
• This command exits non-zero when no catalog can be selected, when a reviewed proposal document is missing, malformed, invalid, out of date, or for a different catalog or skill, when SCORE.json has no score for the current SKILL.md (run skc skill score first), when every AI provider fails to write a rewrite, when every rewrite is invalid, when no AI provider can score the rewrite, when the selected catalog is the Essentials catalog, which is read-only, or when the skill changes before apply.
• When one AI provider fails or writes an invalid rewrite and another produces a valid, scored proposal, the command succeeds and shows the failure as a warning.

skc skill publish-accepted

Publish a reviewed improvement that has already been accepted.

skc skill publish-accepted [OPTIONS] --proposal <PATH> --message <MESSAGE>

Output

• By default this command prints a summary: the commit, push, and delivery status, the committed files, and any other changed files it left uncommitted.
• --json returns the standard SkillCatalog JSON envelope with command: "skill.publish-accepted" and the same commit, push, delivery, and preserved-path fields.
• The command reports success only when the commit status is committed or nothing_to_commit, the push status is pushed, nothing_to_push, or local_only, and the delivery status is delivery_allowed. These are the JSON values; the summary prints them as words, such as nothing to commit.
• With --json, failures print a JSON error envelope on standard error, with command: "skill.publish-accepted".

Side effects

• Successful runs commit only skills/<slug>/SKILL.md and skills/<slug>/SCORE.json of the accepted rewrite, push, and then run delivery.
• This command never commits other files: other changes in the catalog, such as to taxonomy.yaml or the skill's companion files, stay uncommitted.

Follow-on behavior

• After a successful publish the durable accepted-improvement handoff is cleared: SkillCatalog deletes its saved record of the accepted rewrite, so the desktop app and the CLI stop offering to publish or keep it.
• If the commit fails, the push fails or is skipped after a commit, or delivery is blocked, fails, or is not reached, the durable handoff is preserved: SkillCatalog keeps the record, so you can publish again without running apply again.

Exit status

• This command exits non-zero when the reviewed proposal is missing, malformed, invalid, out of date, or for a different catalog or skill, when the accepted SKILL.md has no scores in SCORE.json, when the selected catalog is the Essentials catalog, which is read-only, when the commit fails, when the push fails or is skipped after a commit, when a failed push or other uncommitted changes in the catalog stop delivery, when delivery fails, or when delivery is not reached.
• JSON error envelopes always have command: "skill.publish-accepted". When the commit, push, or delivery step fails, error.details.kind is one of publish_commit_failed, publish_push_failed, publish_push_skipped, publish_delivery_blocked_by_push, publish_delivery_blocked_by_unrelated_changes, publish_delivery_failed, or publish_delivery_not_reached.

skc skill score-history

Show scoring history for one skill from a catalog.

skc skill score-history [OPTIONS] <SLUG>

Output

• On success, this command prints the skill's score history as raw JSON to standard output.
• Successful history output contains the skill slug and every run in the skill's SCORE.json, oldest first.
• --quiet prints the same JSON.
• Successful history output does not use the standard SkillCatalog JSON envelope, even when --json is present.
• --quiet --json prints the same JSON as --json.
• --catalog-id selects a registered catalog explicitly; when omitted, the catalog last chosen in the desktop app is used.
• Failures print a JSON error envelope on standard error, even without --json. Problems choosing the catalog print as plain text unless --json is present.

Side effects

• --repair rewrites SCORE.json in the clone and keeps the original under <config>/score-history-backups/<catalog-id>/<slug>/.

Exit status

• This command exits non-zero when no catalog can be selected, when the selected catalog clone is unreadable, when the skill is a single file such as skills/review-checklist.md or skills/review-checklist.yaml, which scoring does not support (move it to skills/review-checklist/SKILL.md and retry), or when SCORE.json cannot be read.

skc score-history

Alias for skc skill score-history, with the same arguments and behavior.

skc scoring

Manage scoring settings.

skc scoring [OPTIONS] <COMMAND>

skc scoring providers

List AI providers and change their settings.

skc scoring providers [OPTIONS] <COMMAND>

skc scoring providers list

List AI providers, with whether each is enabled and usable.

skc scoring providers list [OPTIONS]

Output

• By default this command prints a table with one row per AI provider: its id, whether it is enabled and usable, its auth mode, credential source, readiness, saved model and effort, and display name.
• --json returns the same details for each AI provider in the standard SkillCatalog JSON envelope, with readiness under local_readiness.

Exit status

• This command exits non-zero when settings.toml cannot be read, or when checking an enabled AI provider fails.

skc scoring providers enable

Enable one AI provider for scoring.

skc scoring providers enable [OPTIONS] <PROVIDER_ID>

Output

• By default this command prints the id of the AI provider it enabled.
• --json returns the provider id, its new enabled value, and the updated provider list, in the standard SkillCatalog JSON envelope.

Side effects

• Successful runs save the AI provider as enabled for scoring in settings.toml.

Follow-on behavior

• Future skc skill score runs use this AI provider when its command-line tool is installed and signed in.

Exit status

• This command exits non-zero for unknown provider ids or settings read and write failures.
• An enabled AI provider takes part in scoring only once it is usable, that is, once its command-line tool is installed and signed in.

skc scoring providers disable

Disable one AI provider for scoring.

skc scoring providers disable [OPTIONS] <PROVIDER_ID>

Output

• By default this command prints the id of the AI provider it disabled.
• --json returns the provider id, its new enabled value, and the updated provider list, in the standard SkillCatalog JSON envelope.

Side effects

• Successful runs save the AI provider as disabled for scoring in settings.toml.

Follow-on behavior

• Future skc skill score runs skip this AI provider.

Exit status

• This command exits non-zero for unknown provider ids or settings read and write failures.

skc scoring providers set-model

Save the model that one AI provider uses.

skc scoring providers set-model [OPTIONS] <PROVIDER_ID> <MODEL>

Output

• By default this command prints a confirmation with the provider id and the new model.
• --json returns the provider id, field: "model", the saved value, and the updated provider list, in the standard SkillCatalog JSON envelope.

Side effects

• Successful runs save the model key for the AI provider under [scoring.enabled_providers.<provider-id>] in settings.toml.

Follow-on behavior

• Future skc skill score and skc skill improve runs pass the saved model to the AI provider's command-line tool, unless the run's own --model flag overrides it.

Exit status

• This command exits non-zero for unknown provider ids, an empty <MODEL> value (use clear-model to remove the saved value), or when settings.toml cannot be read or written.

skc scoring providers set-effort

Save the reasoning effort that one AI provider uses.

skc scoring providers set-effort [OPTIONS] <PROVIDER_ID> <EFFORT>

Output

• By default this command prints a confirmation with the provider id and the new effort.
• --json returns the provider id, field: "effort", the saved value, and the updated provider list, in the standard SkillCatalog JSON envelope.

Side effects

• Successful runs save the effort key for the AI provider under [scoring.enabled_providers.<provider-id>] in settings.toml.

Follow-on behavior

• Future skc skill score and skc skill improve runs pass the saved effort to the AI provider's command-line tool. No flag overrides it for a single run.

Exit status

• This command exits non-zero for unknown provider ids, an empty <EFFORT> value (use clear-effort to remove the saved value), effort values the provider does not support, or when settings.toml cannot be read or written.

skc scoring providers clear-model

Clear the saved model of one AI provider.

skc scoring providers clear-model [OPTIONS] <PROVIDER_ID>

Output

• By default this command prints a confirmation with the id of the AI provider whose saved model it cleared.
• --json returns the provider id, field: "model", value: null, and the updated provider list, in the standard SkillCatalog JSON envelope.

Side effects

• Successful runs remove the model key for the AI provider from [scoring.enabled_providers.<provider-id>] in settings.toml, and keep its enabled and effort keys.

Follow-on behavior

• Future skc skill score and skc skill improve runs use the default model of the AI provider's command-line tool, unless the run's own --model flag names one.

Exit status

• This command exits non-zero for unknown provider ids or settings read and write failures.

skc scoring providers clear-effort

Clear the saved reasoning effort of one AI provider.

skc scoring providers clear-effort [OPTIONS] <PROVIDER_ID>

Output

• By default this command prints a confirmation with the id of the AI provider whose saved effort it cleared.
• --json returns the provider id, field: "effort", value: null, and the updated provider list, in the standard SkillCatalog JSON envelope.

Side effects

• Successful runs remove the effort key for the AI provider from [scoring.enabled_providers.<provider-id>] in settings.toml, and keep its enabled and model keys.

Follow-on behavior

• Future skc skill score and skc skill improve runs pass no effort to the AI provider's command-line tool, so it uses its own default.

Exit status

• This command exits non-zero for unknown provider ids or settings read and write failures.

skc stack

Inspect stacks in registered catalogs.

skc stack [OPTIONS] <COMMAND>

skc stack list

List stacks from every registered catalog, or from one catalog.

skc stack list [OPTIONS] [CATALOG_ID]

Without a filter, the command lists every registered catalog, one group per catalog. Pass --catalog-id <CATALOG_ID> to list only that catalog.

A positional CATALOG_ID also works as an alias for --catalog-id. Supplying both the positional and --catalog-id with different values is a user-input error.

skc stack show

Show one stack from a registered catalog.

skc stack show [OPTIONS] <ARGS>...

Use either the positional form skc stack show <CATALOG_ID> <SLUG> or the explicit flag form skc stack show <SLUG> --catalog-id <CATALOG_ID>.

The catalog id must match a registered catalog; unknown ids fail with catalog-not-found.

skc bundle

Inspect bundles in registered catalogs.

skc bundle [OPTIONS] <COMMAND>

skc bundle list

List bundles from every registered catalog, or from one catalog.

skc bundle list [OPTIONS] [CATALOG_ID]

Without a filter, the command lists every registered catalog, one group per catalog. Pass --catalog-id <CATALOG_ID> to list only that catalog.

A positional CATALOG_ID also works as an alias for --catalog-id. Supplying both the positional and --catalog-id with different values is a user-input error.

skc bundle show

Show one bundle from a registered catalog.

skc bundle show [OPTIONS] <ARGS>...

Use either the positional form skc bundle show <CATALOG_ID> <SLUG> or the explicit flag form skc bundle show <SLUG> --catalog-id <CATALOG_ID>.

The catalog id must match a registered catalog; unknown ids fail with catalog-not-found.

skc validate

Check catalogs, profiles, settings, delivered files, and the team manifest in this folder.

skc validate [OPTIONS]

Output

• By default this command prints human-readable diagnostics for any failing checks.
• --json returns the standard SkillCatalog JSON envelope.

Exit status

• The default run includes drift checks unless --no-drift is set.
• Errors exit non-zero; warnings do too unless --warnings-ok is set. Informational findings never fail validation.
• --drift and --no-drift cannot be combined.
• When --path points at a catalog root, validation scopes catalog checks and drift to that catalog.
• Catalog checks treat missing stacks and bundles folders as empty, like the rest of SkillCatalog, and report a missing skills folder, symbolic links that delivery would refuse in skill folders, and leftover Git conflict markers outside fenced code as errors.

skc hook

Run the check that a catalog's pre-commit hook calls. Not for direct use.

skc hook [OPTIONS] <COMMAND>

skc hook run

Run the check that a catalog's pre-commit hook calls.

skc hook run [OPTIONS] --protocol <PROTOCOL> --path <PATH>

skc status

Show your catalogs, profiles, tools, and drift.

skc status [OPTIONS]

Output

• By default this command prints registered catalogs, profiles, enabled delivery targets, and drift counts.
• --json returns the standard SkillCatalog JSON envelope with the same summary.

Exit status

• This command exits non-zero with status-inconsistent-state when validating profile files, settings, or catalogs finds errors or warnings. Run skc validate for diagnostics.

skc completions

Generate shell completions for skc.

skc completions [OPTIONS] <SHELL>

Output

• This command always prints a shell completion script to standard output.
• It does not use the standard JSON envelope, even when --json is present.

skc help-json

Print the full command tree as JSON.

skc help-json [OPTIONS]

Output

• This command always prints raw JSON to standard output.
• It does not use the standard JSON envelope, even when --json is present.
• The JSON describes every command and argument, including the built-in help and version flags, aliases, options that cannot be combined, and these behavior notes.