Skill files and discovery

On your computer, a skill is a folder with a SKILL.md file inside, or a single .md file. That file decides how the skill is named, when Oda turns to it, and what it does. This page covers the file's shape, where Oda looks for skill files, and the skills that come with Oda. To add a skill, see Create and install skills; to see and manage the skills on your computer, see Skills in Settings.

What a skill file looks like

A skill folder sits directly inside a skills folder, and its SKILL.md is the file that 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 buried deeper inside is not found.
• A single .md file directly inside a skills folder works too; Oda reads it as one skill's file.
• SKILL.md is a text file. Its top block, between two --- lines, carries the settings below; the rest of the file is the skill's instructions.

The lines at the top of the file

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

Two lines are required:

• name: the skill's name. Lowercase letters, digits and single hyphens, at most 64 characters; it becomes the command you run, /<name>.
• description: what the skill does and when to use it, at most 1024 characters. It is the only text Oda sees before loading the skill, and Oda chooses from it.

A few lines are optional:

• whenToUse: a longer note on when to use the skill, at most 1024 characters.
• disable-model-invocation set to true: Oda never loads the skill on its own, and /<name> still runs it. Settings > Skills shows the skill as Only with /name.
• user-invocable set to false: the skill stays out of your / menu, and Oda can still load it. Settings > Skills shows the skill as Not in the / menu.
• Further lines, such as metadata, are allowed; they stay as you wrote them and do not change how the skill runs.

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 does not guess at a misspelled line or a value it does not accept: it drops the whole skill, and the warning names the field. How the two invocation lines play out in a chat is on Skills in chat.

Here is a complete example:

---
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 tidies the file on the way in: a name such as Weekly Report is written as weekly-report, when_to_use becomes whenToUse, and older invocation spellings are written in their current form. Everything else, including your own extra lines, is kept.

Extra files a skill can carry

A skill can bring extra files beside SKILL.md, commonly in folders named references, scripts and assets. When Oda loads a skill it also knows the skill's folder, so a file the skill mentions by a relative path, such as references/format.md, is found where it belongs. Oda loads the files a skill mentions only as needed.

Where Oda finds skills

Oda reads skills from more than one place:

• Your skills folder: the one Settings > Skills manages, where the skills you add are saved.
• A project you work in: a project can carry its own skills, and they run with that project.
• Shared or custom folders set up on your computer.
• The skills that come with Oda itself, listed below.

When the same name exists in more than one place, the nearer one is used: a project skill before one from your own folder, and your own folder before the skills that come with Oda.

Oda keeps its lists up to date on its own:

• Adding, renaming or removing a skill, or editing the lines at its top, is picked up without a restart; a skills folder that does not exist yet is picked up as soon as you create it.
• Oda reads a skill's file fresh every time it loads the skill, so an edit takes effect the next time the skill is loaded.

If a skill file is refused or skipped

When Oda saves a skill, from a chat or from Settings > Skills, 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, empty 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.
• 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 does not pass is skipped: the skill 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 value that is not a boolean on a line that should be true or false: frontmatter field "<key>" must be a boolean.

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

Skills that come with Oda

Several skills come with DataMind Oda itself:

• skill-authoring carries the guidance for writing, testing, finding and installing skills. Oda follows it when you ask it to build a skill or install one.

• office-docx, office-pptx and office-xlsx carry the authoring guidance for Word, PowerPoint and Excel files, each with its own checking tool.

• datamind-badge is optional: the badge for content made with Oda. It is switched off by default and comes in one design; once it is switched on, it becomes available like any other bundled skill.

• They are not in your skills folder: they come with the app, and Settings > Skills lists them as read-only.

• Oda reads each one fresh every time it loads it, and they run like any other skill in a chat. Bundled skills goes through each one in more detail.

Questions, answered

What decides the name I run a skill by?

The name line in the skill's file. It must be lowercase letters, digits and single hyphens, at most 64 characters, and it becomes /<name>. When Oda installs a skill from a source, it normalises the name to this form as it saves it: Weekly Report is written as 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.

Can a skill live outside my skills folder?

Yes. A project you work in can carry its own skills, and shared or custom folders on your computer can too. Oda reads them all, and when the same name exists in more than one place, the nearer one is used: a project skill before one from your own folder, and your own folder before the skills that come with Oda.

Why is a skill file I wrote not showing up?

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

Oda says a frontmatter field is unsupported. What should I write instead?

The warning names the spelling to use. Change the line to that spelling and save the file again. The two invocation lines have one current spelling each: disable-model-invocation and user-invocable; an older spelling, such as disableModelInvocation, is refused rather than guessed at.

Can I keep my own notes in a skill file?

Yes. Extra lines, such as metadata, are allowed and are left as they are; they do not change how the skill runs. When Oda saves a skill from an install, it keeps your extra lines.

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

No. Oda picks up new, renamed and removed skills on its own, and it reads a skill's file fresh every time it loads the skill, so an edit 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.

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. When Oda loads the skill it knows the skill's folder, so a file the skill mentions by a relative path, such as references/format.md, is found where it belongs, and Oda loads such files only as needed.

Where do the skills that come with Oda live?

They are not in your skills folder: they come with the app itself, and Settings > Skills lists them as read-only. Oda reads each one fresh every time it loads it, so what it follows stays in step with your copy of Oda. Bundled skills goes through them.

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, up to 1024 characters, that travels with the skill for people, such as in the save request when Oda writes a skill from a chat.