--- title: Skills | Luma Agents description: 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. 1**Write**`SKILL.md`Markdown with a name and description 2. 2**Upload**`POST /v1/skills`Stored as version 1 3. 3**Pin**`skills`Name the skill on POST /v1/sessions 4. 4**Use**`agent.skill_activated`The agent opens it when the work calls for it ## Write a skill A bundle is a `SKILL.md`, plus optional reference files: ```text brand-voice/ ├── SKILL.md └── references/ └── tone.md ``` `SKILL.md` starts with frontmatter: ```markdown --- 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. ## Upload it Zip the folder and post it from your backend with your API key: - [cURL](#tab-panel-0-0) - [Python](#tab-panel-0-1) - [TypeScript](#tab-panel-0-2) ```bash 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" ``` ```python import json import os import subprocess import urllib.request import 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().hex with 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"]) ``` ```typescript 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 = {}, ) { 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); ``` ```json { "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 List skills in `skills` on session create: - [cURL](#tab-panel-1-0) - [Python](#tab-panel-1-1) - [TypeScript](#tab-panel-1-2) ```bash 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 } ] }' ``` ```python session = post( "/sessions", {"scope_id": workspace_id, "skills": [{"skill_id": skill_id, "version": 1}]}, session_token, ) print(session["session_id"], session["skills"]) ``` ```typescript 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: ```json { "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](/agents/more/index.md). ## 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. Everything else is hidden, including Luma’s creative tools. A skill that lists only your [client tools](/agents/tools/index.md) leaves the agent unable to generate for the rest of the session. To keep generating, also list `query_creative_tools` and `execute_creative_tool`. `allowed-tools` guides the agent. It’s not a security boundary. ## Details ### What a bundle may hold | Path | Rule | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------- | | `SKILL.md` | Exactly one, UTF-8, starting with `---` frontmatter | | `references/.md` | Up to 64, lowercase names, no subfolders | | `assets/.` | 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 | 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 | 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 | 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. ## Next - [Tools](/agents/tools/index.md): give a skill something of yours to call. - [More capabilities](/agents/more/index.md): Luma’s own tools and platform skills.