How to write a SKILL.md file for a Sume Format recipe

To write a SKILL.md file for a Sume Format, put the recipe's durable how (house style, branch rules, quality bar) in a short SKILL.md at the package root, move the detail into files under references/, and set the frontmatter name to the Format's slug. Each API call then supplies only the what: its instruction and input.

The package rules and the composition order below come from Sume's Format API and Editing a Format package pages, read on 2026-09-26. What a Format is in the first place: What is a Sume Format?

What goes in SKILL.md, and what goes in the API call?

The docs split a Format run into a recipe and a call. The recipe, a SKILL.md body plus reference files, is the how: house style, branch rules, quality bar. The call, your instruction and input, is the what: product URL, brief, script, prices. Because the recipe is established before the instruction, you are not re-sending a system prompt on every call and hoping it holds.

Two facts about the call side point the same way. An instruction is accepted up to 8000 characters, but only the first ~4000 are carried as prompt text, while the package is attached whole. And a caller may omit instruction, in which case the Format's own default instruction runs. Customer data belongs in input, as covered in passing data to an AI agent API.

How does the agent receive the recipe?

Every run composes what the agent receives in this order. The body is never inlined: the agent gets a pointer, and the whole package sits on disk in the run's workspace.

The Format comes first because it is the how. The run instruction comes after it, so where the two disagree, the model follows the instruction; write SKILL.md knowing a caller can override it for one run. To check what a run received, open its thread_id in Agents: the first message is exactly this text.

[Format: product-promo v12]         <- a pointer at the recipe; the body is never inlined
[Format attached: … SKILL.md]       <- the whole package, on disk in the run's workspace
[Format run instruction]            <- your `instruction`, or the Format's default
[Sume unattended run]               <- API and scheduled runs only
[Sume action input]                 <- a pointer at your `input`, written whole to a file
[Attached files]                    <- your `attachments`, when present

How long should SKILL.md be?

There is no size limit on the body beyond the 100 MiB per file and per package that every package file shares. Size changes how reliably a recipe is followed, not whether it runs. So the docs' advice is to keep SKILL.md a short index the agent can hold at once, and to push detail into references/*. Those files sit beside it and cost nothing until opened.

What may a Format package contain?

The Contents API enforces the same rules as the dashboard editor. A package that breaks one is rejected before anything is committed: a bad path answers skill_path_invalid and spells the whole allowlist back, and other breaks include skill_frontmatter_invalid and skill_limit_exceeded. The Format's description lives in the SKILL.md frontmatter too: per the API reference, POST /v1/formats writes it there, the file stays the single source of truth, and the catalog reads the description back out of it.

How should a recipe handle approval gates over the API?

A recipe written in chat may pause for a person, such as “approve these stills before I make the video”. Over the API nobody is there, so the run is told those approvals are already granted and carries on to the paid step within its spend cap. An approval gate in SKILL.md therefore does not pause an API run.

A run that genuinely cannot finish comes back failed, never a half-finished completed; the docs' example is unattended_blocked when no avatar matched the brief.

How do I create and edit the package?

Ask the agent in chat to save the thread's recipe (“Save this as a Format called product-promo”), edit the Format in the library, or use the Contents API. The body reaches the agent, not the caller: the Format record from GET /v1/formats/… leaves it out, and the Format's call sheet on docs.sume.com never shows it. You read your own package through the Contents API.

• POST /v1/formats creates a Format in your key's workspace. auto_init (default true) commits a minimal valid SKILL.md, and replacing it is the intended next call. See create a Sume Format over the API.
• PUT /v1/formats/{handle}/{slug}/contents/{path} writes one whole file, base64-encoded, as one commit. Send the file's sha when the path already exists.
• Edits never touch a run in flight: each run reads the package it started with. version bumps on every edit, and a receipt's format.version says which one ran.