skm

skm

skm keeps skills and commands in one local Git repo and installs them into every tool. Two axes: providers say where an asset came from; targets say where it gets installed. skm --help and docs/cli/ have the full surface — this file is the working model plus the commands worth reaching for.

Before anything else

• Every command takes --json. Always pass it when you're going to parse the output; the human tables are not a stable contract.
• Exit codes: 0 ok, 1 problem with the object you asked about, 2 argument / tool / provider error. Don't infer success from stdout.
• The repo root is discovered upward from cwd (a skills/ or commands/ dir marks it); override with --root, or SKM_ROOT. If a command says "no repository found", you are outside the repo — pass --root, don't skm init a new one.
• --dry-run reports intended actions and writes nothing. Use it first for anything that touches target directories.
• Destructive commands (delete, delete-external) require --force by design. Ask the user before reaching for them.

The loop that covers most work

skm list --json                     # the catalog: every entry, with install columns
skm status <name> --json            # one entry across targets: installed/dangling/drifted
skm install <name> [--target t]     # default: every kind-matching target
skm uninstall <name> [--target t]   # removes managed installs only, never user files
skm verify --json                   # whole-repo consistency

Bringing assets in:

skm import ./my-skill --kind skill          # local path
skm import owner/repo/path/to/skill --json  # GitHub shorthand, subdir, or a blob URL
skm import - < sources.txt                  # newline-separated list on stdin
skm discover --json && skm adopt ~/.codex/skills/review   # take over an unmanaged install
skm update <name> / skm batch-update        # refresh from the recorded origin

For community skills, run skm fork <name> before customizing, then edit the copy in skills-fork/<path>/ (skm info prints it). While it exists it is the active version. update merges your edits onto the new upstream with git merge-file and, on any conflict, timeout or binary clash, stops and changes nothing; fix the fork and rerun, or fork --replace. fork --replace and fork --discard delete the user's copy, so get authorization first. Archive and delete refuse a forked Skill until it is discarded. There is no recovery state: an update killed halfway is restored from Git.