> ## Documentation Index
> Fetch the complete documentation index at: https://ara-90a60a07.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Skills

> Skills are reusable instructions a Reason picks up when a task matches their description. Write, import and remove skills, with the CLI and API for them.

A skill is a reusable set of instructions for one kind of task. Each skill has a name, a description and a document of instructions. Reason matches a skill's description against the task in front of it, and an agent that picks the skill follows its instructions.

The description is how a skill gets chosen. Say in it what the skill does and when to use it.

A skill can be a single document, or a folder: a `SKILL.md` file with companion text files beside it, such as scripts, references and templates. A `SKILL.md` file starts with frontmatter that gives the skill's `name` and `description`.

## Where skills come from

| Source | How it gets there | Can you change it |
| - | - | - |
| Authored | You or a Reason write it in the Workspace | Yes |
| GitHub | Imported from a repository folder that holds one or more `SKILL.md` files | Importing the same folder again updates it |
| skills.sh | Installed from the skills.sh listing | It can be removed, not edited |
| A plugin | Installed with the plugin as one of its bundled skills. See [Manage plugins](https://ara-90a60a07.mintlify.site/docs/build/manage-plugins.md) | Read-only |
| A repository | `SKILL.md` folders in `.agents/skills` or `.claude/skills` of a connected repository load in Sessions on that repository, with nothing to install | Edit them in the repository |

Skills in a shared Workspace belong to the Workspace: every Reason in it can use them. See [Workspaces and sharing](https://ara-90a60a07.mintlify.site/docs/workspaces.md).

## Add a skill

**Ask a Reason.** Describe the way of working you want kept, or give it a GitHub link to a skill folder, and it saves the skill for you:

```text theme={null}
Make a skill from how we just cut that release, so you do it the same way next time.
```

```text theme={null}
Install the skills in github.com/acme/agent-skills/tree/main/skills.
```

A Reason reads a GitHub folder with the Workspace's GitHub App, so private repositories it can reach work. If the repository is not connected, give the Reason GitHub App access to it first. See [Connect GitHub](https://ara-90a60a07.mintlify.site/docs/github.md#connect-github).

**In the app.** Open [**Customize**, then **Skills**](https://reasonmachines.com/customize?tab=skills):

* **Search skills** searches skills.sh and installs a listed skill with all its files.
* **Import from GitHub** takes a link to one skill's folder, a folder of skills or a whole repository. Every file comes along.
* **New skill** opens a chat where a Reason helps you write one.

Installed skills are listed under **Installed**, each with where it came from. A skill's menu has **Open** and **Uninstall**.

**In a repository.** Commit a folder with a `SKILL.md` file under `.agents/skills` or `.claude/skills`. Sessions on that repository find it there.

## Limits

A skill that is a folder holds text files only:

| Rule | Value |
| - | - |
| Files in one skill | 160 |
| Size of one file | 2 MiB |
| Size of the whole skill | 3 MiB |
| Skills in one GitHub import | 50 |

The file count includes `SKILL.md`. Leave out images, fonts and archives: a binary file is refused. Two skills in a Workspace cannot share a name.

## Turn a skill off, change it or remove it

* Through the API, a skill can be disabled without deleting it (`is_enabled`). Agents are not offered a disabled skill.
* Changing an authored skill keeps its id. Sending a new set of companion files replaces the old set: a file left out is removed.
* Skills you wrote and skills installed from skills.sh can be deleted. Skills that came with a plugin, and Reason's built-in skills, are read-only. Uninstalling a plugin removes its bundled skills.

## From a terminal

```bash theme={null}
reason skills list
reason skills get SKILL_ID
reason skills create --input-file skill.json
reason skills update SKILL_ID --input-file skill.json
reason skills delete SKILL_ID
```

`--input-file` takes a JSON file, or `-` for stdin. `reason tools describe createSkill` shows the exact fields.

## API

Every call needs an API key with the scope shown. See [Authentication and scopes](https://ara-90a60a07.mintlify.site/docs/build/auth-and-scopes.md).

| Do | Call | Scope |
| - | - | - |
| List skills | [`GET /v3/organizations/{orgId}/skills`](https://ara-90a60a07.mintlify.site/api-reference/skills/list-skills) | `skills:read` |
| Read one | [`GET .../skills/{skillId}`](https://ara-90a60a07.mintlify.site/api-reference/skills/retrieve-a-skill) | `skills:read` |
| Create one | [`POST .../skills`](https://ara-90a60a07.mintlify.site/api-reference/skills/create-a-skill) | `skills:write` |
| Change one | [`PUT .../skills/{skillId}`](https://ara-90a60a07.mintlify.site/api-reference/skills/update-a-skill) | `skills:write` |
| Delete one | [`DELETE .../skills/{skillId}`](https://ara-90a60a07.mintlify.site/api-reference/skills/delete-a-skill) | `skills:write` |

A new skill needs a `name` and `instructions`. Add a `description` so Reason can pick it:

```bash theme={null}
curl -sS -X POST "https://api.reasonmachines.com/v3/organizations/$ORG_ID/skills" \
  -H "Authorization: Bearer $REASON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "release-notes",
    "description": "Writes release notes from merged pull requests. Use when asked for release notes or a changelog entry.",
    "instructions": "List the pull requests merged since the last tag. Group them by area. Write one plain sentence for each."
  }'
```

To change a skill only if nobody changed it since you read it, send the `revision_id` you read as `expected_revision_id`; a stale one answers `409 skill_revision_conflict`.

## Reason's public skills

Reason publishes reusable skills at [github.com/reason-machines/skills](https://github.com/reason-machines/skills), including the [migrate-to-reason skill](https://ara-90a60a07.mintlify.site/docs/migrate-to-reason.md) that moves your own skills, rules and custom commands from another agent platform.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.