Command reference

Global conventions

The flags below are visible on every command. Project scope is the default; user-wide skills have their own, independent declarations, and a command reaches the machine only when it carries --global.

Under --json, stdout carries only the machine-readable report, so scripts should branch on the command and action identifiers rather than on localized text. --yes answers the confirmations that follow a selection and never decides the selection: it does not choose which skill get installs or which declaration remove deletes.

--install-mode (auto or copy, overriding the configuration) is persistent as well: auto prefers links to immutable shared snapshots and falls back to copies when links are unavailable; copy creates independent directories, which is what to use when an installed skill needs editing. --install-mode, --all, --allow-downgrade, and --on-conflict deliberately have no shorthand: the obvious letters are ambiguous or already taken, and the long forms read better.

Output language: help, summaries, prompts, and errors follow SKILLMOD_LANG when it is set and the system locale otherwise. JSON field names and action identifiers are never translated.

Command by command

init

Adopt skills that already exist on disk into SKILL.mod and SKILL.lock.

• Scans .agents/skills/ in the selected scope without changing existing directories, links, or files: directory links are followed for content verification, while broken links, unverifiable contents, and invalid directory names are reported and skipped.
• Provenance is recovered from matching lock records or verified snapshots, including monorepo subdirectories and aliases; --global also imports the upstream installer's .skill-lock.json, while project init reads skills-lock.json.
• A recorded Git source and revision stay authoritative even when the installed directory has drifted; when an upstream record omits its revision, init adopts the latest immutable resolution only if the contents match exactly. Sources that cannot be resolved safely are kept as local baselines, so one unresolved entry does not discard the rest of the import.
• --global init declares everything in ~/.agents/skills/ into ~/.agents/skillmod/global/SKILL.mod. A skill recorded from a web discovery endpoint has no Git repository behind it: it is reported as unresolved and kept as a local declaration, and adding the publishing repository to known_sources lets a later init adopt it as a Git dependency.
• Replacing an existing declaration requires --force, which first backs up SKILL.mod as SKILL.mod.bak; the import writes both SKILL.mod and SKILL.lock.

get

Fetch a skill from any Git repository, update SKILL.mod / SKILL.lock, and install it.

• The repository is always named and // selects the skill inside it: a single segment first addresses an exact root subdirectory, then falls back to a unique skill name below skills/; when several skills answer the same name, skillmod reports the candidate paths and refuses to guess. A repository that is itself a single skill needs no //.
• Versions must be semver tags or 40-character commit SHAs; branch names are rejected because they are mutable. When omitted, the version resolves in this order: <subdirectory>/v<latest> → v<latest> → default-branch HEAD, the last recorded as a pseudo-version.
• --alias / -a sets the installation directory alias, for when two sources publish the same skill name.
• --all installs every skill the repository publishes without asking; --yes answers the confirmations that follow the selection, so a non-interactive run on a multi-skill repository has to say --all. On an interactive terminal, ↑/← and ↓/→ move, Space toggles a selection, d shows the description and command, and Enter confirms.
• A destination holding different content goes through the shared conflict policy: ask per conflict by default (overwrite / skip / abort), skip safely under --yes, or answer everything at once with --on-conflict=overwrite or =skip. The default auto mode links to shared snapshots; --install-mode=copy creates an editable independent directory.

sync

Align local skill directories with the state pinned in SKILL.lock.

• Idempotent, with rollback on failure, and it never silently overwrites local modifications: conflicting targets are kept and counted toward exit code 3 while the work that could proceed did proceed.
• --check / -c verifies without modifying anything and is an alias for skillmod verify; it is mutually exclusive with --relink.
• --relink / -r reinstalls matching remote skills using the configured install mode, only for a deliberate migration; run it with --dry-run first.
• Installed files are never deleted automatically; cleaning stale installations is prune's job.
• On exit code 3, inspect the per-target results: some work completed and conflicting targets were preserved, leaving the decision about local edits with a person.

share

Link installed skills into agent directories such as .claude or .codex, and record the agents in SKILL.mod.

• An agent is named by one directory segment and reads skills from .<name>/skills under the scope root; the manifest stores the name and never a path, so the link reproduces on another machine. Each destination entry is a symlink to the managed copy — a byte-preserving copy where the filesystem forbids symlinks — so edits to the managed skill are visible through every link at once.
• Selected skills missing from SKILL.mod are adopted in the same run: a verified lock baseline or cache snapshot preserves remote provenance, otherwise the current contents become a local entry; existing declared baselines are preserved.
• --skill / -s and --agent / -a are repeatable or comma-separated, and positional arguments name skills the same way --skill does. Omitting both opens interactive selection, with both lists preselected on the state that already holds — confirming an unchanged selection is a no-op.
• --all shares every installed skill without asking; --on-conflict takes ask (default), overwrite, or skip to answer conflicts where a destination holds different content, and .agents/skills/ is refused as a destination.
• --remove requires --agent: it unlinks only those agents while declarations and managed copies stay, the same as remove --agent, and destinations holding foreign content are left alone. The links then maintain themselves: sync recreates a link that was replaced or drifted, verify reports a missing one under an agent directory that exists on this machine, and removing a skill takes its mirror links down with it.

list

Show every declaration, its version, and its installation status.

• Each entry reports its version and status: installed, missing, or upgradable.
• list, why, and verify classify every installation directory the same way, so they cannot disagree about a target: an edited local entry is reported as local-drift rather than a plain local, an unreadable directory is unverifiable everywhere, and local entries are inspected against the recorded baseline.

why

Explain one entry: its declaration, immutable provenance, and installation status.

• Reports the source, resolved version, commit, dirhash, installation directory, and each configured target's status.
• The selector is a published name or an installation alias; a published name can represent more than one aliased declaration, so review the output whenever the selector may not be unique.
• Prefer it over manually interpreting links inside .agents/skills/.

update

Resolve the latest versions, update the lock, and install.

• With no names, every entry is updated with the same latest semantics as get: the highest tag wins (subdirectory tags first, then root), and only a repository without any tag advances to a new pseudo-version at default-branch HEAD.
• Entries pinned to a commit — pseudo-versions and SHAs — migrate to that tag as well, so machines that adopted the same skill differently converge on the same version.
• When newer tags have disappeared, skillmod refuses an accidental semantic-version downgrade of a tag lock; use --allow-downgrade only after confirming the remote tag removal was intentional.
• A published name can represent more than one aliased declaration, and an installation alias selects its corresponding entry; review the output whenever the selector may not be unique.

verify

Check every installation against SKILL.lock; read-only, the CI gate.

• Exits with status 2 when drift is detected; it uses the same implementation as sync --check.
• For machine consumption, add --json and branch on the command and action identifiers rather than on translated notes or terminal text.
• The cheat sheet at the bottom of this page covers exit codes 0 / 1 / 2 / 3.

remove

Delete declarations and clean managed installations.

• Names may be published names or installation aliases, passed as positional arguments or through --skill / -s, which is repeatable and comma-separated; a run that names nothing opens a selection over what SKILL.mod declares, which needs a terminal.
• --all takes every declared entry without asking; names and --all cannot be combined. --yes answers the deletion confirmation rather than choosing what to delete.
• --agent / -a unlinks only those agents and keeps skill declarations and managed copies: without skill names the picker offers only skills shared to the named agents and starts with nothing checked, with --all all matching skills are unshared, and agent values may repeat or use comma-separated names.
• Clean managed installations are removed transactionally; locally modified or unverifiable directories are preserved and reported as partial completion.

prune

Drop stale installations and lock records left behind by hand edits.

• Use it when declarations were already edited and stale installations or lock records remain; it lists and confirms before deleting, so run --dry-run first.
• It never deletes link targets or shared snapshots, and there is no automatic cache eviction; do not replace remove or prune with manual cache deletion.

upgrade

Replace the running skillmod executable with a published release.

• The download is verified against the release checksums before the executable is replaced, following the same trust path as a manual installation.
• --check / -c reports whether a newer release exists without downloading it; --tag / -t installs this release tag instead of the latest; --dry-run downloads and verifies without replacing the executable.
• An executable installed by a package manager should be upgraded through that package manager instead.

Exit codes at a glance

verify uses exit code 2 for drift, while sync, remove, and others may end at 3. The full action vocabulary and the JSON report shape live on the Automation & CI page.