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

# What a skill is

> A skill is the second kind of prompt: a folder of files delivered to a developer's machine, versioned through the same engine that serves chat prompts.

A **skill** is the second kind of prompt. A chat prompt is handed to your application as messages; a skill is handed to a developer's machine as **files**, and the coding agent running there turns one into a message when it decides the skill is relevant.

Same storage, same versioning, same `latest` label — different delivery.

## A skill is a folder, not a document

Every skill has an **entry document**, `SKILL.md`, and may have any number of reference files beside it:

```text theme={null}
incident-triage/
├── SKILL.md              the front door — what this skill is, and what to do
├── references/
│   ├── paging.md         the paging runbook
│   └── severity.md       how severity is decided
└── checklists/
    └── postmortem.md
```

Everything a skill needs travels with it, so a developer never receives a procedure that refers to a file they do not have. A markdown link between two of a skill's files keeps working after either file is renamed — the link is stored as a reference to the *file*, not to its name, and comes back pointing at whatever that file is called now.

Files are UTF‑8 text with `\n` line endings and no byte-order mark. A skill holds at most **128 files**, **512 KB** in any one file, and **4 MB** across all of them.

## It is a prompt, so this all works already

A skill reuses the prompt engine rather than sitting beside it. Everything the [prompt documentation](https://to11.ai/docs/platform/prompts/overview.md) describes for versions, the `latest` label and history is true for a skill, unchanged:

* **[Versions](https://to11.ai/docs/platform/prompts/versions.md#versioning-and-publishing)** — each stored version is an immutable snapshot of the whole file set.
* **[The `latest` label](https://to11.ai/docs/platform/prompts/versions#the-latest-label)** — a skill has one label, `latest`, and storing a version moves it to the newest one. A machine that follows `latest` receives that version on its next sync; a machine pinned to a version keeps it.
* **[History and comparison](https://to11.ai/docs/platform/prompts/versions.md)** — version history and diffs work the same way. A renamed file reads as a rename, not as a file deleted and a different one added.

## What a skill does not have

A skill is delivered to disk and read by an agent. It is not an inference request, so it owns none of the fields that describe one — and a version that carries any of them is rejected rather than quietly ignored:

| Absent | Why |
| - | - |
| **Variables** | Nothing substitutes into a skill. `{{ … }}` is ordinary text: it is published and delivered to the agent exactly as written. |
| **Model config** | No model, temperature or token limit: a skill does not make a request, so there is nothing to configure. |
| **Tool definitions and tool choice** | Request-level concerns. Which tools an agent may use is the developer's setting, on their own machine. |
| **Block roles** | A skill's blocks are files, not conversation turns. |
| **Block conditions** | A skill delivers its whole file set. |

A skill's **description is required**, where a chat prompt's is optional. An agent decides whether a skill is relevant by reading it, so a skill without one is undiscoverable.

## The kind is permanent

A prompt's kind is chosen when it is created and never changes. A skill never becomes a chat prompt, and no chat prompt becomes a skill.

There is no converter, and there will not be one: the conversion is lossless in neither direction — chat to skill discards roles, conditions, tools and variables, and skill to chat discards filenames and references. A lossy conversion presented as a conversion produces silent data loss on published content. Choosing wrong means starting over.

One consequence worth knowing before you name a skill: a **slug identifies one prompt in a project whatever its kind**, so a project holding a `code-review` chat prompt cannot also hold a `code-review` skill. A skill's slug can be changed afterward; a chat prompt's cannot.

## Authoring, and where

In this release skills are **authored through the [to11 CLI](https://to11.ai/docs/reference/cli.md)** and **read in the browser**. Writing one and storing it is [Publishing skills](https://to11.ai/docs/skills/publishing-skills.md); receiving them on your own machine is [one `to11`](https://to11.ai/docs/skills/receiving-skills). The dashboard lists skills, shows each file's content and compares versions; it does not create or edit them — see [Reading a skill in the dashboard](#reading-a-skill-in-the-dashboard).

That is deliberate rather than unfinished: a skill is a folder on a developer's machine, and the tool that already has the folder is the one that should send it. Importing brings an existing skill onto the platform as it stands, without restructuring or rewriting it first.

## Reading a skill in the dashboard

Open a project and select **Skills**. The list shows only skills, with a band
of summary cards (skill counts), and controls to search, include archived
skills, and sort.

Opening one shows its **files** where a chat prompt shows its editor:

* **The file list** is flat and shows each filename as stored, path included —
  `references/paging.md`, not a folder to expand. A skill's filenames *are*
  relative paths, so a tree would invent a structure the skill does not have.
  The entry document is first and marked `entry`.
* **The file content** is what a machine receives, unchanged: nothing is
  reflowed, re-indented or rewritten. `{{ … }}` is shown as plain text, not
  highlighted as a variable — a skill has no variables, so nothing substitutes
  into it. A link to another of the skill's files opens that file.
* **The publication state** reads `stored; followers of latest receive it`.
  Storing a version is what moves the skill's one label,
  [`latest`](https://to11.ai/docs/platform/prompts/versions#storing-a-skill), so a version you have
  just stored is the one every machine that follows `latest` receives on its
  next sync.

**Comparing two versions** works as it does for a chat prompt, with filenames
as the rows. A file renamed between versions reads as one **renamed** row
carrying both names — and its content diff too, if the content changed in the
same version. A rename is not shown as a deletion beside an addition, because
that is the same picture a genuine deletion produces.

### Why there is no edit button

**The browser reads skills; the to11 CLI writes them.** Creating a skill,
changing a file, adding or removing one, renaming one and importing a folder
all happen through the CLI. There is no editor for a skill, and no route,
button or link reaches one — a half-working authoring surface is worse than
none, so the absence is deliberate rather than unfinished.

What you *can* do in the browser: read every file, compare versions, see which
version `latest` points at, and archive the skill.

**New skill** on the Skills page opens a panel rather than an upload control,
because an upload control would imply the browser can create a skill. It hands
you the two things that happen outside the browser: `to11`, which
signs you in and links a project, and a prompt to give your coding agent — writing a
skill is writing a folder of documents, which is what a coding agent is for.

The agent is a convenience, not the mechanism; the folder can equally be one
you wrote yourself. [Publishing skills](https://to11.ai/docs/skills/publishing-skills.md) is the
procedure for both.

## What a machine receives

The platform renders a skill into the files a machine writes, rather than serving raw content for a client to assemble. So a format fix ships once and reaches every machine on its next sync, and supporting another coding agent is work on the platform rather than a client release.

Every target receives the standards-only form today — the entry document's frontmatter carries a `name` and a `description`, and the files are as they were stored. That is the form every consumer accepts, so one render serves every agent.

## The endpoints behind it

These are endpoints on the to11 API, `https://api.to11.ai`. The to11 CLI calls them for you; they are listed because an API-first product's paths are part of its surface.

| Method | Path | Permission | What it does |
| - | - | - | - |
| `POST` | `/v1/projects/:projectId/prompts` | `prompt:create` | Creates a definition. Send `kind: "skill"` and a description; omitting `kind` creates a chat prompt, as it always did. Creates **no** version. |
| `GET` | `/v1/projects/:projectId/prompts` | `prompt:read` | Lists prompts. **Skills are excluded unless you ask** — pass `?kind=skill` or `?kind=chat,skill`. Each row carries its `kind`. |
| `GET` | `/v1/projects/:projectId/prompts/summary` | `prompt:read` | Counts for the directory's summary band — total, published, archived. Takes the same `?kind=` the listing does, and **excludes skills unless you ask**, so pass whichever kinds you listed and the counts describe the rows you got. |
| `PATCH` | `/v1/projects/:projectId/prompts/:promptId` | `prompt:update` | A skill's `slug` may be changed here; a chat prompt's may not. A skill's description cannot be emptied. |
| `POST` | `/v1/projects/:projectId/prompts/:promptId/imports` | `prompt:create` | Takes a folder — `{ slug, files: [{ filename, content }] }` — parses its frontmatter and links, and stores a version. Refuses a chat prompt. |
| `POST` | `/v1/projects/:projectId/prompts/:promptId/versions` | `prompt:create` | Stores a version whose `templateJson` is already structured as `{ files: [...] }`. |
| `GET` | `/v1/projects/:projectId/prompts/:promptId/versions` | `prompt:read` | Lists a skill's versions, newest first, as summaries — `id`, `version`, `format`, `changelog`, who created it and when — with no file content. Paged by an opaque cursor: `limit` is 50 by default and at most 100, and the answer's `pagination.nextCursor` goes back as `cursor` for the next, older page; it is `null` on the last. The CLI walks it to match a folder against stored versions. |
| `GET` | `/v1/projects/:projectId/prompts/:promptId/versions/:versionNumber` | `prompt:read` | Returns one version with its content: the summary fields plus `templateJson` as `{ files: [...] }`. |
| `POST` | `/v1/projects/:projectId/prompts/by-slug/:slug/labels/:label/render` | `prompt:read` | Returns the file set `latest` points at: the newest stored version's. `latest` is the only label; any other answers `404` with the code `LABEL_NOT_FOUND`. See [Rendering a skill](https://to11.ai/docs/platform/prompts/rendering.md#rendering-a-skill). |
| `POST` | `/v1/projects/:projectId/prompts/by-slug/:slug/versions/:versionNumber/render` | `prompt:read` | Returns the file set for one **named version** — what a machine pinned to that version receives. Skills only; the answer carries no `label`, because none is in play. |
| `GET` | `/v1/projects/by-name/:organization/:workspace/:project` | `project:read` | Resolves three names to a project id, so a configuration file can name `acme` and `sre/runbooks` instead of carrying an opaque id nobody can check by eye. |

**No new permission exists for skills.** Every endpoint uses a scope that already existed — see [Roles & permissions](https://to11.ai/docs/platform/roles-and-permissions.md).

**The whole folder is the truth on import.** A file present in the previous version and absent from an import is gone from the new one; that is the only way to remove a reference file. Frontmatter keys the platform does not recognize are dropped rather than rejected, whatever their value, so a skill written for one agent imports without being rewritten first. The frontmatter itself must be valid YAML: an import whose `SKILL.md` frontmatter does not parse is refused, naming the line and column. A `description` that is not a string is stored as written — `[a, b]` becomes the description `[a, b]`. Every problem in a rejected import is reported at once, not one round trip at a time.

## Next steps

> [card] [Versions](https://to11.ai/docs/platform/prompts/versions.md)
>
> Storing a version moves `latest` — the same act for both kinds of prompt.

> [card] [Rendering prompts](https://to11.ai/docs/platform/prompts/rendering.md)
>
> What a render returns for each kind, and what a render target selects.

> [card] [Roles & permissions](https://to11.ai/docs/platform/roles-and-permissions.md)
>
> Which permission each skill operation carries.

> [card] [CLI commands](https://to11.ai/docs/reference/cli/commands.md)
>
> The commands that store, import, and sync a skill.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.