Format package files: which types and paths the Contents API accepts

A Sume Format package may contain only .md, .json, .yaml, .yml and .txt files. SKILL.md at the package root is required, and every other file must sit at the root or one directory level under references/ or agents/. If you send a path that breaks the rules, the Contents API commits nothing and answers skill_path_invalid with the full allowlist.

The rules in one table

These are the rules the Contents API enforces, and the dashboard editor enforces the same ones.

What this means in practice

You cannot ship an image, a font or a video inside the package. Put reference text, brand notes, shot lists and JSON examples in references/, and pass media as URLs through attachments or input when you call the Format. A file named _notes.md or .env fails the name pattern, so rename it before you write.

The write is all or nothing. A PUT to the package root with a files list commits every file as one commit or none of them. A failed sha check on one entry also stops the batch.

Writing a note

The request below creates references/brand-notes.md. content is the file body in base64. Because the path is new, no sha is sent; for an existing path you must send the current sha, or you get 409 format_content_sha_required. The handle and slug are placeholders for a Format your key owns, and the key needs formats:write.

curl -sS -X PUT \
  "https://api.sume.com/v1/formats/acme/event-recap/contents/references/brand-notes.md" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "add brand notes", "content": "IyBCcmFuZCBub3RlcwoK"}'

When a write is refused

Three answers come up most. skill_path_invalid means a path or type broke a rule. skill_frontmatter_invalid means the SKILL.md header is wrong, for example a name that differs from the slug. skill_limit_exceeded means a size or count limit. Read the response before you retry; none of them is fixed by repeating the same request.

Planning the layout

A layout that stays inside the rules is simple. Keep SKILL.md short and procedural: what the Format does, what it reads from input, and the order of steps. Put long reference material in references/ as .md or .txt, and put examples of the output shape in .json. The agents/ folder is also allowed, one level deep.

Because only text-like files are allowed, anything visual must come from the caller or from the generation tools at run time. A logo, for example, should be passed as an HTTPS URL in input or as an attachment on each run. If the logo changes, you change the call, and not the package. A batch of file edits is one commit and one version increase, which keeps the history readable when several files change for one reason.