Skill files and folders

A skill on your computer is a folder with a SKILL.md file inside, or a single .md file, and you can write or edit it yourself. This page covers what a skill file may contain, where Oda looks for it, and how your edits are picked up. To add a skill from a chat or an install, see Create and install skills; to review and manage the skills on this computer, see The skill library.

How a skill file is laid out

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

text

<skills folder>/
  weekly-report/
    SKILL.md
    references/
      format.md

Oda looks one level deep: a skill folder must sit directly inside a skills folder; a SKILL.md placed further down is not picked up.
You can also use a single .md file directly inside a skills folder; Oda treats it as one skill.
SKILL.md is a plain text file: a settings block at the top, between two --- lines, and the skill's instructions below it.

The top block of a skill file

The top block 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 weekly-report. It becomes the command you run, /<name>.
description (required): what the skill does and when to use it, at most 1024 characters. Oda picks the skill from this line, so say when it applies.
whenToUse (optional): a longer note on when the skill fits, at most 1024 characters.
disable-model-invocation: true (optional): Oda never loads the skill on its own; run it yourself with /<name>.
user-invocable: false (optional): it is hidden from your / menu, and Oda can still load it on its own.
Other lines, such as metadata, are allowed. They are kept exactly as you wrote them and do not change how the skill runs.

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

yaml

---
name: weekly-report
description: Build the weekly sales report from our own files. Use when the user asks for the weekly numbers.
whenToUse: When the user asks for the weekly report or its numbers.
---

In a chat, the two invocation lines decide who can start the skill; Using skills goes through that. When Oda saves a skill from an install, it rewrites the top block into today's spellings: Weekly Report is written as weekly-report, when_to_use becomes whenToUse, and an older invocation key is written the current way. Your own extra lines, like the instructions below them, are kept.

Extra files beside the skill file

A skill folder can hold extra files beside SKILL.md, often under folders named references, scripts and assets. The skill refers to them by relative path, such as references/format.md; Oda reads them from the skill's own folder, and only when the skill needs them.

Where Oda looks for skills

Skill files can come from several places. When the same name exists in two of them, the nearer one wins:

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

A warning records the set-aside skill: skill "<name>" from <source> ignored because a higher-priority skill already exists.

Tip

Open skills folder in Settings > Skills opens your skills folder in your file manager.

How your edits are picked up

Oda keeps its skill lists current on its own:

Adding, renaming or removing a skill, or changing its settings lines, 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 to them takes effect on that next load.
A change inside a skill's references, scripts or assets folders does not refresh the list; Oda reads those files when the skill needs them.
A skills folder you have not created yet is picked up the moment you create it.

If a skill file is skipped

Oda checks each file it reads in a skills folder. A file that fails is skipped, so the skill does not appear, and a warning records the file and why it was skipped:

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 further checks apply to the settings lines:

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.

Correct the named problem and save the file again; Oda picks the file up the next time it reads the folder.

Questions, answered

Can I write and edit skill files myself?

Yes. A skill is a folder and a file, so you can create it in any editor and save it into a skills folder. Write the name and description lines in the top block and the instructions below them, and the skill appears in your chats. Your skills folder takes your personal skills, and a project you work in can carry its own; to have Oda create or install a skill instead, see Create and install skills.

What happens if two skills have the same name?

The nearer place wins. From nearest to furthest: a project you work in, a custom skills folder, your own skills folder, a shared location on this computer, then the skills that come with DataMind Oda. The skill that was set aside is recorded in a warning: skill "<name>" from <source> ignored because a higher-priority skill already exists.

When does an edit to a skill file take effect?

Oda notices on its own, with no restart needed: a new, renamed or removed skill, or a change to the settings lines, refreshes the list, and an edit to the instructions is read the next time the skill loads. Changes inside a skill's references, scripts or assets folders do not refresh the list.

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

name and description are required; whenToUse, disable-model-invocation and user-invocable are optional, and 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.

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

On an install, yes: Oda rewrites the top block so its keys and spellings match the current ones. Weekly Report becomes weekly-report, when_to_use becomes whenToUse, and an older invocation key is written the current way. Your extra lines and the instructions are kept.

Can I add extra files to a skill?

Yes. Extra files commonly sit in references, scripts and assets folders beside SKILL.md, and the skill points to them by relative path, such as references/format.md. Oda reads them from the skill's folder, and only when the skill needs them.

Why did Oda ignore one of my skill files?

The file did not pass its checks: its top block is missing, its name or description line is missing, its name is not valid, or its settings cannot be read. Oda skips the file and records the reason, so the skill does not appear; fix the named problem and save the file again. An older spelling of an invocation line also drops the whole skill, and the warning names the spelling to use.