Skip to content
Going further

Skills

Write guidance once in Markdown, upload it as a skill, and attach it to any session.

A skill is guidance you write once and attach to any session: your house style, a product’s rules, a review checklist, or how to use one of your tools. You write it as a small bundle of Markdown, upload it, and pin it on the sessions that need it.

The agent doesn’t read a pinned skill up front. For each one it sees a single line: the skill’s name, its description, and the names of its files. It opens a skill only when the work calls for it. So a session can carry several skills cheaply, and the description decides whether a skill is used at all.

Skills are for sessions without an app. A workflow app gets its guidance from its own release.

  1. 1WriteSKILL.mdMarkdown with a name and description
  2. 2UploadPOST /v1/skillsStored as version 1
  3. 3PinskillsName the skill on POST /v1/sessions
  4. 4Useagent.skill_activatedThe agent opens it when the work calls for it

A bundle is a SKILL.md, plus optional reference files:

brand-voice/
├── SKILL.md
└── references/
└── tone.md

SKILL.md starts with frontmatter:

---
name: brand-voice
description: House voice for Acme copy. Use it for any tagline, headline or short marketing line.
---
# Acme brand voice
Before you write any copy, read `references/tone.md` and follow it.
End every tagline with a full stop.

A few habits make a skill fire:

  • Start the description with the situation, not the content. “Use it for any tagline” tells the agent when to open it. “Acme’s tone rules” does not.
  • Keep SKILL.md short and point to reference files. The agent reads SKILL.md every time it opens the skill, and a reference only when SKILL.md sends it there.
  • Check that it fires. The stream carries agent.skill_activated the first time the agent opens a skill.

Zip the folder and post it from your backend with your API key:

Terminal window
zip -r brand-voice.zip brand-voice
curl -s -X POST https://agents.lumalabs.ai/v1/skills \
-H "Authorization: Bearer $LUMA_AGENTS_API_KEY" \
-F "file=@brand-voice.zip;type=application/zip"
{
"id": "bbc17e21-e13d-4704-9652-179ef9d41177",
"name": "brand-voice",
"scope_id": null,
"latest_version": 1
}

Keep the id. It’s what a session pins, and it stays the same across versions.

Uploaded without a scope_id, a skill is available to sessions in any of your workspaces. Add a scope_id form field to make it a workspace skill, which only sessions in that workspace can pin. A session token with the generate permission can manage workspace skills but only read the shared ones.

To change a skill, edit the bundle and post it to /v1/skills/$SKILL_ID/versions. Versions are numbered 1, 2, 3 and never change. Uploading identical files publishes nothing, so a retry is safe.

List skills in skills on session create:

Terminal window
curl -s -X POST https://agents.lumalabs.ai/v1/sessions \
-H "Authorization: Bearer $SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"scope_id": "'"$WORKSPACE_ID"'",
"skills": [ { "skill_id": "'"$SKILL_ID"'", "version": 1 } ]
}'

version is a number or "latest", the default. latest is resolved once, at create, and the response shows the number you got. Pin a number when two sessions must be comparable.

A pin lasts for the session’s life. A new version doesn’t move it, and deleting the skill doesn’t break it. Start a new session to pick up a new version.

When the agent first opens a skill, the stream carries:

{
"type": "agent.skill_activated",
"skill_name": "brand-voice",
"source": "client",
"skill_id": "bbc17e21-…",
"version": 1
}

It’s sent once per skill per session. A pinned skill the agent never needed produces no event. If you expected one and none came, the description didn’t match the work. Rewrite it to say when to use the skill, or name the skill in your message.

Luma also ships a few platform skills with craft guidance. They show up on the stream with source: "slug". See More capabilities.

A skill can declare allowed-tools in its frontmatter. Once the agent reads that skill, the session narrows to the tools it lists, plus the tools the agent needs to read skills and finish.

allowed-tools guides the agent. It’s not a security boundary.

PathRule
SKILL.mdExactly one, UTF-8, starting with --- frontmatter
references/<name>.mdUp to 64, lowercase names, no subfolders
assets/<name>.<ext>Workspace skills only, up to 64 images, PDFs, videos or text files. The agent sees each asset’s path but can’t open it

Nothing in a bundle is ever run. Any other path is refused with CLIENT_SKILL.INVALID_BUNDLE.

FieldRule
name4 to 64 lowercase letters, digits, - or _. Can’t start with platform. Fixed across versions
description32 to 1,000 characters
allowed-toolsOptional list of tool names
LimitValue
Upload size8 MB
One text file128,000 bytes
All text files512 KB
Skills per API client500
Versions per skill1,000
Skills pinned per session20
CodeWhen
422 CLIENT_SKILL.MODERATION_REJECTEDContent moderation flagged a file, or couldn’t finish in time. paths names the files
422 CLIENT_SKILL.NAME_MISMATCHA new version names a different skill
422 CLIENT_SKILL.CONFLICTS_WITH_APPskills sent beside app
422 CLIENT_SKILL.NAME_CONFLICTTwo pinned skills share a name
404 CLIENT_SKILL.NOT_FOUNDDeleted, or another workspace’s skill

An upload answers only after moderation finishes, so set a generous client timeout. GET /v1/skills/{skill_id}/versions/{version}/files/{path} reads a file back. SKILL.md comes back with normalized frontmatter, so compare hashes against what you read back, not your local file.