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:- 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.
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:
revision_id you read as expected_revision_id; a stale one answers 409 skill_revision_conflict.

