# What agent skills are: one folder, one SKILL.md, open source > An agent skill is a folder holding a SKILL.md file: YAML frontmatter with a name and a description, then Markdown instructions, with optional scripts and reference files beside them. Kortix is the open-source AI Operating System, and a skill in a Kortix project lives at skills//SKILL.md. URL: https://agentskillsguide.dev/what-are-agent-skills ## The frontmatter of a skill in production `.agents/skills/kortix-brand/SKILL.md` ``` --- name: kortix-brand description: "Load FIRST for anything that carries the Kortix look or voice: product or mobile UI, copy of any kind, decks, social, images, email, CLI output, anything with the logo, and reviews of these. Routes you to the exact files. Triggers: choosing a spacing, color, radius, shadow, duration or word that a user or buyer will read." --- ``` Source: https://github.com/kortix-ai/suna/blob/dev/.agents/skills/kortix-brand/SKILL.md The `kortix-brand` skill in Kortix's own repository, whose description names the jobs it covers and the moment to load it. ## A skill is a folder with one Markdown file in it A skill is a directory containing, at minimum, a `SKILL.md` file, as the [Agent Skills specification](https://agentskills.io/specification) puts it. Nothing compiles and nothing registers. The folder sits in your repo beside the work it describes, and any text editor opens it. That flatness is the format's design. A person who can write a README can write a skill, and that is most of why the format spread. It also moves the difficulty somewhere the file itself does not show. What decides whether a skill works is when the agent opens it, what opens alongside it, and who is allowed to open it at all. A skill written as if its body sat in every prompt gets all three wrong. In a [Kortix](https://kortix.com/docs/project/agents) project a skill is `skills//SKILL.md`, and reference files can sit beside it. Kortix is the open-source AI Operating System, so a skill is a file in a git repo you own. Open source. Read it, fork it, audit it. Session work reaches `main` through a change request. Merge is default-deny for agents. ## Two required fields, and one of them decides loading `SKILL.md` holds YAML frontmatter followed by Markdown content; `name` and `description` are required. `name` is 1 to 64 characters of lowercase letters, digits and hyphens, and must match the folder name. Tooling finds a skill by its path. A name that disagrees with the directory is the first thing a validator rejects. `description` is 1 to 1024 characters, and should say both what the skill does and when to use it. Of the two fields, this is the one an agent reads before it decides anything. `description` is what the agent reads to decide when to load the skill; write when to use it, not only what it is. A description that says "helps with invoices" tells the agent almost nothing about the moment to reach for it. One that names the trigger ("Use for every new invoice, before any reminder is drafted") gives the agent something to match against a task. The descriptions in a repo work as its routing table. A vague one is a row nobody can find. ## The optional fields a reader will meet `license`, `compatibility` (1 to 500 characters), `metadata` (a string map) and `allowed-tools` (experimental) are optional. `compatibility` is for a skill with an environment requirement, such as a package it needs installed, and most skills leave it out. `metadata` holds string keys a client wants to keep. `allowed-tools` pre-approves a space-separated list of tools, and support for it varies between implementations, so treat it as a hint. The Markdown body has no format restrictions. The specification recommends step-by-step instructions, examples of inputs and outputs, and common edge cases. That is also the order a reader needs them in. ## Three load levels, each with a budget Metadata is about 100 tokens and loads for every skill at startup; the full `SKILL.md` body loads when the skill is activated, with under 5,000 tokens recommended; bundled files load only when read. That order is why a repo can carry 40 skills without paying for 40 instruction sets in every prompt. Startup costs roughly 100 tokens per skill, about 4,000 for the set. One body costs its own 5,000 only in the session that activates it. The description is the cheap, always-on half of a skill. The body is the expensive half, and it should earn its place. The specification recommends keeping the main `SKILL.md` under 500 lines and moving reference material into separate files. A skill that runs past 500 lines is usually two skills. The second half is a reference document that has not been split out yet. ## Scripts run, references wait, assets sit Scripts go in `scripts/`, reference documents in `references/`, and templates, images or data in `assets/`. The split is about load cost. A script in `scripts/` exists to be executed, so it can be as long as the job needs. A file in `references/` is read only when the agent asks for it, which leaves the third disclosure level in the agent's hands. Assets hold what a script or a template consumes. Keeping reference files focused is part of the same budget. An agent loads them on demand, so a smaller file means less context when it does. Relative paths from the skill root keep the references working after the folder moves into another repo. ## A complete skill, from frontmatter to edge cases This one is valid as written: paste it at `skills/ticket-triage/SKILL.md`, and the folder name, the `name` field and the description agree. ```markdown --- name: ticket-triage description: "Classify a new support ticket by product area and urgency, and route it to the right queue. Use at the start of every new ticket, before any reply is drafted." metadata: owner: support-ops version: "1.2" --- # Ticket triage ## Steps 1. Read the ticket subject and body, plus the customer's last three tickets. 2. Name the product area: billing, onboarding, data sync or access. 3. Name the urgency: `blocked` for an outage or a failed payment, `high` for a broken workflow, `normal` otherwise. 4. Write the area, the urgency and the queue into the ticket. ## Example Input: "Sync stopped at 09:10, nobody can see new rows." Output: `area: data sync`, `urgency: blocked`, `queue: sync-oncall`. ## Edge cases - Two product areas: pick the one that owns the failing step. - No clear area: set `area: unknown` and leave the queue alone. - A security report: set `urgency: high`, add the `security` label and stop. ``` Two details keep this skill cheap. The description names the moment ("at the start of every new ticket"), so routing has something to match. The body holds decision rules. A policy document that changes weekly belongs in `references/policy.md`, where it costs nothing until a step needs it. ## How an agent decides to load a skill A session starts with the metadata of every skill it may use, and nothing else. When a task arrives, the agent compares the task against the descriptions and loads the matching body with the `skill` tool. On the pi harness the system prompt lists each granted skill's name and description, and the agent reads the file once it decides. Kortix does not put skill bodies in every prompt. The comparison runs against the description in the language of the task. An agent asked to answer a support ticket matches `ticket-triage`. The same agent asked to resize a logo never loads it, and the 5,000 tokens stay unspent. Two skills that both claim "handles support" load unpredictably for the same reason. The agent cannot choose between them, so it picks one and the other may as well not exist. A skill that never loads is usually a description problem. Read the description as the sentence a colleague would use to decide whether to open the file. If it names a topic and never a moment, rewrite it. ## Where a session looks, and who may load As of October 2026, a session looks in the managed `kortix-*` skills first, then `skills/`, then `.kortix/opencode/skills/`, and pi also reads `harnesses/pi/skills/`. The first skill of a name wins. Kortix copies its managed `kortix-*` skills into every session; a project cannot override one of the same name ([the docs](https://kortix.com/docs/project/agents)). Finding the file is only half of access. Which skills an agent may load is a grant in `kortix.yaml`, set for each agent. A skill in `skills/` is usable only when that agent's grant allows it. ```yaml agents: support: file: agents/support.md skills: [kortix-cli, ticket-triage] ``` `kortix.yaml` declares the machine image, connectors and triggers, and secret names and grants. Secret values never appear in the repo. The grant sits in the same file, and the same change request, as the skill it names, so a reviewer reads the access change beside the instruction. ## Questions readers ask before writing one ### What are the skills for an agent? A skill is a folder with a `SKILL.md` file that an agent loads when a task calls for it. It carries the instructions, scripts and reference files for one job, so the agent gets that know-how without every other task paying for it. ### Can you give me some examples of agent skills? Kortix keeps its own skills as folders under `.agents/skills/` in the repository, each one a `SKILL.md`: `kortix-brand` for voice and visual work, `kortix-release`, `ponytail`, `composio`, `agent-browser`. A support team's skill might classify each new ticket by product area and urgency. ### Are agent skills actually useful? Yes, judged by adoption. [Anthropic reports](https://www.anthropic.com/news/donating-agent-skills-to-the-agentic-ai-foundation) 1 million skills published and nearly 280 million installs, and more than 70 platforms have integrated the format, including ChatGPT, Cursor, GitHub Copilot and VS Code (October 2026). ## Write the first skill in a repo you own. One Markdown file, one description, and a grant that names it. [Try Kortix](https://kortix.com) · [Read the docs](https://kortix.com/docs/project/agents) Run it on Kortix Cloud, in your VPC, or on your own on-prem network. Self-host is free. · Session work reaches main through a change request · Merge is default-deny for agents