Publish a skill folder to a project, install a published skill on your computer, and keep the two in step with sfora 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.

The commands that talk to a project use your signed-in key, like every other command; see The sfora 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

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:

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

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:

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.

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.

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.

⌃CtrlC during a batch stops after the current run and cancels the rest.

Skills from the CLI

Limits

Publish a skill

Install a published skill

Find the skills on your computer

Link a local skill to a project

Run a reviewed plan

Troubleshooting

"--expected-version is required"

The push stops with a conflict

Install refuses the target folder