Skills
Instruction packs agents load progressively at chat time.
A skill is an instruction pack for your org: a SKILL.md, plus optional
reference files bundled with it, attached to agents in the editor.
Instructions are always in the prompt, but skills load progressively. The
model reads the skill list, calls use_skill for the one it needs, then pages
through bundled files with read_skill_file. Long references cost nothing
until they're opened.
Authoring
You can create a skill two ways: write the markdown in the UI, or upload a zip. Every skill has:
name(required): lowercase letters, digits, and hyphens, up to 64 characters, unique in the org.anthropicandclaudeare reserved.description(required, up to 1,024 characters): what the model reads in the skill list to decide when to load the skill.displayTitle(optional, up to 128 characters): the label shown in the library.
For an upload, these come from the SKILL.md frontmatter. Form fields sent
with the upload take priority. Frontmatter may be YAML (the default) or JSON.
JavaScript frontmatter is rejected.
---
name: refund-policy
description: How to decide and word refunds. Use for any refund or return question.
---
# Refunds
Check the order date first. See references/limits.md for the thresholds.Uploads are checked up front:
| Rule | Limit |
|---|---|
| Zip size | 5 MB |
SKILL.md location | At the archive root or one folder deep |
SKILL.md size | 1 MB, and about 50,000 tokens |
| Bundled files | 50 files, 1 MB each, 10 MB total |
| Bundled file types | .md .txt .json .csv .yaml .yml .xml .html .htm |
Paths that escape the archive (zip-slip), symlinks, and files outside the skill's folder are rejected. The token cap applies to written skills too, so an oversized skill fails when you save it instead of quietly degrading at runtime. Split a large skill or move material into bundled files. Written skills have no bundled files.
Skill files are stored in object storage under your org. read_skill_file
can open only files listed in the skill's manifest, and it returns up to 2,000
lines at a time, paged with offset and limit.
Built-ins
Four document skills ship with the product: pdf, docx, xlsx, and
pptx. They're on every turn, cost about a line each in the system prompt,
and describe the document libraries run_code can use (Tools). An
org skill with the same name replaces the built-in.
Using skills in chat
The model decides when to load a skill. In the Assivy app, users can also
point at one by typing / in the chat box. It lists the agent's skills and
inserts the chosen name.
Sharing
A skill with no sharing set inherits its agent's audience. Skills a user isn't
allowed to use are never named anywhere: not in the skill list, not in the
use_skill options, and not through the file tool. A restricted skill is
invisible rather than forbidden.
Manage skills under Library → Skills, where each skill opens a file-tree
viewer over its SKILL.md and bundle. API: POST /skills,
POST /skills/upload (multipart, field file), GET /skills,
GET /skills/:id, GET /skills/:id/body, GET /skills/:id/files/<path>,
PATCH /skills/:id, DELETE /skills/:id. Deleting a skill removes its files
from storage and soft-deletes the row.