---
title: Skills
description: Bundles of knowledge and procedure, versioned in a workspace and granted to an agent version.
sidebar:
  order: 4
---

A **skill** is a directory of files with a `SKILL.md` at its root. It carries the knowledge and the step-by-step procedure an agent should follow for some task — the things that would otherwise be pasted into a system prompt and go stale there.

Skills live in a workspace, are versioned, and are granted to an agent version. The same skill can be granted to several agents.

## The bundle

<FileTree>

- refund-policy/
  - SKILL.md
  - reference/
    - tiers.md
    - escalation.md

</FileTree>

`SKILL.md` is required at the bundle root. Its frontmatter names the skill; everything else in the directory travels with it.

| Limit | Value |
| --- | --- |
| Files per bundle | 1,000 |
| Bytes per file | 10 MB |
| Bytes per bundle | 10 MB |
| Symlinks | Refused, never followed |

Symlinks are rejected rather than resolved. Following one would upload a file you never put in the bundle — `ln -s /etc/passwd notes.txt` would ship that file's contents under an innocent name.

## Creating and pushing

The first push creates version 1; every push after that appends the next version.

```bash
subako skill create ./refund-policy
subako skill push <skill-id> ./refund-policy
subako skill versions <skill-id>
```

The whole directory is packed and uploaded each time — a push is a new version of the bundle, not a diff against the last one.

```bash
subako skill list
subako skill show <skill-id>
subako skill rename <skill-id> --display-name "Refund policy"
```

Renaming sets a display name that overrides the bundle's own. Setting it to empty unsets it, and the frontmatter name stands in again.

## Granting a skill

A grant lives in the agent version's configuration. It may pin a version number, or float to the skill's latest at the time each version is published.

## Deleting

```bash
subako skill delete <skill-id>
```

This takes the skill and all of its versions and bundles. It is refused with a 409 while something still depends on it — a published agent version that grants it, or a session still holding it — so those go first.

:::note
A skill is knowledge, not authority. Granting one tells the agent how a job is done; it does not give the agent anywhere to do it. That comes from the MCP servers the version grants and the [vaults](/concepts/vaults) the session names.
:::