---
title: "Skills: shared instructions for agents"
description: "Share instructions and supporting files with your team and your agents as skills, publish versions, and install them."
canonical: "https://www.sfora.ai/docs/agents/skills"
---
# Skills: shared instructions for agents

> Share instructions and supporting files with your team and your agents as skills, publish versions, and install them.

Source: https://www.sfora.ai/docs/agents/skills

A **skill** is a folder of instructions and supporting files that tells an agent how to do a job, such as writing release notes or triaging bugs. Each skill belongs to a project. The workspace's **Skills** page lists the skills of every project you're in, and each project has a **Skills** page of its own.

## Find a skill

Open **Skills** from **Jump to** in the command palette: press `/` and type its name. While you're on Skills, the sidebar lists **All skills**, then each project; click a project to see its own skills. The Skills page lists your team's skills across projects. Each row shows the skill's project, how many files it has, and its version: **v2** for a published version, **Draft** for unpublished changes, or **Unpublished**.

- Type in **Find a skill…** to search by name or project.
- Pick a project from **All projects** to see only its skills.

Click a skill to open it in its project's **Skills** page. There you read **SKILL.md**, browse the other files, and see **Version history**.

## Add a skill

A skill is a folder with a file named `SKILL.md` at its top. The folder's name is the skill's name: lowercase letters, digits and hyphens, such as `release-notes`.

1. On the **Skills** page, select **Add skills** and pick the project the skill belongs to. Or open the project's **Skills** page directly.
2. Select **Upload folder** and choose the skill's folder. To bring in a bundle someone downloaded from sfora, use the **…** menu and **Import bundle** instead.
3. Check the files, then select **Push draft to Sfora**. The skill is saved as a draft that your project can see.
4. When it's ready, select **Publish v1**. The status reads **Published for your team**.

A folder uploaded from the browser loses its files' executable permissions. Set them in **Source**, or import a bundle, which keeps them.

## Change a skill

1. Open the skill and select **Edit**.
2. Make your changes, then select **Save draft**.
3. Select **Publish** with the next version number, such as **Publish v3**.

Published versions never change. In **Version history**, in the skill's actions menu (**…**), open an older version to read it, or select **Edit as draft** to start a new draft from it. To take a copy with you, select **Download bundle**.

## Install a skill

Agents read skills from sfora with the CLI or the API, so a skill a project publishes is ready for the agents in that project. For the commands, see [Skills commands](https://www.sfora.ai/docs/developers/cli/skills).

To teach your coding agent how to use sfora itself, install the [sfora skills packet](https://www.sfora.ai/docs/agents/skills-packet).

In the desktop app on a Mac, the **Skills** page also has **Install** beside each published skill. It copies the skill into `~/.agents/skills` on your Mac. To put it somewhere else, open the arrow beside **Install** and pick **Choose another folder…**.

## Archive a skill

Open the skill, open its actions menu (**…**), and select **Archive**. Confirm with **Archive skill**. It leaves the project's list and the workspace's **Skills** page. Copies already installed on someone's computer stay there.

On a phone: Works the same on a phone, except **Install**, which only the desktop app has. Above a file, **Read**, **Edit** and **Source** show as icons: the open book, the pencil and the code brackets.

## Availability

- Any member of a project can add, edit, publish and archive its skills.
- A file can be up to 5 MB, and a skill up to 20 MB and 1,000 files in all.
- **Install** is only in the desktop app on a Mac.

## Troubleshooting

### Upload says "Skills support up to 5 MiB per file and 20 MiB total."

A file or the whole folder is too big. Remove large files, such as images or build output, and upload again.

### Upload says "Choose one skill folder at a time."

You picked files from more than one folder. Choose the one folder that holds `SKILL.md`.

### Install isn't there

**Install** is only in the desktop app on a Mac, and only for a skill with a published version. Publish the draft first.

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