> ## Documentation Index
> Fetch the complete documentation index at: https://docs.textql.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Skills

> Reusable instruction sets stored in your Ontology that Ana pulls into a chat on demand — invoked by name with a slash command, or selected by Ana when the task calls for one.

A skill is a procedure you write once and reuse. It lives in your [Ontology](/core/ontology/overview) as a folder containing a single `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](/core/ontology/build-your-ontology#dynamic-loading--how-ana-uses-your-ontology) 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

The `skills/` folder sits at the root of your Ontology and is flat — one folder per skill, no nesting:

```
skills/
  monthly-close/
    SKILL.md
  board-deck/
    SKILL.md
```

The folder name is the skill's **trigger**: `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.

```markdown SKILL.md theme={null}
---
name: Monthly Close Review
description: The month-end revenue close checklist — which numbers to pull, in what order, and the reconciliations to run before publishing. Use when preparing or reviewing a monthly close.
---

# Monthly close review

1. Pull recognized revenue from `fct_revenue` for the closing month, excluding
   the intercompany entities listed in `skills/monthly-close/entities.md`.
2. Reconcile against the billing system total. A gap over 0.5% is not roundable —
   find it before continuing.
3. ...
```

Everything below the frontmatter is the instruction body, and it is ordinary Markdown — the same content you would write in any other Ontology file.

| Field         | Required | What it does                                                                                                                                                                                                                                                                                              |
| ------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`        | No       | Display label in the skill picker.                                                                                                                                                                                                                                                                        |
| `description` | No       | What the skill is for, and when it should be used.                                                                                                                                                                                                                                                        |
| `listed`      | No       | `false` hides the skill from the `/` picker and drops its description from the list Ana reads. She still receives the trigger and can invoke it — normally because another skill's instructions sent her there. Use it for reference material, not to conceal a skill; that is what folder access is for. |

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.

<Note>
  Triggers cannot contain `/`, `\`, `:`, `<`, or `>`. A folder named with one of these is skipped rather than offered as a trigger that could never be invoked.
</Note>

## 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:

|                    | Description                                                                                                                                                                        |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Less effective** | "Monthly close process."                                                                                                                                                           |
| **More effective** | "The month-end revenue close checklist — which numbers to pull, in what order, and the reconciliations to run before publishing. Use when preparing or reviewing a monthly close." |

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 and `SKILL.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](/core/ontology/enrich-through-chat).

To write one by hand instead:

<Steps>
  <Step title="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`.
  </Step>

  <Step title="Add SKILL.md">
    Inside that folder, create a Markdown file named `SKILL.md`, write the frontmatter and instructions, and save.
  </Step>

  <Step title="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.
  </Step>
</Steps>

If your Ontology is [connected to a GitHub repository](/core/ontology/build-your-ontology#method-1-github-integration), you can commit `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](/core/ontology/ontology-rbac) 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`](/core/how-it-works/playbooks), [`.dashboard`](/core/how-it-works/dashboards), [`.tql`](/core/ontology/tql-reference), 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.** Only `SKILL.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](/core/get-better-results/writing-better-prompts) for the prompt-level version of the same habit, and [Build Your Ontology](/core/ontology/build-your-ontology) for where definitions, as opposed to procedures, belong.