Skip to main content
A skill is a Markdown file of instructions for one kind of task, such as cutting a release, writing a migration, or reviewing an API change. The model can list and search your skills by their short descriptions and load the full instructions only when a task calls for them. You can also run a skill yourself as a slash command. Write a skill when you find yourself giving o4 the same multi-step instructions again and again. For rules that should apply to every session in a project, use project instructions instead.

​
Create a skill

Each skill is a folder with a SKILL.md file in it. The folder name is the skill’s name. To make a skill for this project, create .o4/skills/release-notes/SKILL.md:
Start a new o4 session, then run it with:
o4 builds its list of skill slash commands when a session starts, so a skill you add by hand gets its slash command in the next session. The model can find it right away, because its skill tool reads the folders each time. You can also create one from /skills: choose Create new skill, enter a name, pick the location (project or user), and o4 writes a SKILL.md template and opens it in your editor. A skill created this way works as a slash command right away.

​
Where skills live

When two skills have the same name, a project skill wins over a user skill, a user skill wins over a plugin skill, and a plugin skill wins over a built-in one. o4 ignores a project’s .o4/skills folder until you trust the workspace, so a repository you just cloned can’t add instructions to your sessions. See Workspace trust. To install skills that others have written, install a plugin that contains them. o4 calls these plugins skill packs. See Plugins and marketplaces.

​
Built-in skills

o4 ships with five skills that the model can load: Built-in skills don’t appear in /skills and don’t have slash commands. To change how one works, create a project or user skill with the same name.

​
The SKILL.md format

A SKILL.md file is Markdown with optional YAML front matter between --- lines. A skill must be a regular file, not a symlink, and at most 1 MiB.
​
string
What the model sees when it lists or searches skills. Write it so the model can tell when the skill applies. Without it, o4 uses the first non-empty line of the body, without any leading #. The model sees at most 200 characters. For project and user skills, /skills and the slash command menu always show the body’s first line instead.
​
string
Set to fork to hand the skill to a subagent when you invoke it as a slash command. o4 shows “Running <name> in background…” and sends the model the skill’s text with a request to run it as a subagent; the model then starts one with its agent tool. See Subagents.
​
string[]
Shown in the skill’s details in /skills. For project and user skills it doesn’t limit which tools the model can use. In a plugin’s skill, a tool that isn’t in the plugin’s permissions.tools keeps the skill from loading. See Plugins and marketplaces.
​
string
Shown in the skill’s details in /skills. o4 doesn’t switch models for the skill.
​
list
Hooks that run only while the skill runs. Each has an event, an optional matcher and a command. See Hooks in skills.
​
boolean
default:"false"
When true, running the skill as a slash command shows its text in o4 without sending it to the model. Use it for checklists and reference notes you want to read yourself.
A project or user skill’s name always comes from its folder name; a name field in the front matter doesn’t change it. In a plugin’s skill, a name field sets the slash command name and the name in /skills, but the model’s skill tool still uses the folder name. Keep the two the same.

​
Arguments

When you run a skill as a slash command, o4 replaces every $ARGUMENTS in the body with the text you typed after the command. If you type nothing, $ARGUMENTS becomes an empty string. In a plugin’s skill, o4 also replaces $CWD with the working directory and $O4_PLUGIN_ROOT with the plugin’s folder. When the model loads a skill with its skill tool, it gets the body without any replacements.

​
Shell commands in skills

o4 never runs a line in the body that starts with !. When you run a project or user skill as a slash command, o4 replaces each such line with a note like this before the model sees it:
When the model loads a skill with its skill tool, or you run a plugin’s skill, the line reaches the model as written, and still isn’t run. If a skill needs a command’s output, tell the model to run the command. It then goes through the normal approval, sandbox, and hook checks.

​
How the model uses skills

The model has a skill tool with three uses:
  • With no arguments, it lists the available skills with their names, where each comes from, and their descriptions. It shows up to 50.
  • With query, it searches skill names and descriptions.
  • With name, it loads that skill’s full instructions.
Skill text isn’t added to the model’s context until the model loads a skill, so having many skills costs little. The skill tool never asks for approval, because it only reads instructions. A clear description is what lets the model find the right skill.

​
Run a skill yourself

Type / and the skill’s name, followed by any arguments:
o4 loads the skill, fills in $ARGUMENTS, and sends it to the model as your next message. Built-in slash commands take precedence, so a skill named help can’t replace /help. Skills from plugins run the same way.

​
Manage skills with /skills

/skills opens the skill browser. Its tabs are All, Project, User, Plugin, and Errors. The Errors tab lists skills that failed to load, such as a SKILL.md with invalid front matter, and notes when project skills were skipped because the workspace isn’t trusted. Select a skill to see its details and act on it:
  • Select skill puts /<name> in the prompt so you can add arguments.
  • Edit skill opens the SKILL.md in your editor.
  • Delete skill removes it.
  • View definition shows the skill’s description and where it comes from. In o4 0.2.74, selecting it does nothing more.
A skill that Project Scout turned off has Enable skill instead of Select skill. It removes the skill from disabled_skills in the project’s .o4/config.toml. While a skill is turned off, it’s left out of the slash command menu, and running it only shows “Skill ‘<name>’ is disabled by Project Scout.” The model can still load it with its skill tool. You can’t edit or delete plugin skills from the browser. Change or remove the plugin instead. While the model is working, you can still open the browser, select a skill, and use Enable skill, but creating, editing or deleting a skill is refused: o4 closes the browser and shows Wait for the current turn to finish before making this change. You can also jump straight to an action: The Skills tab in /config (run /config skills to go straight to it) has two rows:
  • Open skill browser opens the same skill browser as /skills.
  • Install skill packs opens the plugin browser, the same as /plugins, where you can find and install plugins that bundle skills. See Plugins and marketplaces.