> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rerun.build/llms.txt
> Use this file to discover all available pages before exploring further.

# Skills

> Teach an agent a procedure it loads only when it needs it.

A skill is a written procedure. The agent reads it when the task at hand matches its description, and ignores it the rest of the time.

Skills are how you make an agent good at something specific without turning its system prompt into a manual.

## What a skill looks like

A skill is a folder, not a single file. It holds a `SKILL.md` and any reference files you want to give it.

```markdown SKILL.md theme={"system"}
---
name: Weekly report
description: Use when asked for the weekly numbers, on Monday or on demand.
---

1. Query the `sales` table for the last 7 days
2. Follow the layout in `references/format.md`
3. Write the report to the shared folder as `reports/<week>.md`
4. Post the link in Slack
```

Two fields matter in the frontmatter:

* **`name`** gives the skill its slug, which is how everything addresses it.
* **`description`** is what makes the agent decide to open the skill. Write it as a trigger condition, not as a summary. "Use when asked for the weekly numbers" beats "About weekly numbers".

## Why it stays out of the way

Skills load in three layers:

<Steps>
  <Step title="Always in context">
    A one-line index: the name, the slug and the description of every skill. Nothing else.
  </Step>

  <Step title="On demand">
    When a task matches, the agent opens the skill and reads the whole procedure.
  </Step>

  <Step title="At the exact step">
    It opens a reference file only when the procedure tells it to.
  </Step>
</Steps>

That is why a skill can carry a long reference corpus without costing anything on every run. Keep the body short and push the detail into `references/`.

## Create and edit one

<Tabs>
  <Tab title="In the app">
    Open the agent panel, go to the **Skills** tab, and click **New**. Write the name, the description and the body. Reference files are added from the same editor.
  </Tab>

  <Tab title="Ask the agent">
    Tell it what to do and to remember the procedure. It writes the skill itself, as long as the `skills` capability is on.
  </Tab>

  <Tab title="From the API">
    [`upsert_skill`](/api/tools/skills#upsert-skill) writes the body and the reference files in one atomic call. This is how you version skills in a repository.
  </Tab>
</Tabs>

## When to write a skill instead of something else

| Situation                                              | Where it belongs                       |
| ------------------------------------------------------ | -------------------------------------- |
| A repeatable procedure with steps                      | A skill                                |
| Who the agent is and how it behaves                    | The [soul](/agents/configure#the-soul) |
| A fact it should remember, like a preference or a name | [Memory](/concepts#memory)             |
| Reference material that is long and rarely needed      | A reference file inside a skill        |

When you correct an agent behaviour and the correction is a rule rather than a fact, fix the skill that governs it. A memory can be outvoted by a procedure, a procedure cannot.

## Limits

* A skill lists up to 200 bundled files.
* A reference file is read up to 100,000 characters at a time.
* `SKILL.md` itself cannot be written through the file tools. Change it through the skill body.