CLI reference

This reference is generated by hand from the airskills binary's --help output. Run any command with --help for the canonical wording.

Two remotes, one rule

Every command talks to one of two remotes, and knowing which is the key to the whole CLI:

• Your own account's skillset — where your skills (and your edits to sourced ones) live. push, pull, and sync work this axis.
• An origin namespace — the published skill of another user or org that you sourced a skill from. add, resolve, and the suggestion flow work this axis.

The rule: pull --force resolves a conflict against your account's copy; airskills add <owner>/<skill> --force takes the origin's current bytes, dropping your customisation. They are not interchangeable — pull never fetches from an origin namespace. For skills you own outright, the second remote doesn't exist and sync is all you need.

Commands

airskills sync

Push local skill changes, then pull remote skills (running push then pull in sequence). The fastest way to log in for the first time and get everything in line.

airskills sync [--skillset <slug>] [-v|--verbose]

• --skillset <slug> — personal skillset to sync against. Defaults to your last-used skillset (set via airskills skillset use).
• -v, --verbose — show per-skill progress.

---

airskills push

Scan local skills, detect changes, and upload them to the server.

airskills push [--force] [--force-suggest] [--org <slug>] [-v|--verbose]

• --force — skip the conflict check (use after resolving conflicts). Bypasses the X-Expected-Hash content-hash check. Mirror of pull --force: both mean "I'm about to overwrite the other side, do it anyway", pointed in opposite directions. Also auto-confirms any detected file deletions (see below) instead of prompting.
• --force-suggest — submit the suggestion for edits to a non-owned skill without prompting, even when the upstream has advanced. In a terminal, push asks per skill whether to suggest your edits to the owner; headless (an agent, a cron job) it never auto-fires a suggestion — your edits are still backed up to your account, and the decision is deferred until an interactive push answers the prompt or a push with this flag submits it.
• --org <slug> — create new skills under this org (org admins only). Existing skills keep their current owner regardless of this flag.
• -v, --verbose — show per-skill progress.

If you hand-deleted a file from a skill, push (and sync) detects it by comparing your agent copies against the server: a file still on the server but missing from a local copy is surfaced before the mirror can resurrect it. In a terminal you're asked whether to remove it for good; headless, it keeps the file and prints a hint (use --force to remove without asking). See Delete a skill.

---

airskills pull

Download skills from your account that aren't installed locally, and update changed ones. If both local and remote have changed, the remote version is saved to a temp dir for merge instead of overwriting your work.

airskills pull [--force | --keep-local <name>] [--skillset <slug>] [--version <commit>]

• --force — overwrite local with remote for diverged skills (backs up your local copy first). Mirror of push --force: both mean "I'm about to overwrite the other side, do it anyway", pointed in opposite directions.
• --keep-local <name> — the opposite resolution: keep your local copy of a conflicting skill as-is and track it against the server version, so the conflict stops recurring. Your files are never touched. For a skill you don't own this becomes your fork on the next push; for an org skill it warns first, since keep-local forks rather than updating the org skill (admins should use --force instead — see below).
• --skillset <slug> — personal skillset to pull against. Defaults to your last-used skillset.
• --version <commit-hash> <skill> — pull a specific commit version of a single skill.

When a skill you have locally collides by name with a different server skill that airskills has never tracked, pull does not pick a side for you (same name doesn't mean same skill). It parks the server copy for review and offers three resolutions: pull --keep-local <name> (keep yours), pull --force <name> (take the server's), or mv <name> <new> to rename your local aside and keep both.

---

airskills update

Fetch the latest versions of all skills (or a named skill) from your account and write them to each detected agent's directory. Reports which skills changed.

airskills update [name]

update does not push local changes — it's pull-only. Use sync for the round-trip.

---

airskills resolve

Records that you've reviewed your customised copy of a sourced skill against the original's current version. Stops the modified-pending prompt on every sync until the original moves again.

airskills resolve <name>

What it does: writes the upstream skill's current content hash into your local marker as ResolvedHash. No file changes, no push, no pull. The CLI just remembers "user has seen the original at version V."

Three flows that all end in resolve:

• Took nothing from upstream, kept your customised copy as-is.
• Took some upstream ideas (manually or with AI), edited locally.
• Resolved a previous review and the upstream has moved again.

If you instead want to take the whole upstream, replacing your local copy: airskills add <owner>/<slug> --force. That makes you synced; resolve is unnecessary. (Not pull --force — pull talks to your own account's copy and only resolves conflicts there; taking an upstream's bytes always goes through add.)

For owned skills (your own namespace, no upstream) this is a no-op — there's no "original" to resolve against.

See Customise a sourced skill and Incorporate updates from the original for the full flow.

---

airskills add

Install a skill from airskills.ai or directly from a GitHub repo.

airskills add <username/skill> [--preview] [--force]
airskills add github.com/<owner>/<repo>[/<path>] [--all] [--skill <names>]

• <username/skill> — install from airskills.ai (e.g. chrismdp/retro).
• github.com/<owner>/<repo>[/<path>] — install directly from a GitHub repo. Use <path> to pick a specific skill in a multi-skill repo.
• --all — install every skill found in the GitHub repo.
• --skill <names> — comma-separated names (or path/to/name) for a subset.
• --preview — show the skill's content without installing it.
• --force — take upstream's current bytes, overwriting any local copy. Use when sync tells you upstream has advanced and you want to adopt it (drops any local edits). Previous local files are backed up to ~/.airskills/undo/<timestamp>/. No-op when the skill isn't installed yet. If your local copy is a legacy visible fork of this skill (a shape from before forks became emergent-only), taking the upstream also retires the fork — the fork row is soft-deleted and your machine tracks the original directly from then on.

Adding a skill you don't own tracks the original directly — it stays ONE skill on your machine. If you later edit it, your edits become a local overlay: push backs them up to a hidden copy in your account and offers to suggest them to the owner. There is no deliberate fork command — forks only ever exist as those automatic backups (and as personal skills promoted from them if you lose access to the original). If you want an independent variant you own outright, copy the skill's folder to a new name, update the name: field in its SKILL.md, and push.

When you're logged in, adding a skill you don't own also subscribes you to it — the install is recorded against your account, so it follows you to your other machines on their next airskills sync (it shows in list as "added from <owner>", not as one of your own skills). This applies to --as and --force too. Anonymous adds stay local to that machine; log in and sync and the CLI registers a subscription for anything you added beforehand. If a subscribed skill's upstream later disappears — the owner deletes it or makes it private — your local copy is saved as your own skill so you keep it; if it's transferred, your subscription follows it to its new home.

---

airskills once

Download a skill to a temp directory for one-time use, without installing it permanently. Prints the SKILL.md path so you can reference it with @ in your AI agent, plus @ paths for any other files.

airskills once <username/skill>

Aliased as airskills show.

---

airskills publish

Make a private skill publicly visible so anyone can install it with airskills add.

airskills publish <skill-name>

---

airskills share

Grant another user access to one of your skills by email. They are notified and can install it with airskills add. Sharing does not change ownership — you still own the skill. To change ownership, use airskills transfer.

airskills share <username/skill> --with <email>

---

airskills mv

Rename a skill. Updates the local directory name across every detected agent and the skill's display name on the server. The skill's owner does not change — see airskills transfer for that.

Consumers who installed the skill via airskills add are unaffected by a rename — their CLI continues to fetch updates because it pins by skill ID, not by name.

airskills mv <old-name> <new-name>

See Rename a skill for the full workflow.

---

airskills transfer

Change the ownership of a skill — between your personal account and an organization you belong to. This is a deliberate, consumer-visible move: the old skill is archived (not redirected), the old slug starts returning 410 Gone, and anyone who previously installed the skill sees an "upstream archived" warning on their next pull.

airskills transfer <skill-name> --to-org <organization-slug> [--slug <new-slug>] [-y|--yes]
airskills transfer <skill-name> --to-user [--slug <new-slug>] [-y|--yes]

• --to-org <slug> — target org slug (e.g. cherrypick). Mutually exclusive with --to-user.
• --to-user — transfer to your personal namespace (org → user). Org admins only.
• --slug <new-slug> — override the slug in the target namespace. Use on collision when the target already has a skill at that slug.
• -y, --yes — skip the confirmation prompt.

On --to-org, your local copy is removed (backed up first to ~/.airskills/undo/) — the skill is now delivered through skillsets, so re-add it to a skillset you're assigned to in order to use it locally again. On --to-user the skill becomes your personal skill and the local copy stays linked.

See Transfer a skill for the full workflow, including what consumers see and how to restore.

---

airskills rm

Delete a skill — or a single file within a skill — from this machine and from your account.

airskills rm <name>         [-f|--force] [--keep-local] [--keep-remote] [--pending]
airskills rm <name>/<path>  [-f|--force] [--keep-remote]

• -f, --force — skip the confirmation prompt.
• --keep-local — only delete the remote skill; leave local files alone. (Whole-skill form only.)
• --keep-remote — only delete locally; leave the remote skill alone. For a subscribed skill (one you added but don't own), this keeps the subscription, so it reinstalls here on the next airskills sync — the CLI warns you when that's the case. Plain rm unsubscribes instead, so the skill stops arriving on your other machines too.
• --pending — discard only a parked pending-conflict copy (left in temp by a collision during add or sync), without touching the installed skill or the server. Use this to clear an "N pending conflict" status warning when a real skill of the same name is installed — plain rm <name> would delete that skill, not the parked copy.

Without flags: deletes both local (across every detected agent) and remote, then drops the entry from sync state.

Use this instead of rm -rf ~/.claude/skills/<name>. Hand-deleting an agent dir is silently restored by the next airskills sync — see Delete a skill for why and what to do about it.

Removing a single file. Pass a path inside a skill — airskills rm triage/scripts/old.sh — to drop one file rather than the whole skill. Hand-deleting the file and pushing does not work: the sync mirror resurrects it from any sibling agent dir that still has a copy. This command deletes the file from every detected agent copy first (so the mirror has nothing to copy back), then pushes the skill so the server and the marker drop it too. --keep-remote removes the file locally without pushing. SKILL.md can't be removed this way — to delete the whole skill, run airskills rm <skill>.

---

airskills restore

Restore a skill that was deleted with airskills rm.

airskills restore <skill-name> [--slug <new-slug>]

• --slug <new-slug> — rename on restore if the original slug now conflicts with another skill in your namespace.

---

airskills export

Export skills from your account into a portable format you can hand to another tool.

airskills export [name] [-f|--format zip|dir] [-o|--output <path>] [--all]

• -f, --format — zip (default) for a zip you drag into Claude.ai's Upload Skill dialog, ChatGPT's Skills page, or Cowork; dir for a Claude Code plugin directory you copy into ~/.claude/skills/ or a project's .claude/skills/.
• -o, --output — output path. Defaults to ./<name>.zip or ./<name>/.
• --all — export every skill on your account as a zip.

airskills export code-review               # → code-review.zip
airskills export code-review -f dir        # → code-review/SKILL.md
airskills export code-review -o ~/Downloads/
airskills export --all                     # → one zip per skill

---

airskills log

Show a unified timeline of recent changes across all your skills.

airskills log [-n|--limit <N>]

• -n, --limit — number of recent changes to show (default 20).

---

airskills status

One-line sync status, designed for shell startup:

eval "$(airskills status)"

airskills status [-q|--quiet]

• -q, --quiet — only output when updates are available.

status is a no-network call when run as part of eval; it does hit the server otherwise.

---

airskills list

List the skills in your skillset (including the ones you added from other people), with description, version, and the per-skill sync state on this machine.

airskills list [--scope personal|org] [--deleted]

• --scope personal|org — filter to one scope. Default is personal.
• --deleted — show soft-deleted skills instead of live ones.

The STATE column reports one of:

• synced — local matches the server.
• modified — local has diverged from the server. For owned skills: unpublished changes (run airskills push). For sourced skills: a customised copy you've already resolved against the original's current version.
• modified* — sourced skill, customised, AND the original has moved since you last resolved. See customisation.
• local changes — a skill you don't own (org-distributed, or added from another user) with your standing edits on top. The edits are backed up to a hidden copy in your account; the row reads local changes (suggestion pending) while a suggestion to the owner is open. Still ONE row — the backup never lists separately.
• untracked — local exists but airskills has no record of installing it. Next airskills sync will either silently link it (if bytes match) or surface it as a conflict.
• — — not installed locally; available to install.

Sample:

NAME              DESCRIPTION              VERSION  STATE
project           Manage vault projects    1.0.8    synced
cherrypick        Meal planning helper     2.1.0    untracked
coaching          Coaching session helper  1.0.3    modified
review-board      Review queue manager     1.3.0    modified*
brand-new-thing   Just published this      1.0.0    —

For more detail on what each state means, run airskills doctor or see How sync state works.

---

airskills doctor

Run health checks on your local skills. Reports two sections:

• Sync state — informational diagnostics about each skill's state relative to the server: untracked locals that next sync will link or surface as conflicts; sourced skills with new updates from the original; owned skills with unpublished changes. Doesn't affect exit code — these are healable on next sync.
• Refs — broken cross-skill references (a SKILL.md mentions /foo but /foo isn't installed). Exits non-zero (1) if any are found.

airskills doctor

Sample output:

Sync state:
  ! project — local exists, not tracked. Original v1.0.8 matches bytes — next sync will link.
  ! cherrypick — local exists, not tracked. Original v2.1.0 differs — next sync will surface conflict.
  ! coaching — local has unpublished changes. Run 'airskills push' to publish.
  ! review-board — customised copy of chrismdp/review-board. Original moved 1.2.0 → 1.3.0 since you resolved. Review and 'airskills resolve review-board', or 'airskills add chrismdp/review-board --force' to drop your customised copy.
  ! brand-new-thing — on server, not installed here ('airskills sync' or 'airskills add').
  ✓ 3 synced.

Refs:
  ✓ no broken refs found.

Every notable line shares the ! prefix; the rest of the line names the cause and the action. Synced skills collapse into the trailing count.

---

airskills login

Sign in to airskills.ai. Opens your browser to authenticate with Google or Microsoft. No account needed — one is created automatically.

airskills login

---

airskills logout

Sign out of airskills.

airskills logout

---

airskills whoami

Show the currently signed-in user.

airskills whoami

---

airskills self-update

Download the latest airskills binary from GitHub Releases, verify the checksum, and replace the current binary in place.

airskills self-update

Auto-update

The CLI auto-updates to the latest release before every command runs (you'll see a brief stderr line: airskills: updating to v…), provided all of the following hold:

• the install is in a user-writable path (curl-pipe-bash from airskills.ai/install.sh, manual download, or go install);
• there's a newer GitHub release than the running binary;
• neither --no-update nor AIRSKILLS_NO_AUTO_UPDATE=1 is set.

Installs in system-managed paths (/usr/, /opt/, /snap/, /Applications/) are skipped — your package manager owns those upgrades. You'll keep getting the older "new version available" hint on those installs.

If the auto-update fails (network, checksum, write permission) the CLI prints a single stderr line explaining why and runs your command on the current binary. Auto-update is best-effort and never blocks.

Opt out

Two equivalent escape hatches:

• --no-update flag — per invocation, useful in CI: airskills sync --no-update.
• AIRSKILLS_NO_AUTO_UPDATE=1 env var — per shell/profile.

Both leave airskills self-update working as a manual command.

---

airskills version

Print the version, commit, and build date.

airskills version

There is no --version flag — use the version subcommand.

---

airskills feedback

Send a message to the airskills team.

airskills feedback [-m|--message <text>] [--include-logs]

• -m, --message — feedback message (otherwise read interactively).
• --include-logs — attach recent CLI log files.

---

airskills config

Manage CLI configuration.

airskills config get <key>
airskills config set <key> <value>
airskills config path

Valid keys for set:

• api_url — API endpoint (default https://airskills.ai).

airskills config path prints the config directory (~/.config/airskills/ on macOS/Linux).

---

airskills skillset

Personal skillsets group skills for selective sync. Every account has a default skillset auto-created on signup. Use these commands to add more, switch between them, and delete the ones you no longer want.

airskills skillset list
airskills skillset create <slug> [--name <human-readable>] [--description <text>]
airskills skillset delete <slug> [--force]
airskills skillset use <slug>

• list — the currently-selected skillset is marked with *.
• create — --name defaults to the slug.
• delete — refuses to delete default and the currently-selected skillset. --force skips the confirmation prompt.
• use — switches the remembered default skillset. Subsequent airskills sync and airskills pull use this skillset unless you override with --skillset.

---

airskills org list

List the organizations you're a member of, with your role and member count. Read-only — organization creation, deletion, and settings live in the dashboard.

airskills org list

Sample:

SLUG          ROLE     MEMBERS  NAME
chrismdp-org  admin    3        Chrismdp Org
instem        member   12       Instem

If you don't belong to any organizations, you'll see a pointer to the dashboard:

(no organizations — visit https://airskills.ai/dashboard/organizations/new to create one)

---

airskills org member skillsets

Inspect or change which org skillsets are assigned to a member of an org you belong to.

airskills org member skillsets <user>                       # list current assignments
airskills org member skillsets <user> --set a,b,c           # replace the full set
airskills org member skillsets <user> --add <slug>          # add one
airskills org member skillsets <user> --remove <slug>       # remove one
airskills org member skillsets <user> --org <slug>          # disambiguate when in multiple orgs

• <user> is a username. The org-members API does not support email lookup today.
• --set, --add, and --remove are mutually exclusive.
• --set with an empty value means "just the default skillset".
• The default skillset is always implicitly assigned and cannot be removed.
• --org <slug> is required if you belong to multiple orgs.

---

airskills review

Review suggestions submitted by other users against your skills.

airskills review [skill]                                    # list pending suggestions
airskills review download <suggestion-id>                   # download to a temp dir
airskills review accept <suggestion-id>                     # mark accepted (bookkeeping only)
airskills review decline <suggestion-id> [--message <text>] # mark declined with optional reason

• airskills review with no args lists all pending suggestions and prints the full agent-friendly workflow. Pass a skill's local directory name to narrow the list.
• accept is bookkeeping only. Merge the changes into your local skill and run airskills push yourself — nothing auto-pushes.
• decline --message shows the reason to the contributor.

---

Shipping skills with runnable scripts

Skills can ship executable helpers (e.g. ralph.sh, generate.sh). On install (airskills add, airskills once, airskills sync, airskills pull), any file whose contents start with a #! shebang is written with 0755 so it can be invoked directly:

~/.claude/skills/ralph/ralph.sh        # works without bash prefix

Files without a shebang are written 0644 as before. Shebang detection is purely content-based — the file extension doesn't matter.

If you want a script to be runnable directly, give it a shebang as the first line. Files marked executable on the source machine but lacking a shebang (rare) will round-trip as non-executable; add a shebang to preserve the bit.

---

Notes on undocumented commands

Two commands are present in the binary but intentionally not promoted in user-facing docs:

• airskills bundle — bundles still exist in the API (bundle create | list | show | delete) but the user-facing primitive going forward is skillsets. New code should reach for skillsets.
• airskills completion — the cobra-generated shell completion helper. Run airskills completion --help for shell-specific instructions.