SKILL.md file, and its instructions load into Ana’s context only when the skill is invoked.
The distinction from an ordinary Ontology file is what the content does. Ontology files encode what your data means — how churn is defined, which table is canonical — and Ana navigates to them as questions require. A skill encodes how to do something: the sequence of a monthly close review, the structure your board deck expects, the reconciliations that must pass before a revenue number is trusted. It loads as a unit, when asked for, and not otherwise.
File Layout
Theskills/ folder sits at the root of your Ontology and is flat — one folder per skill, no nesting:
monthly-close is invoked as /monthly-close. Each folder must contain a file named exactly SKILL.md — case-sensitive, no other filename works. A folder without one is an ordinary folder and is ignored.
SKILL.md
Both
name and description are optional — a SKILL.md with no frontmatter at all still works, it just shows an empty label in the picker. Unrecognized frontmatter keys are ignored rather than treated as errors, so a skill folder written for another agent tool can usually be dropped in unchanged.
Triggers cannot contain
/, \, :, <, or >. A folder named with one of these is skipped rather than offered as a trigger that could never be invoked.How Skills Are Invoked
There are two paths, and both deliver the same instructions. You invoke it by name. Type/ in the chat composer and pick from the autocomplete. The skill becomes a chip in your message, and Ana receives its instructions inline at that point in the conversation. Clicking the chip opens a panel showing what was loaded.
Ana invokes it herself. Ana is given a roster of every skill you can access — trigger and description, never the body — and pulls one in when a description matches what you are asking for. The invocation appears in the chat like any other tool call.
Because of the second path, the description is the highest-leverage thing in the file. It is the only part Ana reads when deciding whether a skill applies, so it needs to state the trigger condition and not just the subject:
The body loads only on invocation, so a long, detailed skill costs nothing on the turns where it is not used. This is what makes it worth being thorough.
Creating a Skill
The fastest way is to ask Ana. Describe the procedure in a chat — “write me a skill for our monthly close review, here are the steps” — and she will create the folder andSKILL.md for you, including the skills/ root if your Ontology does not have one yet. Review what she wrote before relying on it, the same as any other Ana-proposed Ontology change.
To write one by hand instead:
1
Create the skill folder
In the Ontology Files tab, create
skills/ at the root of the tree if it does not exist, then a folder inside it named for your trigger. Lowercase and hyphenated reads best in the composer — monthly-close, not Monthly Close Review.2
Add SKILL.md
Inside that folder, create a Markdown file named
SKILL.md, write the frontmatter and instructions, and save.3
Try it
Open a chat and type
/. The skill should appear in the list — if it does not, refresh the page, as the picker caches the list for the session.skills/<trigger>/SKILL.md there instead and let it sync. It is the same file either way, and skills are versioned in the History tab like everything else in the Ontology.
Role & Access
Skills follow the same folder-level access as the rest of your Ontology. Restrict a skill’s folder to specific roles and it disappears entirely for everyone else: it is absent from their picker, Ana will not consider it on their behalf, and invoking it by name returns nothing. See Role & Access for configuration. This makes skills a reasonable home for team-specific process. A finance close checklist that should not be visible org-wide lives in a restricted folder, with no separate permission model to maintain.Built-in Skills
TextQL ships built-in skills alongside the ones you write — authoring references for.playbook, .dashboard, .tql, and .malloy files, plus a documentation skill covering how TextQL works. They appear in the same picker and require no setup.
If you create a skill whose folder name matches a built-in’s trigger, yours takes precedence. This is the supported way to replace built-in guidance with your organization’s own conventions.
Writing Skills That Work
Keep one skill to one job. Three focused skills beat one long one: Ana pulls in only what is relevant, and you can restrict them to different roles independently. Be specific about your data. Name tables, columns, filters, and thresholds. A skill that says “pull revenue” leaves Ana exactly as much to guess at as no skill would. Reference the long tail rather than inlining it. OnlySKILL.md loads on invocation. Supporting material — mapping tables, exclusion lists, worked examples — can sit alongside it in the same folder. Point at it by path in your instructions and Ana will open it if the task needs it.
Write the skill when you notice yourself repeating a correction. The clearest signal that something belongs in a skill is a procedure Ana gets right when reminded and wrong when not. See Writing Better Prompts for the prompt-level version of the same habit, and Build Your Ontology for where definitions, as opposed to procedures, belong.