Skip to main content
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

Skills in a shared Workspace belong to the Workspace: every Reason in it can use them. See Workspaces and sharing.

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:
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. In the app. Open Customize, then 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: 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

--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. A new skill needs a name and instructions. Add a description so Reason can pick it:
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, including the migrate-to-reason skill that moves your own skills, rules and custom commands from another agent platform.