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

# Skills

> Versioned packages of instructions and files that agents load on demand

A skill packages reusable instructions and optional files for agents. You upload it once, attach its ID to agent configs, and the model calls the built-in [`skill` tool](/tools/built-in#skill) when it needs the instructions.

Skills are:

* **Lazy** — only the name and description enter the model's context until it loads the skill.
* **Versioned** — uploading the same skill again creates a new revision under the same skill ID.
* **Shared** — one skill can be granted to multiple projects and attached to many agents.

## Upload a skill

Upload a `.zip` or `.tar.gz` archive with one top-level directory:

```text theme={null}
release-notes/
├── SKILL.md
└── templates/
    └── example.md
```

`SKILL.md` starts with the skill's name and description:

```md theme={null}
---
name: release-notes
description: Use when writing release notes for Acme.
---

Follow the Acme release-note format in templates/example.md.
```

Write the description as a trigger—“Use when…”—because it helps the model decide when to load the skill.

| Rule | Limit |
| - | - |
| `name` | Required. Lowercase letters and digits in hyphen-separated segments (`release-notes`), up to 64 characters. Must match the archive's top-level directory. |
| `description` | Required, up to 1,024 characters. |
| `SKILL.md` | Must sit directly inside the top-level directory, up to 256 KB. |
| Archive | Up to 25 MB and 1,000 entries. Symlinks are rejected; macOS metadata (`__MACOSX/`, `.DS_Store`, `._*`) is ignored. |

**API**

The examples assume the client, `$ORG`/`orgID`, and `$PROJ`/`projectID` setup from the [quickstart](/quickstart).

`POST /skills` takes multipart form data: an `owner` and the `archive` itself. When calling the API directly, send `owner` as a JSON part (`Content-Type: application/json`); the SDK and CLI do this for you. The CLI's `--archive` takes a `.zip` or `.tar.gz` file, or a skill directory that it packs for you:

```bash CLI theme={null}
omnara skills create --owner-kind org --archive release-notes/ --json
```

```bash REST theme={null}
curl "$OMNARA_API/orgs/$ORG/skills" \
  -H "Authorization: Bearer $OMNARA_TOKEN" \
  -F 'owner={"kind": "org"};type=application/json' \
  -F "archive=@release-notes-skill.zip"
```

```typescript SDK theme={null}
import { readFile } from 'node:fs/promises'

const bytes = await readFile('release-notes-skill.zip')

const skill = await sdk.createSkill({
  client,
  path: { orgID },
  body: {
    owner: { kind: 'org' },
    archive: new File([bytes], 'release-notes-skill.zip'),
  },
})
```

```json theme={null}
{
  "id": "skl_ik7mv4qtrwz3jehcyd5n6a2bfg",
  "org_id": "org_k7mv4qtrwz3jehcyd5n6a2bfgi",
  "owner": { "kind": "org" },
  "name": "release-notes",
  "revision_id": "skr_d5n6a2bfgik7mv4qtrwz3jehcy",
  "revision": 1,
  "description": "Use when writing release notes for Acme.",
  "skill_md": "---\nname: release-notes\ndescription: Use when writing release notes for Acme.\n---\n\nFollow the Acme release-note format in templates/example.md.",
  "created_at": "2026-08-03T20:31:04Z",
  "updated_at": "2026-08-03T20:31:04Z"
}
```

For a project- or user-owned skill, set the owner accordingly: `--owner-kind project --owner-project-id proj_…` or `--owner-kind user` with the CLI, or `{"kind": "project", "project_id": "proj_…"}` / `{"kind": "user"}` as the `owner`.

**Dashboard**

1. With **All projects** selected in the project switcher, open **Skills** and pick the **User** or **Organization** tab, or open **Skills** inside a project and stay on its **Project** tab. The page determines who owns the skill.
2. Click **Create skill**.
3. Drop files or a folder onto the dialog, or use **Choose files** / **Choose a folder**. You can also switch to the **SKILL.md** tab and write the skill in the editor.

The dashboard accepts a `.zip`, a `.tar.gz`, a loose `SKILL.md`, or a folder, and zips folders in the browser before uploading. A folder or archive holds one skill when `SKILL.md` sits at its top, or several skills when each subfolder has its own `SKILL.md`; deeper `SKILL.md` files are not picked up. Folders skip `node_modules` and dot-directories such as `.git`; archives upload every file. The dashboard names each skill's top-level directory after its frontmatter `name`, so the folder name does not have to match.

Frontmatter problems are flagged before anything uploads. When you upload several skills, reuse an existing name, or include two skills with the same name, a review step lists each skill as new, a new revision (for example `v2 → v3`), or skipped, and uploads only after you confirm. Skills upload one at a time; if some fail, **Retry** re-sends only those.

The owner (`org`, `project`, or `user`) decides who manages the skill and cannot change. A project can attach only skills it owns or has been granted—even skills owned by its organization.

Uploading again with the same owner and name creates the next revision: the `skl_` ID stays the same and the `skr_` revision ID changes. Attached agents resolve the latest revision at each model call, so they do not need to be relaunched.

## Update a skill

Each update creates the next revision; the skill's name cannot change.

**API**

`POST /skills/{skillID}` takes multipart form data with exactly one of:

* `skill_md` — replacement `SKILL.md` text. Every other file in the current revision is kept.
* `archive` — a new `.zip` or `.tar.gz` that replaces all of the skill's files.

```bash theme={null}
curl "$OMNARA_API/orgs/$ORG/skills/skl_ik7mv4qtrwz3jehcyd5n6a2bfg" \
  -H "Authorization: Bearer $OMNARA_TOKEN" \
  -F "skill_md=<release-notes/SKILL.md"
```

The CLI has no update command. Running `omnara skills create` again with the same owner and skill name uploads the next revision.

**Dashboard**

Click the skill's name to open its page. Edit `SKILL.md` in place and click **Save**; the other files are kept. Frontmatter errors are marked in the editor, and **Save** stays disabled until they are fixed. To replace every file, click **Upload new version** and choose a new archive; the `SKILL.md` name must stay the same.

## List, inspect, delete

Each skills page lists the skills owned at that scope; `omnara skills list` does the same from the terminal. Fetching a skill (`omnara skills get {skill-id}` or the API) returns `skill_md`, the full instruction text of its current revision. To delete an owned skill in the dashboard, open its row menu and click **Delete**, or run `omnara skills delete {skill-id}`. Deletion removes its revisions and grants, but is blocked with `409` while an active agent config references it.

## Grant it to projects

A project can use a skill only if it owns it or holds a grant — org- and user-owned skills must be granted to each project that references them. Grants share without transferring ownership.

**API**

The response identifies the grant and target project:

```bash CLI theme={null}
omnara grant skills add skl_ik7mv4qtrwz3jehcyd5n6a2bfg \
  --target-project-id proj_4qtrwz3jehcyd5n6a2bfgik7mv \
  --json
```

```bash REST theme={null}
curl "$OMNARA_API/orgs/$ORG/skills/skl_ik7mv4qtrwz3jehcyd5n6a2bfg/grants" \
  -H "Authorization: Bearer $OMNARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"target_project_id": "proj_4qtrwz3jehcyd5n6a2bfgik7mv"}'
```

```typescript SDK theme={null}
await sdk.createSkillGrant({
  client,
  path: { orgID, skillID: 'skl_ik7mv4qtrwz3jehcyd5n6a2bfg' },
  body: { target_project_id: 'proj_4qtrwz3jehcyd5n6a2bfgik7mv' },
})
```

```json theme={null}
{
  "id": "skg_jehcyd5n6a2bfgik7mv4qtrwz3",
  "org_id": "org_k7mv4qtrwz3jehcyd5n6a2bfgi",
  "skill_id": "skl_ik7mv4qtrwz3jehcyd5n6a2bfg",
  "target_project_id": "proj_4qtrwz3jehcyd5n6a2bfgik7mv",
  "created_at": "2026-08-03T20:34:52Z"
}
```

List a skill's project grants with `omnara grant skills list {skill-id}` or `GET …/grants`; revoke one with `omnara grant skills delete {skill-id} {grant-id}` or `DELETE …/grants/{grantID}`.

To confirm which skills a project can use (the CLI has no equivalent command):

```bash REST theme={null}
curl "$OMNARA_API/orgs/$ORG/projects/$PROJ/skills" -H "Authorization: Bearer $OMNARA_TOKEN"
```

```typescript SDK theme={null}
const available = await sdk.listProjectAvailableSkills({
  client,
  path: { orgID, projectID },
})
```

Each result reports whether the project owns the skill (`direct`) or receives it through a `grant`.

**Dashboard**

On the skill's row, click **Share with project** and pick the target. Shared skills appear on the project's **Skills** page, **Shared** tab — **Stop sharing skill** revokes one. Anyone who can view the project can open a shared skill to read it; only its owner can edit it.

## Attach it to an agent

Reference the skill ID in the config; config creation verifies the project can use it:

```yaml theme={null}
skills:
  - skl_ik7mv4qtrwz3jehcyd5n6a2bfg
```

In the dashboard's agent builder, click **+** in the **Skills** section and search for a skill to attach it. The search list includes **Create skill**, first when nothing matches the search and after the matching skills otherwise. It opens the same upload dialog, creates the skills in the project, and attaches them. A created skill replaces an attached skill with the same name.

Attaching a skill automatically enables the built-in `skill` tool. The model sees each skill's name and description; when it calls the tool, Omnara returns the `SKILL.md` instructions and attempts to install the supporting files on each attached machine. The instructions still work when no machine is attached or an installation fails.

For a complete example you can deploy, which uploads Remotion's skill folder and attaches it to a video agent, see the [video generation agent](/examples/video-generation-agent).

> [!NOTE]
>
> Full schema and playground: [Create skill](/api-reference/endpoints/skills/create-skill) · [Update skill](/api-reference/endpoints/skills/update-skill-by-uploading-a-new-revision) · [List skills](/api-reference/endpoints/skills/list-skills-visible-through-ownership-authority) · [Skill grants](/api-reference/endpoints/skills/create-skill-grant) · [Project skills](/api-reference/endpoints/skills/list-skills-available-to-project).


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