Skill Bundle Format

SKILL.md frontmatter, scripts/references/assets layout, agentskills.io compatibility

Skill Bundle Format

A skill is a reusable knowledge-bundle that teaches an agent how to do a specific task. Skills are imported into the platform as .zip archives or created in-place via the Studio UI. This document specifies the exact file layout, frontmatter fields, and size limits for the .zip import path.

Upstream compatibility

The platform's skill format is a superset of agentskills.io (the open spec Anthropic published with Claude Agent Skills and which OpenAI Codex, VS Code, Cursor, Gemini CLI, and 20+ other clients implement). Any skill authored to the agentskills.io spec — including the flagship Anthropic bundles at github.com/anthropics/skills (pdf, xlsx, pptx, docx, skill-creator) — imports here without modification. The sections below call out our extensions explicitly.

References:

• Spec: https://agentskills.io/specification
• Anthropic announcement: https://www.anthropic.com/news/skills
• Reference implementations: https://github.com/anthropics/skills

Quick reference

• Entry point: SKILL.md at the archive root (or one level deep — see Nested layouts)
• Required frontmatter field: name
• Max archive size: 100 MB
• Max per-file size: 10 MB
• File types: script, reference, asset (inferred from directory name, see Files)

Minimum valid bundle

my-skill.zip
└── SKILL.md

SKILL.md:

---
name: my-skill
description: One-sentence summary shown in the agent builder.
---

# My Skill

When the user asks to do X, follow these steps:

1. First step
2. Second step

Full layout

my-skill.zip
├── SKILL.md              # Required — frontmatter + Markdown instructions
├── scripts/              # Executable helpers (auto-typed as `script`)
│   ├── render.py
│   └── check.sh
├── references/           # Supporting docs (auto-typed as `reference`)
│   ├── style-guide.md
│   └── glossary.md
└── assets/               # Binary / opaque data (auto-typed as `asset`)
    ├── template.docx
    └── logo.png

Nested layouts

The importer also accepts a single top-level directory wrapping the bundle:

my-skill.zip
└── my-skill/
    ├── SKILL.md
    ├── scripts/
    └── references/

This matches what most archive tools produce when zipping a folder. The top-level directory name is stripped; the contained SKILL.md is treated as the root.

Frontmatter

YAML between --- fences at the top of SKILL.md. All fields are optional except name.

Body

Everything after the closing --- is the Markdown body — this is what the platform injects into the agent's context when the skill loads. Write it as imperative, step-by-step instructions; avoid narrative prose.

Size guidance (from agentskills.io): keep SKILL.md under ~500 lines / 5 000 tokens. Longer content belongs in references/ — the load_skill_instructions tool returns the body verbatim and long bodies blow the LLM's context budget. Put runnable code in scripts/ so only the output enters context, not the source.

Our extensions vs. agentskills.io

Fields marked below are NOT in the upstream spec but are honoured by our importer when present:

Upstream skills omit these fields; they simply default (category=general, tags=[], user-invocable=true, etc.). Your agentskills.io-compliant bundle imports cleanly with zero edits.

Files

Any file under the archive root (other than SKILL.md) is attached to the skill as a typed file. The platform infers the file type from the top-level directory:

All files are stored UTF-8 — binary files must be kept under the 10 MB per-file cap. Files larger than 10 MB are rejected with HTTP 413.

Size limits

How the platform uses a skill at runtime

1. Discovery. An agent's skill grants make the skill visible to load_skill_instructions. The LLM sees name + description + category in its tool list.
2. Load. When the LLM calls load_skill_instructions(skill_id), the platform returns the SKILL.md body.
3. Scripts. If the skill carries scripts/ files, the LLM can call run_skill_script(skill_id, file_id) to execute them in the code sandbox. Only stdout/stderr enters LLM context — the source never does.
4. References / assets. Delivered on demand; not auto-injected.

Import ways

• UI: Studio → Skills → Import button → pick .zip or .json.
• API: POST /api/skills/import with multipart/form-data (field name: file).
• Studio inline: Create a skill, save, reopen with Edit → Upload file to attach scripts/references/assets one at a time.

Export

GET /api/skills/:id/export returns the bundle as a .zip in the canonical layout above. Round-tripping (export → import) reproduces the bundle byte-identical when content-hash is preserved.

Troubleshooting