Documentation Index
Fetch the complete documentation index at: /llms.txt
Use this file to discover all available pages before exploring further.
Skip to main content
Tools
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
Write the description as a trigger—“Use when…”—because it helps the model decide when to load the skill.
The owner (The CLI has no update command. Running
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 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.
| 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, For a project- or user-owned skill, set the owner accordingly:
$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"
}
--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.
.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.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— replacementSKILL.mdtext. Every other file in the current revision is kept.archive— a new.zipor.tar.gzthat 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"
omnara skills create again with the same owner and skill name uploads the next revision.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
- Dashboard
The response identifies the grant and target project:List a skill’s project grants with Each result reports whether the project owns the skill (
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"
}
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 },
})
direct) or receives it through a grant.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:skills:
- skl_ik7mv4qtrwz3jehcyd5n6a2bfg
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.