# Add a Mindset Skill

> Gives agents shared instructions they load only when a request needs them, such as a policy, a process or a set of templates.

Building an agent goes in order: build the agent, connect your systems, add functions, scripts, Skills and widgets, test it, take it live, then put it in your product. Highlighted: Add functions, scripts, Skills and widgets.

A [Mindset Skill](https://docs.mindset.ai/docs/mindset-skills) holds instructions your agents load when a request matches its description. Your coding agent writes it and attaches it, and a person makes it live in the Studio.

## Ask your coding agent

```
Write a Mindset Skill called supplier-queries from our finance team's notes below: when an invoice difference is worth querying with the supplier, and how to word the query. Put the email templates in a references file, and give me the link to activate it. Once I've enabled it, attach it to the invoice exceptions agent and try it on INV-4471 before I activate the agent version.
```

Skill: [mindset-build-agent](https://docs.mindset.ai/skills/mindset-build-agent/SKILL.md)

## What gets built

Your coding agent writes the Skill's name, description, instructions and any text files, and saves them as version 1. It then attaches the Skill to the agent, which saves a new agent version. Nothing reaches users until a person activates the Skill version, enables the Skill and activates the agent version.

## Best practice

- **Write the description in the words a user asks with.** Along with the name, it's all the agent reads before deciding to load the Skill, so say what the Skill does and when to use it. "Helps with suppliers" never gets loaded. "Use when an invoice differs from its purchase order and you're deciding whether to query the supplier, or writing the query" does.
- **Give each Skill one job.** When two descriptions overlap, the agent has to guess which to load.
- **Keep the instructions short and move detail into files.** The agent reads every line of the instructions each time it loads the Skill. Aim for under about 500 lines, put templates and long reference in files, and name each file in the instructions with what it's for.
- **Keep hard rules out of Skills.** An agent follows a Skill's instructions, but Mindset doesn't enforce them. A rule that must hold every time belongs in a [script](https://docs.mindset.ai/docs/write-a-script) or a [function](https://docs.mindset.ai/docs/build-a-function).

## Go live

An agent loads a Skill only when the Skill has an active version, the Skill is enabled, and the agent version that holds it is active. A new Skill starts disabled, and activating a version doesn't enable it, so the first two are separate steps. See [Versions, testing and going live](https://docs.mindset.ai/docs/versions-and-going-live).

> **Info:** Your coding agent can't activate, enable or delete a Skill. A person does that in the Studio, or your own system does it through the [Skills API](https://docs.mindset.ai/docs/skills-api).

### 1. Activate the version

Open the link your coding agent gives you to the Skill's **Versions** tab, open the version's **…** menu and choose **Activate version 1**.

### 2. Enable the Skill

Turn on **Enabled** on the same tab.

### 3. Attach it and try it

Your coding agent attaches the Skill and runs the new agent version once, without activating it, on a request the description covers.

### 4. Activate the agent version

On the agent's **Versions & Availability** tab.

## Done when

- The Skill shows **Enabled**, and the version you meant is active.
- The Skill's **Overview** lists the agent under **Attached to**.
- A request the description covers made the agent load the Skill, and the reply followed it.

## Change it

Each change your coding agent saves is a new version, and nothing uses it until a person activates it on **Versions**. From then, every agent that holds the Skill uses it from its next turn, with no new agent version. To roll back, activate an earlier version. To take a Skill away from every agent at once and keep it, turn off **Enabled**.

## Delete it

In the Studio, open the Skill's **…** menu on the **Skills** list and choose **Delete**. If any agent's active version holds it, the dialog names those agents before you confirm with **Delete Skill**, and asks again if that list has changed. Your own system can delete one through the Skills API, which also refuses until the call confirms that list.

Deleting removes every version and can't be undone. The handle is free to use again.

## Bring skills you already have

A skill folder in the Agent Skills format, such as one written for any coding agent, comes across with its `SKILL.md` and text files. Leave out any scripts and programs: Mindset refuses them, because it doesn't run a Skill's code.

To keep many Skills in step with a repository, push them from your own system with the [Skills API](https://docs.mindset.ai/docs/skills-api) and a **Skills only** API key. The API doesn't attach Skills to agents, so your coding agent still does that. Your backend can also give one embedded session extra Skills: see [Skills for one session](https://docs.mindset.ai/docs/session-api#skills-for-one-session).

## Limits

- **50 Skills**: Per agent
- **1,024 characters**: Per description
- **64 characters**: Per handle: lowercase letters, digits and hyphens
- **4 MiB**: Per version, text files only

## In the Studio

**Skills** lists every Skill in the environment with its status. Skills aren't written in the Studio, so **Copy prompt to create** gives you a prompt for your AI tool instead. Each Skill's **…** menu has **Enable** or **Disable**, and **Delete**. A Skill's page has an **Overview** (description, status, the agents it's **Attached to** and its load count for the last 30 days), its **Contents** for each version, and its **Versions** with the **Enabled** switch. An agent's **Resources** tab lists the Skills it holds.
