Skill Tarball Requirements

Supported formats

Your archive must contain SKILL.md at the root of the extracted directory. The platform rejects archives that are missing this file.

SKILL.md must begin with a YAML frontmatter block:

---
name: my-skill
description: A one-sentence description of what this skill does.
---

# My Skill

(Rest of the skill documentation...)

Both name and description are required in the frontmatter.

The platform enforces the following during extraction:

Violating either constraint results in the upload being blocked with an error.

The slug you choose when uploading must match:

^[a-z0-9][a-z0-9-]*$

With optional namespace prefix:

^[a-z0-9][a-z0-9-]*:[a-z0-9][a-z0-9-]*$

Valid: my-skill, acme:token-transfer, balance-checker Invalid: My_Skill, ../escape, acme/skill

See Uploading a Skill for the full upload flow.

Error	Cause	Fix
`BLOCKED: missing SKILL.md`	No `SKILL.md` at archive root	Add `SKILL.md` to the top level of your archive
`BLOCKED: symlink or path traversal`	Archive contains symlinks or `../` paths	Remove all symlinks and relative path entries
`BLOCKED: decompressed too large`	Extracted content exceeds 50 MB	Trim large files and unnecessary assets
`BLOCKED: too many files`	File count exceeds 1,000	Reduce the number of files in the archive
`TARBALL_TOO_LARGE`	Archive exceeds 5 MB	Compress more aggressively or remove large assets
`UNSUPPORTED_FORMAT`	Unrecognised archive format	Use `.tar.gz`, `.tgz`, `.zip`, or `.rar`