Skill files (SKILL.md)

On your computer, a skill is a folder with a SKILL.md file inside, or a single .md file. This page covers the file's shape and its top block, where Oda finds skill files, and what happens when a file fails its checks. To add a skill from a chat, see Create and install skills; to manage the skills on your computer, see Manage your skills.

What a skill file looks like

A skill folder sits directly inside a skills folder, and the SKILL.md inside it is what makes it a skill:

<skills folder>/
  review-checklist/
    SKILL.md
    references/
      format.md

• Oda looks one level deep: a skill folder must sit directly inside a skills folder, and a SKILL.md placed further down is not found.
• A single .md file directly inside a skills folder works too; Oda reads it as one skill.
• SKILL.md is a plain text file: a settings block between two --- lines at the top, and the skill's instructions below it.
• When Oda saves a skill, it writes any extra files first and SKILL.md last, so a half-saved skill never appears.

The lines at the top of the file

The block between the two --- lines is the skill's frontmatter: settings written as plain line: value pairs.

• name (required): the skill's name, in lowercase letters, digits and single hyphens, at most 64 characters, such as review-checklist. It becomes the command you run, /<name>.
• description (required): what the skill does and when to use it, at most 1024 characters. It is the only text Oda sees before loading the skill, so say when it applies.
• whenToUse (optional): a longer note on when to use the skill, at most 1024 characters.
• metadata (optional), and any other lines you add: allowed and kept as you wrote them; they do not change how the skill runs.
• disable-model-invocation: true (optional): Oda never loads the skill on its own; run it yourself with /<name>.
• user-invocable: false (optional): the skill stays out of your / menu; Oda can still load it on its own.

A true or false line accepts true and false, the spellings yes and no, on and off, and 1 and 0, in any letter case. Oda never guesses at a line it cannot read: the whole skill is dropped, and a warning names the field.

---
name: review-checklist
description: Check a change against our review checklist. Use when asked to review a change before it is shared.
whenToUse: When the user asks for a review pass, or a check before sharing.
---

When Oda saves a skill from an install, it writes the top block in the current form: a name such as Weekly Report is written as weekly-report, when_to_use becomes whenToUse, and an older invocation key is written its current way. Everything else, including your extra lines and the instructions below the block, is kept. How the two invocation lines play out in a chat is on Skills: loading and running.

Extra files beside the skill file

A skill can bring extra files beside SKILL.md, commonly under folders named references, scripts and assets. The skill points to them by relative path, such as references/format.md; Oda finds them in the skill's own folder and reads each one only when the skill needs it.

Where Oda finds skill files

Skill files can come from more than one place. When the same name exists in more than one of them, the nearer one is used. The places, from nearest to furthest:

• A project you work in: a project can bring its own skills, and they are used with that project.
• A custom skills folder set up on this computer.
• Your skills folder: the one Settings > Skills manages, where the skills you save are kept.
• A shared skills folder on this computer.
• The skills that come with DataMind Oda; Bundled skills lists them.

Oda keeps its skill list current on its own:

• Adding, renaming or removing a skill, or editing its top block, refreshes the list of skills a chat works from; nothing needs restarting.
• The instructions are read from the file every time the skill is loaded, so an edit takes effect on the next load.
• Editing files inside a skill's references, scripts or assets folders does not change the skill's identity; those files are read when the skill needs them.
• A skills folder that does not exist yet is picked up as soon as it is created.

What happens when a file fails its checks

When Oda saves a skill, from a chat or an install, the file is checked first, and a refusal names what to fix:

• A name that is missing, too long, or not lowercase words joined by single hyphens: The skill name "<name>" is invalid. Use at most 64 lowercase letters, digits and single hyphens, such as review-checklist. or SKILL.md does not name the skill. Add a kebab-case name to its frontmatter.
• A description that is missing or too long: The skill needs a description that says what it does and when to use it. or The description is longer than 1024 characters.
• A when-to-use line that is too long: "When to use" is longer than 1024 characters.
• Empty instructions: The skill needs instructions.
• Too many files, or a SKILL.md above its size limit: The skill holds more than <n> files. or SKILL.md is larger than <size>.
• A top block that is not closed: The SKILL.md frontmatter is not closed with a --- line.

A file you place in a skills folder yourself meets the same rules. When Oda reads the folder, a file that fails is skipped, so the skill simply does not appear, and a warning records the file and the reason:

• skill file <path> ignored: missing YAML frontmatter
• skill file <path> ignored: frontmatter requires name and description
• skill file <path> ignored: invalid skill name "<name>"
• skill file <path> ignored: invalid YAML frontmatter: <detail>

Two more checks apply to the settings lines themselves:

• An older spelling of an invocation line is refused, with the spelling to use: frontmatter field "disableModelInvocation" is unsupported; use "disable-model-invocation".
• A line that should be true or false carries something else: frontmatter field "<key>" must be a boolean.

Fix the named problem and save the file again; Oda reads it afresh.

Questions, answered

What decides the name I run a skill by?

The name line in the top block. It must be lowercase letters, digits and single hyphens, at most 64 characters, and it becomes /<name>. When Oda saves a skill from an install, it writes the name in this form: Weekly Report becomes weekly-report.

Can I write a skill as a single file?

Yes. A single .md file directly inside a skills folder works in the same way as a folder with SKILL.md: Oda reads its top block and its instructions. The rest of this page applies to both forms.

What happens if two skills have the same name?

The nearer place wins, so the name always means the nearest skill file. From nearest to furthest: a project you work in, a custom skills folder, your skills folder, a shared folder, then the skills that come with Oda.

Do I need to restart Oda after adding or editing a skill file?

No. A new, renamed or removed skill, and an edit to its top block, are picked up without a restart; an edit to the instructions takes effect the next time the skill is loaded. A skills folder you have not created yet is picked up as soon as you create it. If a skill still does not appear, check the file against the rules above.

Which lines can a skill file's top block hold?

name and description are required; whenToUse, disable-model-invocation and user-invocable are optional; other lines, such as metadata, are allowed and kept as you wrote them. A true or false line accepts true, false, yes, no, on, off, 1 and 0.

What is the difference between the description and the when-to-use line?

The description is required, says what the skill does and when to use it, and is the only text Oda sees before loading the skill; Oda chooses from it. The whenToUse line is an optional, longer note, at most 1024 characters, that travels with the skill as a note for people, such as in the save request when Oda writes a skill from a chat.

Why does a skill file I wrote not appear?

Most often the file did not pass its checks: its top block is missing or cannot be read, its name or description line is missing or not in the accepted form, or the SKILL.md sits deeper than one level inside a skill folder. Oda skips the file and records the reason, so the skill does not appear and a small typo can look like a missing skill. Fix the named problem or move the file, and Oda picks it up on its own.

What are the references, scripts and assets folders for?

They carry a skill's extra files: reference notes, scripts and other assets that sit beside SKILL.md. The skill points to them by relative path, such as references/format.md; Oda finds them in the skill's folder and reads each one only when the skill needs it.

Does Oda change a skill file when it saves one for me?

When Oda saves a skill from an install, it writes the top block in the current form: a name such as Weekly Report becomes weekly-report, when_to_use becomes whenToUse, and an older invocation key is written its current way. Your extra lines and the instructions are kept.

Can I keep my own notes in a skill file?

Yes. Extra lines, such as metadata, are allowed and are left as you wrote them; they do not change how the skill runs. When Oda saves a skill, it keeps them.