category
A grouping label for listings, general when unset. It is what /skills groups by.
How-to
How to teach an AI agent a new skill
A skill on Olano is a folder with a markdown file in it - not a fine-tune, not a plugin you build, not a form in a settings screen. That is the whole fix for an agent that does the job, but not the way your team does it, and not the same way twice. This page shows what goes in the folder, the three routes by which one reaches an agent, how to keep a skill away from agents that cannot run it, and how to open the bundled chart skill, read it, and fork it.
What a skill actually is
Hold on to one fact and the rest of this page follows from it: a skill is a folder. Inside it is a file called SKILL.md, which opens with a short header - a name that matches the folder, and a one-line description of what the skill is for - and continues with the procedure itself in plain language: the steps, the output format, the checks to run before handing over. Beside that file can sit scripts, reference documents, templates and example inputs.
That is the whole format. Nothing is compiled and nothing is trained. The agent's prompt carries the name and description of every skill it holds; when a task matches, it opens the file and follows it. Type / in the dashboard chat and the agent's skills appear in the menu beside the slash commands; /skills lists everything the agent actually has, grouped by category.
A skill is not memory. Memory holds what is true about your business and is read at the start of every turn; a skill holds how a piece of work gets done and is read when that work comes up. How AI agents remember covers the memory side, and the docs chapter on memory and knowledge has the rule of thumb: a fact goes in memory, a document goes in the knowledge base, anything with steps goes in a skill.
Why a folder and not a fine-tune
A fine-tuned model learns your procedure as a tendency, and you find out how well by running it. A folder is a document: you can read it before the agent ever uses it, correct a step by editing a line, see the change in the revision history, and hand it to a different model without losing it. The price is that the agent has to be told the skill exists, which is what the header and the tools rule below are for. Agent memory vs fine-tuning makes the longer argument.
Anatomy of a skill folder
One required file and three optional directories, all readable in the dashboard.
| Entry | What it holds | Notes |
|---|---|---|
SKILL.md | Required. A YAML header - name equal to the folder name, and a description saying what the skill does and when to reach for it - then the procedure in markdown. | Written to be read in full. The Skills tab renders it as a document, with the bundled files listed beside it. |
scripts/ | Programs the instructions tell the agent to run: a renderer, a validator, a fetcher. | The bundled chart skill keeps its renderer here. A skill with no scripts is still a skill. |
references/ | Longer material the steps point at - a style guide, a cookbook, a list of anti-patterns - read when the procedure calls for it, not every turn. | What keeps SKILL.md short. |
assets/ | Templates, themes, example inputs, fonts, a vendored library. | The chart skill ships its charting library, three themes and twelve example recipes here. |
Four optional header lines
These keys change how the platform treats the skill.
trigger
One line on when to reach for the skill. The description says what it is for; the trigger says which moment calls for it.
tier
light, the default, is described in the agent's own prompt and followed inline. subagent runs on demand through delegation, as a bounded task with its own step and time budget; two further lines set that budget per skill.
requires_tools
The tools the procedure assumes. The skill is shown to an agent only when every listed tool is in that agent's effective tool set. It never grants a tool; it hides the procedure from agents that could not follow it. Written at the top level, or under a metadata key in a skill that keeps to the published Agent Skills format; both are read.
Do the job once in chatAsk the agent to write it up as a skillIt writes the folder into its own skills directoryOpen it on the Skills tab and read itEdit any step in FilesRestart - the agent follows it whenever the task matches
Teaching a skill from a conversation
The most reliable way to write a skill is not to write it. Do the job with the agent once - the Monday report, the refund check, the supplier summary - correcting it until the output is what your team would have produced. Then ask it to turn what it just did into a skill. Any agent can author one - a skill-creator skill from the Olano skills catalog walks it through the folder - and it writes the result into its own skills directory, picked up on the agent's next restart.
What you get is a folder labelled Agent skill on that agent's Skills tab. Open it and read it: where the agent has generalised wrongly or missed the step you only do at month-end, you fix the sentence. Open in Files takes you to the folder; the edit is a text edit.
The other two routes produce the same folder by a different hand: write it yourself in the Files tab - a new folder under the agent's skills directory, a SKILL.md with the two-line header, the steps beneath - or have the deployment's administrative agent write it, or install a finished folder for every agent at once.
One rule for hand-written files: the name in the header must equal the folder's name. A mismatch still loads, with a warning on every start, and the fix is to rename the folder - not the header, because the name is what the agent refers to.
Three ways a skill reaches an agent
The folder is the same in every case. What differs is who wrote it and how many agents see it.
Bundled with the platform
The skills every deployment starts with - documents, spreadsheets, slides, charts, browser use, the platform's own procedures. They load for every agent on the box and show as Common skill.
Synced from the Olano skills catalog
The shared pack, refreshed from the catalog rather than copied once and left to age. A refresh replaces a skill wholesale, which is why an agent's own improvements are kept as forks rather than edits.
Authored in the workspace
Written by you in Files, by the agent when you ask it to, or by Cortex out of work the agent has repeated. These live in the agent's own skills directory, show as Agent skill or Learned skill, and belong to that agent alone.
Declaring the tools a skill needs
A skill that says "render the page to PNG" is a trap for an agent with no render tool: it reads the instruction, plans around it, and fails at the step it cannot take. So the header can declare what the procedure assumes:
requires_tools: [render_html_image]
With that line, the skill is advertised only to agents whose effective tool set contains every tool listed. For any other agent it is not in the prompt, cannot be delegated to, and is listed on the Skills tab as gated, with the missing tool names and no on/off switch. Asked to list its skills, an agent reports the same thing about itself.
The line grants nothing. Granting a tool is done on the agent's Tools tab, or through a connector or an MCP server, and the moment the tool is there the skill appears. A skill is instructions, a tool is access, and a file in a folder should never be the thing that hands an agent access to email.
Worked example: read the chart skill, then fork it
The clearest real skill to open is the chart skill, because the chart engine is the skill: there is no chart feature in the runtime, there is a folder.
Open it from any agent's Skills tab. The header declares requires_tools: [render_html_image] under its metadata key - the tool that turns HTML into a PNG on a browser bundled with the deployment - so it appears only for agents that can render. The body is the procedure in six steps: show the numbers as a table first, so the chart has something it must match; propose a chart form and wait for a go-ahead; write the takeaway title before the spec; render; check the image once against a fixed five-point list; hand the file over. scripts/ holds the renderer, a script that needs nothing beyond the standard Python library and turns a small recipe file into a themed page. assets/ holds the charting library, three colour themes and one example recipe for each of the twelve chart types. references/ holds what the steps point at: how to choose a form, the colour rules, the anti-patterns, every recipe field with an example.
Now change it. Every recipe is a short, flat file written to be copied, and the skill's own instructions say how: copy the bar recipe, edit the one function that returns the chart specification, and render with the copy. The themes are plain files too, and a fourth theme named brand reads its colours from a token file in the working directory when one exists - the intended way to put your palette on every chart.
Where you make the change decides who it reaches. The shared copy is read-only from any single agent's page on purpose, because editing it there would quietly change what every agent draws. Change it in the shared skills folder and every agent on the deployment draws differently. Copy the folder into one agent's own skills directory under the same name, edit that, and only that agent changes - an agent's own skill of the same name takes precedence over the shared one.
When a skill is not the answer
Some things people reach for a skill to fix are a different kind of thing.
You need access, not instructions
If the procedure needs a calendar, a CRM or a database the agent cannot reach, no skill helps. Grant the tool or connect an MCP server, then write the skill that uses it and declare it in the header.
It is a fact, not a procedure
"Our office hours are nine to six" belongs in memory, where the agent reads it every turn. A skill is opened only when its task comes up.
It is a document
The 40-page policy goes in the knowledge base, retrieved when someone asks. Pasting it into a skill makes the skill unreadable and the answer no better.
It should happen on a clock
A skill says how, not when. Work that must run every Monday is a schedule or a standing instruction, and the scheduled task's wording can name the skill to follow.
It needs to run apart from the conversation
A long, bounded job with its own budget is a subagent-tier skill or a subagent of its own, delegated to and awaited rather than followed inline.
How Cortex proposes one
You will not write every skill. Olano Cortex, the improvement engine that runs per agent on a schedule, has a Learned Skills phase that reads the work the agent has actually done and drafts a skill when it finds a procedure repeated across conversations. It reads the library the agent already holds first, and drafts nothing when the procedure is already covered.
Fully Autonomous is on by default, and under it a learned skill is kept without a click - logged, labelled Learned skill on the Skills tab, readable and editable like any other. Switch it off, for one agent or the whole deployment, and the same drafts wait in a queue for you to approve or reject. Rewriting the agent's own instructions is different: that waits for a human in either mode, unless a deployment owner has explicitly lifted the hold for that agent.
When Cortex improves a skill the agent did not write, it forks the folder into the agent's learned library rather than editing the original, and a separate Skill Library phase merges duplicates, snapshotted with a one-click undo. The mechanics - the fork, the check that quarantines a degraded copy, the merge when the original changes - are the subject of how an AI agent learns a new skill, the conceptual half of this page.
Checking what an agent actually has
The Skills tab on an agent's detail page lists every skill that agent can reach. Each row says where it lives - Common, Agent, Learned, or Configured for an extra directory named in the agent's settings - whether it is editable from here, and carries an on/off switch. Off means the skill is not described in the agent's prompt, cannot be delegated to and is ignored by self-learning; it is not deleted, and turning a common skill off takes it away from this agent only. Everything is on by default.
An agent can work its own switches from a conversation - "stop using the spreadsheet skill" - if that self-configuration capability is on for it; it can never install, edit or delete a skill that way. Skills are audited before an agent runs them, and one held back by the audit is listed with the reason rather than vanishing.
Nothing on this page trains a model. A skill is a document in your own deployment - written by you, by your agent, or by Cortex - and read, corrected and undone the same way in all three cases.
FAQ
What is a SKILL.md file?
It is the one required file in an agent skill folder. It opens with a short YAML header - a name that must equal the folder's name and a one-line description of what the skill is for - and continues with the procedure in plain markdown: the steps, the output format, the checks. Optional header lines add a category, a trigger, a tier and the tools the procedure requires. Scripts, reference documents and assets sit beside it in the same folder.
How do I add a custom skill to an AI agent?
Create a folder in the agent's skills directory, put a SKILL.md in it with the header and the steps, and restart the agent. On Olano you can do that in the dashboard's Files tab, or ask the agent in chat to write the procedure up as a skill after you have done the job together once. It then appears on the agent's Skills tab as an Agent skill, where you can read and edit it.
Can I teach my AI agent a company procedure?
Yes, and a procedure is exactly what a skill is for. Do the job with the agent once, correcting it until the result is what your team would produce, then ask it to save the procedure as a skill. Read the file it writes, fix any step it generalised wrongly, and from the next restart the agent follows it whenever that task comes up. Facts about the business belong in memory instead; documents belong in the knowledge base.
How do I change how my agent formats charts?
The chart engine on Olano is itself a skill folder: a small renderer script, a bundled charting library, three colour themes and one example recipe per chart type. Open it from any agent's Skills tab and read it. To change one chart type, copy its recipe file and edit the function that returns the chart specification. To put your palette on every chart, add a brand token file that the brand theme reads. Edit the shared copy and every agent changes; copy the folder into one agent's own skills directory under the same name and only that agent does.
Does adding a skill retrain the model?
No. Nothing is trained or fine-tuned. A skill is a folder of plain-text files inside your own deployment; the agent's prompt carries its name and description, and the agent opens the file when a task matches. That is why you can read a skill before it is ever used, correct a step by editing a line, see the change in revision history, and switch models without losing it.
What happens if the agent does not have the tools a skill needs?
If the skill's header declares the tools it requires, an agent missing any of them never sees the procedure: it is not in the prompt, cannot be delegated to, and shows on the Skills tab as gated with the missing tool names. Granting the tool - on the agent's Tools tab, or by connecting an MCP server - is what makes the skill appear. The declaration never grants access on its own.
Related reading
Where to go next.
How an AI agent learns a new skill
The conceptual half: how Cortex drafts, forks and merges skills without overwriting an original.
Are agent skills portable?
What travels with a folder of markdown and scripts, and what stays behind.
Docs: memory and knowledge
Memory, the knowledge base and skills - and which one a given thing belongs in.
Docs: agents
The Skills tab and the rest of an agent's settings, in reference form.
Bring the procedure your team explains most often.
Tell us the job that gets done slightly differently every time. We will say whether it is a skill, a tool the agent is missing, or a schedule - and show you the folder before anything else.