---
title: "Publish and install skills from the CLI"
description: "Publish a skill folder to a project, install a published skill on your computer, and keep the two in step with sfora skills."
canonical: "https://www.sfora.ai/docs/developers/cli/skills"
---
# Publish and install skills from the CLI

> Publish a skill folder to a project, install a published skill on your computer, and keep the two in step with sfora skills.

Source: https://www.sfora.ai/docs/developers/cli/skills

`sfora skills` moves **skills** between folders on your computer and a project. A skill is a folder with a `SKILL.md` and any scripts, references and other files it needs. The CLI keeps every byte and every executable flag, and it never runs a skill's scripts. For what skills are in the app, see [Skills: shared instructions for agents](https://www.sfora.ai/docs/agents/skills).

The commands that talk to a project use your signed-in key, like every other command; see [The sfora CLI: install and sign in](https://www.sfora.ai/docs/developers/cli). The commands that only look at your computer need no account. Every command prints JSON.

## Limits

A skill bundle holds 1 to 1,000 files. Each file is at most 5 MB, and the whole bundle at most 20 MB. A skill's name is lowercase letters, digits and hyphens, up to 64 characters. The CLI refuses symbolic links and paths that leave the folder.

## Publish a skill

```bash
sfora skills list --project web
sfora skills push ./release-notes --project web --expected-version 0
```

`push` uploads the folder as a draft and publishes it, in two checked steps. `--expected-version` is the version you think is published now: `0` for a new skill. To update a skill that already exists, read its version and draft revision with `skills list` and pass both:

```bash
sfora skills push ./release-notes --project web --expected-version 3 --expected-revision 7
```

If someone published or saved a draft since you read them, the push stops instead of replacing their work. Read them again and retry.

## Install a published skill

```bash
sfora skills install release-notes --project web --skills-target ~/.agents/skills
```

It downloads the latest published version into a new folder inside `--skills-target`, and records that sfora installed it. `--version <n>` installs a particular version. It never replaces a folder sfora didn't install, and it refuses to update or remove an install you changed locally.

| Command | What it does |
|---|---|
| `skills install <name> --project <slug> --skills-target <dir> [--version <n>]` | Installs a published skill. |
| `skills pull <name> <bundle.json> --project <slug> [--version <n>]` | Saves a published skill as one bundle file. It won't overwrite an existing file. |
| `skills install-file <bundle.json> --skills-target <dir>` | Installs from a bundle file, with no network. |
| `skills diff <folder> <name> --project <slug> [--version <n>]` | Compares a local folder with a published version. |
| `skills uninstall <installed-folder>` | Removes an install, only if sfora installed it and it is unchanged. |

Published skills also show in the workspace tree, read-only:

```bash
sfora ls /projects/web/skills
sfora cat /projects/web/skills/release-notes/SKILL.md
```

## Find the skills on your computer

The CLI keeps a list of the skill folders it knows, shared with the Sfora app for macOS. It lives in `~/.sfora/skills/`.

| Command | What it does |
|---|---|
| `skills roots` | Lists the folders the CLI searches for skills. |
| `skills roots add <folder> [label]` | Adds a folder to search. |
| `skills roots add-project <folder> [label]` | Adds a project's folder to search. |
| `skills roots remove <id>` | Stops searching a folder. It deletes no files. |
| `skills scan [folder…]` | Finds complete skills in the folders you name. |
| `skills inventory` | Searches every folder and lists each skill with its id and any warnings. |
| `skills index` | Lists what the last search found, without searching again. |

```bash
sfora skills roots add ~/.agents/skills "Agent skills"
sfora skills inventory --json
```

Two copies of a skill stay separate, even with the same name and content, until you link one to a project's skill.

## Link a local skill to a project

A **binding** links one local skill to one published skill, so the CLI can tell which side changed.

| Command | What it does |
|---|---|
| `skills bind <location-id> <cloud-name> --project <slug>` | Links a local skill to a published one. Take the location id from `skills inventory`. |
| `skills bindings` | Lists your bindings. |
| `skills status <binding-id>` | Says whether the two sides match, which one changed, or whether both did. |
| `skills plan <binding-id> push` | Previews a push: every file, hash and conflict. It writes nothing. |
| `skills plan <binding-id> pull` | Previews a pull the same way. |
| `skills plan-install <name> --project <slug> --skills-target <dir>` | Previews installing into a folder that doesn't exist yet. |
| `skills relocate <location-id> <folder>` | Keeps a skill's identity after you move its folder. |

## Run a reviewed plan

A plan you saved to a file can be queued and run. The CLI checks it again against the current files and the published version before it writes, and keeps a record of each run, so an interrupted run can be finished later.

```bash
sfora skills plan <binding-id> push --json > push-plan.json
sfora skills apply push-plan.json
```

| Command | What it does |
|---|---|
| `skills queue <plan.json>` | Queues a plan without running it. |
| `skills apply <plan.json\|operation-id>` | Runs a plan file, or a queued run by its id. |
| `skills operations` | Lists runs and their outcomes, including any that need recovery. |
| `skills recover <operation-id>` | Finishes an interrupted run without repeating what already landed. |
| `skills cancel <operation-id>` | Cancels a run that hasn't started. |
| `skills apply-batch <ids.json>` | Runs several queued runs, from a JSON array of ids. |
| `skills recover-batch <ids.json>` | Recovers several runs the same way. |

`ctrl+C` during a batch stops after the current run and cancels the rest.

## Troubleshooting

### "--expected-version is required"

`push` needs the version you expect. Use `0` for a new skill, or the version `skills list` shows.

### The push stops with a conflict

The skill changed since you read it. Run `skills list` again and push with the new version and revision.

### Install refuses the target folder

A folder with that name exists and sfora didn't install it, or you changed the install. Pick another `--skills-target`, or save your changes first.

Related: https://www.sfora.ai/docs/agents/skills, https://www.sfora.ai/docs/developers/cli/commands, https://www.sfora.ai/docs/developers/cli
