# Create a skill

At the end of this guide an agent has a skill of yours: instructions it loads when a question needs them, with reference files it reads on demand, and a slash command that turns a repeated request into one line. An organization skill needs the **Manage organization skills** permission, and you become its Admin; a private skill for your own assistant needs **Create private skills**. Attaching a skill to a shared agent is an admin's job.

## Before you begin

- **Manage organization skills** (for an organization skill) or **Create private skills** (for a private one).
- For scripts, a sandbox profile you can bind to the skill.
- An agent to give the skill to: your personal assistant, or a shared agent whose settings you manage.

## Write the `SKILL.md`

1. Make a folder named after the skill, such as `release-checklist`, and put a `SKILL.md` in it.
2. Write the frontmatter: `name` is the slug (lowercase letters, digits and hyphens), `description` says what the skill does and when to use it.
3. Write the instructions in the body. Keep them short; move long procedures into reference files.

```text
---
name: release-checklist
description: Walks a release through its checklist and drafts the release notes page. Use when someone prepares, checks or announces a release.
allowed-tools: search_pages read_page create_page update_page
---

## When activated

1. Read `references/checklist.md` and go through it item by item.
2. Search for an existing release notes page before creating a new one.
3. Never invent version numbers or dates. Ask when they are not given.
```

> **Note:** `allowed-tools` is a suggestion. Volobox maps the built-in tool keys it knows, shows unknown ones as warnings, and grants nothing: the people who configure the skill decide what it may use.

## Add reference files or scripts (optional)

1. Put each file in the skill's folder. Files keep the path they have relative to `SKILL.md`. Text documents (markdown, JSON, YAML, CSV and similar) are references the agent reads on demand; runnable files outside `references/` and `assets/` are scripts.

   ```text
   release-checklist/
     SKILL.md
     references/
       checklist.md
     scripts/
       collect_changes.py
   ```

2. Zip the folder for import. A zip can hold several skills: every folder with an exact `SKILL.md` is one. The format is in [Skills and packs](/docs/skill-and-pack-formats).

## Import the skill

1. For an organization skill, open **Organization Settings** > **AI** > **Skills**, stay on **Organization** and choose **Import**. For a private skill, open your **Personal Settings** > **AI** > **Skills**, then **Private** > **Import**.
2. Choose **Paste SKILL.md** and paste the document, or **Upload zip** and choose **Upload bundle (.zip)**.
3. Choose **Preview**. Check the slug, description, body, suggested built-in tools, the files that will be imported, the files that will not be imported (each with its reason), and the warnings.
4. If a skill with the same slug exists, the preview names it and offers **Overwrite** when you may overwrite it. Otherwise rename the skill in the file.
5. Choose **Import skill**. The skill opens.

![Organization Settings on the AI tab, Skills: the Skill library with Organization and System tabs, Import and Create skill buttons, and Meridian Works skills as cards (Brand voice, Client communications, Fieldwork repository, Meridian release process, QA checklist, Research synthesis), each with who can use it, its description and its tools.](https://volobox.io/docs/images/skills-library.light.webp)

*The Skill library in Organization Settings, AI, Skills: the Organization tab with Import and Create skill, and the organization's skills as cards.*

To change it later, edit it in place (text files on its **Files** tab can be edited in the browser), or use **⋯** > **Replace from file…** on the skill.

### Let its scripts run

1. On the skill's **Sandbox** tab, bind a sandbox profile. Without one, scripts are readable but never run.
2. Each run then raises an approval card with the exact command line before it runs.
3. For scheduled or event-triggered workflows, an administrator opens the organization skill, finds **Unattended automation**, selects **Trust for automations**, reviews the content hash and every file, and selects **Trust this revision**. Changing the skill's content revokes the trust.

## Give it to an agent

1. Open the agent's settings: your personal assistant's, or, for a shared agent, the agent's (admins).
2. Open **Skills** > **Default skills**.
3. Choose the skill in **Add a skill…** and add it. On a shared agent, people without access to the skill do not see or load it when they chat with the agent.

The agent starts each turn with a small baseline of tools and turns a skill on when a question needs it, so you do not have to mention the skill by name.

> **Warning: Enable and Disable apply to everyone**
>
> **Enable** and **Disable** on a skill's card or page turn it on or off for everyone who uses it, not only for you. A turned-off skill does not load, even when an agent has it.

## Add a slash command

1. Open **Commands** in your **Personal Settings** > **AI** (or in **Organization Settings** > **AI** for an organization command) and choose **Create command**.
2. Set the **Handle** (lowercase, typed after `/`), such as `release-prepare`, the **Display name** and a starting **Prompt template**, then choose **Save and edit details**.
3. On the **Prompt** tab, write the template. `{{args}}` takes the free text after the handle; `{{version}}` takes a named input.

   ```text
   Prepare release {{version}} with the release checklist. {{args}}
   ```

4. On the **Inputs** tab, add the input: **Label** "Version", **Name** `version`, **Type** **Free text**, required.
5. Save, and attach the command to the agent if it is not **Available on all agents**. To use it in coding sessions too, turn on **Usable in coding sessions** on **Overall**.

A command can also name skills it always enables or suggests. A prompt you already sent can become a command: hover your own message in an agent chat and choose **Save as command**.

## Check that it works

- In a chat with the agent, ask something the skill's `description` covers. The agent turns the skill on and follows its instructions, reading `references/checklist.md` when it needs it.
- Type `/` in the composer: the command is listed. Send `/release-prepare version=2.4.0 focus on the API changes`, and the agent receives the rendered prompt, not the slash line.
- A script run shows an approval card with its command line.

## Troubleshooting

| Symptom | Fix |
| --- | --- |
| The import is rejected as an existing slug | Choose **Overwrite** if you may, or rename the skill in the file. A personal import cannot overwrite an organization skill; use **Replace from file…** on the skill instead |
| A file was not imported | The preview and the result list each skipped file with its reason, such as an executable type or a path with characters that are not allowed |
| The agent never uses the skill | Check that the skill is turned on, attached to the agent, and that you have access to it |
| A script is readable but does not run | Bind a sandbox profile on the skill's **Sandbox** tab |
| A scheduled workflow cannot run the skill's script | Trust the current revision under **Unattended automation** |
| The command is missing from the `/` menu | Check that it is enabled, that you can access it, and that it is attached to the agent (or **Usable in coding sessions** for a coding session) |
| A value is not substituted | The template must contain `{{exact_name}}` matching the input's **Name** |

## Next steps

- [Skills and packs](/docs/skill-and-pack-formats)
- [Host a pack registry](/docs/host-pack-registry)
- [Agents](/docs/agents)
- [Write a code workflow](/docs/write-code-workflow)
