Glossary

Skill file

The capability an agent has, written down where a person can read and edit it.

Definition

A skill file is a plain-text document, conventionally named SKILL.md, that teaches an AI agent one capability: when the skill applies, the procedure to follow, the constraints to respect, and any reference material or scripts it needs. Skill files are loaded into the agent's context when relevant, which keeps capabilities modular, version-controlled and readable by the people who rely on them.

Conventional filename: SKILL.md
Format: Markdown, often with frontmatter
Loaded: When the task matches

Where the convention came from

The pattern was popularised by Anthropic's Agent Skills, which package a capability as a folder containing a SKILL.md file with YAML frontmatter giving a name and a description of when to use it, plus whatever reference documents and scripts the procedure needs. An agent reads the descriptions, and pulls the full file into context only for tasks where the skill applies.

The design solves a context problem. Everything an agent might ever need to know cannot fit in one prompt, and stuffing it in degrades performance on every other task. Splitting capabilities into files that load conditionally keeps the always-on instructions short.

What a good skill file contains

A trigger description
When this skill applies and, just as important, when it does not. This is the line the agent reads to decide whether to load the rest.
The procedure
Steps in order, written as instructions to a competent colleague rather than as a description of the domain.
Constraints and prohibitions
What must never happen. Negative constraints do more work than positive ones, because they are the part a model will otherwise reason its way around.
Reference material
Tables, examples, checklists, or scripts the procedure calls. Kept in the same folder so the skill travels as a unit.

Commonly confused with

Term	What it is	The difference
System prompt	Always-on instructions defining identity and behaviour	Loaded on every call. A skill file loads only when the task matches.
Tool definition	A machine-readable schema describing a function the agent can call	Tells the agent what it can do. A skill file tells it how and when to do it.
RAG document	Content retrieved from a knowledge base to answer a question	Supplies facts. A skill file supplies procedure.
Fine-tuning	Changing model weights on training examples	Bakes behaviour into the model. A skill file is editable in a text editor at any time.

How Polaris uses skill files

When you hire an AI worker in Polaris, the interview at the end of hiring writes the worker's capabilities to a real SKILL.md file rather than a hidden system prompt. You can open it, read exactly what your worker was told, and edit it. When a task is assigned, the runtime compiles the worker's identity from its instructions, its skill files and the task context before starting the tool loop.

The reason for exposing the file is auditability. A worker that behaves oddly has a text file behind it that a person can read and correct, which is not true of an agent whose behaviour lives in a prompt you never see.

AI worker

The difference between an agent you prompt and an agent you assign work to.

Agent runtime

Not the model, not the framework: the thing that actually runs the job.

Model Context Protocol (MCP)

One protocol between models and the systems they need, instead of one integration per pair.

Skill files, and why a worker's capability should be readable

The difference between a prompt and a playbook is that one of them is a document your colleague can edit.

Acceptance criteria

Written before the work, checkable after it, and binary either way.

AI workers you can hire, brief and assign

Every role below is a teammate you hire in chat, brief with an editable skill file, and assign work to on the same board as your people.

Questions people ask

+How is a skill file different from a prompt?

A prompt is what you send for one request. A skill file is a durable document that any task matching its trigger will load, version-controlled and editable independently of any single request. The practical difference is that a prompt improves one answer and a skill file improves every future task of that kind.

+Can a non-technical person write a skill file?

Yes. It is Markdown, and the hardest part is procedural clarity rather than syntax. The most common failure is writing a description of a topic instead of instructions for performing a task, which produces an agent that knows about the work rather than one that does it.

+How many skill files should one agent have?

As many as it has distinct capabilities, since they load conditionally and unused ones cost nothing. The design pressure is towards one file per capability with a sharp trigger description, rather than one large file covering an entire role.