Files and folders

This page lists the folders SkillCatalog uses on your machine and in your repositories, what each file holds, and which ones you can delete. See File formats.

The SkillCatalog folder

SkillCatalog keeps its files in ~/.skillcatalog/. The desktop app and skc share this folder.

~/.skillcatalog/
  settings.toml
  telemetry-salt
  logs/
  catalogs/
    catalogs.yml
    acme-skills/
  profiles/
    home/
      profile.yml
      delivery-manifest.json
    payments-api/
  proposals/
    acme-skills/
  delivery-retained/
  score-history-backups/

Every command except skc completions, skc help-json, and skc update --check writes to this folder, even one that only reads your catalogs. Commands that read catalogs, such as skc status, skc validate, skc catalog list, and skc proposal list, can also replace the Essentials catalog's copy with the version that comes with skc.

The desktop app keeps display preferences, such as the theme, outside this folder.

Use another folder

skc --config-dir <folder> keeps all of SkillCatalog's files in <folder> instead of ~/.skillcatalog: settings, catalogs and their clones, profiles, proposals, logs, and the secret for log codes. Pass it to every command. The desktop app always uses ~/.skillcatalog.

--config-dir does not move delivery. The Home profile still delivers to each tool's skills folder in your home folder, such as ~/.claude/skills/. Two setups with different --config-dir folders share those skills folders.

To isolate delivery too, set HOME to another folder, which moves ~/.skillcatalog with it. See Isolate a run.

Where skills are delivered

SkillCatalog delivers each skill as a folder <slug>/ with its SKILL.md and companion files, into the skills folder of each tool you turned on:

For a project profile, <folder> is the checkout, or the folder saved with skc install --target-dir. For a personal profile, it is the folder you gave skc profile create. See Use the skills in a second checkout.

When no entry selects a skill any more, delivery removes its files and then its folder if the folder is empty. Turning a tool off removes the files SkillCatalog delivered for that tool. See Turn tools on and off.

When delivery cannot deliver a profile or a skill safely, it skips only that one, keeps its earlier copies, and delivers the rest, as Partial delivery explains.

Delivered files and drift

Each profile's delivery record lists every file SkillCatalog delivered, with a hash of its content. SkillCatalog compares each file with the record to find drift. skc deliver --check and skc validate --drift fail when they find drift, and skc status counts it.

skc deliver --check also lists a project profile's checkout or --target-dir folder that cannot be found, as "Unreadable", and fails.

To replace an edited file with the catalog's version, delete it and run skc deliver. For files that SkillCatalog did not write, see A skill folder already exists.

Files in a checkout

skc install itself writes nothing in the checkout except delivered files.

Files in a catalog clone

skc sync commits changes in catalog.yaml, README.md, skills/, stacks/, bundles/, and a legacy taxonomy.yaml, and leaves other files uncommitted.

The pre-commit check

When you add a catalog with skc catalog add, the desktop app's Add catalog, or a first skc install, SkillCatalog adds its lines to the clone's .git/hooks/pre-commit, between # --- skc-validate-begin --- and # --- skc-validate-end ---. An existing hook keeps its other lines. A catalog added from a share link gets no hook.

Before each commit in the clone, including the commits that skc sync and desktop saves make, the hook checks the catalog's files as skc validate --path <clone> --warnings-ok --no-drift does. A warning or an edited delivered copy never blocks a commit. An error refuses the commit, and the hook prints Fix the problems listed above, then commit again.

Each sync and save rewrites SkillCatalog's lines in the hook so they run the skc of the program doing the work, and discards any edit you made between the markers. When the hook cannot run skc at all, it refuses the commit and says to update SkillCatalog and sync.

To turn the check off for one catalog, run chmod -x .git/hooks/pre-commit in the clone. SkillCatalog keeps the file that way. If your Git configuration sets core.hooksPath, Git never runs this hook, so run skc validate yourself before you sync or save.

Logs

skc and the desktop app write log files to ~/.skillcatalog/logs/, or to <folder>/logs/ with --config-dir <folder>. When skc cannot find your home folder, it writes to skillcatalog-logs in the system's temporary folder.

Each time skc or the desktop app starts, SkillCatalog deletes log files more than 7 days old. skc completions, skc help-json, and skc update --check write no log.

SKILLCATALOG_LOG sets how much SkillCatalog logs. The default is info, and the other levels are error, warn, debug, and trace. SKILLCATALOG_LOG=off stops writing log lines, though the day's file is still created.

Log files are not redacted, so read them before you share them, as Find and share logs explains.

Environment variables

A timeout value that is not a whole number is ignored. No environment variable sets the SkillCatalog folder, so use --config-dir or HOME.

When SkillCatalog syncs, saves, or publishes, its Git commands ignore variables from your environment that point Git at another repository. Examples are GIT_DIR, GIT_WORK_TREE, and GIT_INDEX_FILE. A shell or a Git hook that sets them cannot send those commits elsewhere. GIT_CEILING_DIRECTORIES and the GIT_CONFIG* variables still apply.