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.
- 1Write
SKILL.mdMarkdown with a name and description - 2Upload
POST /v1/skillsStored as version 1 - 3Pin
skillsName the skill on POST /v1/sessions - 4Use
agent.skill_activatedThe agent opens it when the work calls for it
Write a skill
Section titled “Write a skill”A bundle is a SKILL.md, plus optional reference files:
brand-voice/├── SKILL.md└── references/ └── tone.mdSKILL.md starts with frontmatter:
---name: brand-voicedescription: 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
descriptionwith 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.mdshort and point to reference files. The agent readsSKILL.mdevery time it opens the skill, and a reference only whenSKILL.mdsends it there. - Check that it fires. The stream carries
agent.skill_activatedthe first time the agent opens a skill.
Upload it
Section titled “Upload it”Zip the folder and post it from your backend with your API key:
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"import jsonimport osimport subprocessimport urllib.requestimport uuid
BASE = "https://agents.lumalabs.ai/v1"
def post(path, body, token, headers=None): request = urllib.request.Request( BASE + path, method="POST", data=json.dumps(body).encode(), headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json", **(headers or {})}, ) with urllib.request.urlopen(request) as response: return json.load(response)
subprocess.run(["zip", "-r", "brand-voice.zip", "brand-voice"], check=True)
boundary = uuid.uuid4().hexwith open("brand-voice.zip", "rb") as f: bundle = f.read()form = ( f"--{boundary}\r\n" 'Content-Disposition: form-data; name="file"; filename="brand-voice.zip"\r\n' "Content-Type: application/zip\r\n\r\n").encode() + bundle + f"\r\n--{boundary}--\r\n".encode()
request = urllib.request.Request( BASE + "/skills", method="POST", data=form, headers={ "Authorization": f"Bearer {os.environ['LUMA_AGENTS_API_KEY']}", "Content-Type": f"multipart/form-data; boundary={boundary}", },)with urllib.request.urlopen(request) as response: skill = json.load(response)skill_id = skill["id"]print(skill["name"], skill["latest_version"])import { execFileSync } from "node:child_process";import { readFile } from "node:fs/promises";
const BASE = "https://agents.lumalabs.ai/v1";
async function post( path: string, body: unknown, token: string, headers: Record<string, string> = {},) { const response = await fetch(BASE + path, { method: "POST", headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", ...headers, }, body: JSON.stringify(body), }); if (!response.ok) throw new Error(`${response.status} ${await response.text()}`); return response.json();}
execFileSync("zip", ["-r", "brand-voice.zip", "brand-voice"]);
const form = new FormData();form.append( "file", new Blob([await readFile("brand-voice.zip")], { type: "application/zip" }), "brand-voice.zip",);
const upload = await fetch(`${BASE}/skills`, { method: "POST", headers: { Authorization: `Bearer ${process.env.LUMA_AGENTS_API_KEY!}` }, body: form,});if (!upload.ok) throw new Error(`${upload.status} ${await upload.text()}`);const skill = await upload.json();const skillId: string = skill.id;console.log(skill.name, skill.latest_version);{ "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.
Pin it on a session
Section titled “Pin it on a session”List skills in skills on session create:
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 } ] }'session = post( "/sessions", {"scope_id": workspace_id, "skills": [{"skill_id": skill_id, "version": 1}]}, session_token,)print(session["session_id"], session["skills"])const session = await post( "/sessions", { scope_id: workspaceId, skills: [{ skill_id: skillId, version: 1 }] }, sessionToken,);console.log(session.session_id, session.skills);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.
Narrow the tools a skill may use
Section titled “Narrow the tools a skill may use”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.
Details
Section titled “Details”What a bundle may hold
Section titled “What a bundle may hold”| Path | Rule |
|---|---|
SKILL.md | Exactly one, UTF-8, starting with --- frontmatter |
references/<name>.md | Up 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.
Frontmatter
Section titled “Frontmatter”| Field | Rule |
|---|---|
name | 4 to 64 lowercase letters, digits, - or _. Can’t start with platform. Fixed across versions |
description | 32 to 1,000 characters |
allowed-tools | Optional list of tool names |
Limits
Section titled “Limits”| Limit | Value |
|---|---|
| Upload size | 8 MB |
| One text file | 128,000 bytes |
| All text files | 512 KB |
| Skills per API client | 500 |
| Versions per skill | 1,000 |
| Skills pinned per session | 20 |
Common refusals
Section titled “Common refusals”| Code | When |
|---|---|
422 CLIENT_SKILL.MODERATION_REJECTED | Content moderation flagged a file, or couldn’t finish in time. paths names the files |
422 CLIENT_SKILL.NAME_MISMATCH | A new version names a different skill |
422 CLIENT_SKILL.CONFLICTS_WITH_APP | skills sent beside app |
422 CLIENT_SKILL.NAME_CONFLICT | Two pinned skills share a name |
404 CLIENT_SKILL.NOT_FOUND | Deleted, 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.
- Tools: give a skill something of yours to call.
- More capabilities: Luma’s own tools and platform skills.