Skills

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 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:

release-notes/
├── SKILL.md
└── templates/
    └── example.md

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

---
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
Dashboard

The examples assume the client, $ORG/orgID, and $PROJ/projectID setup from the 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:

omnara skills create --owner-kind org --archive release-notes/ --json

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

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'),
  },
})

{
  "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.

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.
Click Create skill.
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
Dashboard

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.

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.

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
Dashboard

The response identifies the grant and target project:

omnara grant skills add skl_ik7mv4qtrwz3jehcyd5n6a2bfg \
  --target-project-id proj_4qtrwz3jehcyd5n6a2bfgik7mv \
  --json

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"}'

await sdk.createSkillGrant({
  client,
  path: { orgID, skillID: 'skl_ik7mv4qtrwz3jehcyd5n6a2bfg' },
  body: { target_project_id: 'proj_4qtrwz3jehcyd5n6a2bfgik7mv' },
})

{
  "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):

curl "$OMNARA_API/orgs/$ORG/projects/$PROJ/skills" -H "Authorization: Bearer $OMNARA_TOKEN"

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.

Attach it to an agent

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

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.

Full schema and playground: Create skill · Update skill · List skills · Skill grants · Project skills.

Get started

Examples

Agents

Inputs & events

Tools

Machines

Organization

Integrations

Upload a skill

Update a skill

List, inspect, delete

Grant it to projects

Attach it to an agent

​Upload a skill

​Update a skill

​List, inspect, delete

​Grant it to projects

​Attach it to an agent

Upload a skill

Update a skill

List, inspect, delete

Grant it to projects

Attach it to an agent