# Skills

> Teach the agent how you do one kind of task, in your own words. Skills work with every AI choice.

Source: https://graspable.dev/docs/skills

A skill is a folder with a file named `SKILL.md`: instructions for one kind of task. The agent sees the list of your skills and reads one when a task calls for it. Skills work the same with the Graspable agent, Claude Code and Codex.

Use a skill for things you would otherwise repeat in every request: how your studio lights a scene, your naming rules, the steps to export for a client.

## Write one

```markdown
---
name: scene-lighting
description: How we light scenes. Use for any new scene or when lighting looks flat.
---

Use one warm key light at intensity 2.4 from the upper left, and a cool rim light.
Never use ambient light above 0.3. Colours are in palette.md.
```

- `name`: lowercase letters, digits and dashes.
- `description`: one or two sentences that say what the skill covers and when to use it. The agent decides from this line alone, so be specific.
- The rest is the instructions. Other files in the folder can be referred to by name; the agent reads them when the instructions point to them.

## Add it

Open **Settings → Plugins and connectors → Skills**, paste the folder's path and choose **Add skill**. Graspable copies the folder into `~/.graspable/skills`.

From a terminal:

```bash
grasp skills add ./scene-lighting
grasp skills
```

A [plugin](https://graspable.dev/docs/plugins.md) can bring skills too. When your own skill has the same name as a plugin's, yours is used.

## How the agent uses them

The names and descriptions of your skills are part of every run's prompt. When a task matches one, the agent reads the skill and follows it. You can see this in the run as a `use_skill` step, and the list itself under **Context**.

Skills that already follow this layout for other tools, a folder with a `SKILL.md` that has `name` and `description`, can be added as they are.