Skill package format

A skill package is a ZIP archive with a SKILL.md file at its root and any supporting files the job needs. Atlan checks every package when you publish it, and refuses one that breaks a rule on this page.

Layout

incident-review.zip
├── SKILL.md                      # required, at the root, exactly this name
├── references/
│   └── incident-format.md        # longer material SKILL.md links to
├── templates/
│   └── review.md
└── scripts/
    └── collect-context.sh

SKILL.md must sit at the root of the archive, not inside a folder. The name is case-sensitive.
Supporting files can use any folder names and file types. Atlan doesn’t restrict file extensions.
The package must be a ZIP archive.

SKILL.md

SKILL.md starts with YAML front matter between two --- lines, followed by the Markdown instructions.

---
name: incident-review
description: Write an incident review with a timeline, causes, and follow-up actions. Use after an incident or when asked to review one.
license: Apache-2.0
allowed-tools: Read, Write
metadata:
  lifecycle: active
---

# Incident review

1. Read the incident timeline and list the contributing causes.
2. Assign each follow-up action to an owner. See references/incident-format.md.
3. Draft the review from templates/review.md.

The first line must be exactly ---. The body after the closing --- is required and can’t be blank.

Front matter fields

Field	Type	Required	Meaning and limits
`name`	string	Yes	The skill’s machine name. See Naming rules. Up to 64 characters.
`description`	string	Yes	What the skill does and when to use it. Up to 1,024 characters.
`when_to_use`	string	No	A longer version of when to use the skill. Up to 1,024 characters.
`license`	string	No	The package’s license, such as `Apache-2.0`. Up to 128 characters.
`allowed-tools`	list, or a string separated by spaces or commas	No	Tools the skill expects to use. Up to 256 entries of up to 256 characters each.
`arguments`	list, or a string separated by spaces or commas	No	Named arguments. Up to 64 entries of up to 128 characters each.
`argument-hint`	string	No	A hint shown for the arguments. Up to 256 characters.
`compatibility`	string	No	Where the skill works. Up to 500 characters.
`version`	string	No	Your own version label. Up to 64 characters. Atlan numbers versions separately.
`model`	string	No	A model the skill prefers. Up to 128 characters.
`metadata`	mapping	No	Your own keys. Up to 64 keys and 16 KiB. If you set `metadata.lifecycle`, it must be `draft`, `active`, or `deprecated`.
`disable-model-invocation`	boolean	No	`true` or `false`.
`user-invocable`	boolean	No	`true` or `false`.

Other rules:

Lengths count characters, except metadata and the whole front matter, which count bytes.
The whole front matter can be up to 32 KiB.
The instructions after the front matter can be up to 500,000 characters.
Atlan keeps keys it doesn’t recognize but doesn’t act on them.
Booleans must be true or false. yes and no are read as text, so they fail a boolean field.

Naming rules

Characters: Lowercase letters a–z, digits, and hyphens. No spaces, capitals, or underscores.
Hyphens: The name can’t start or end with a hyphen.
Length: 1 to 64 characters.
Match: When you create a skill, the skill’s name must equal the name in SKILL.md.
Unique per workspace: Two skills in one workspace can’t share a name. The same name can exist in another workspace.
Archived skills keep their name. Creating a new skill with an archived skill’s name in the same workspace is refused with 409.
Fixed after creation: You can’t rename a skill’s machine name. Change its display name instead.

Name a skill for its job, such as incident-review, not for its team or author.

Package limits

Limit	Value
Compressed archive	10 MiB
Total uncompressed size	500 MiB
Entries in the archive, including folders	10,000
Path length	1,024 bytes
Folder depth	8 folders, so 9 path segments including the file name
Compression ratio per file	100 to 1

The archive is also refused if it contains:

A symbolic link.
An absolute path, or a path with a .. segment.
Two entries with the same path.
No files at all.

Limits in Atlan’s tools

Some tools apply their own checks before upload:

Tool	What it checks
Atlan Desktop	Skips `.git`, `node_modules`, `target`, `dist`, and `.venv` folders, and leaves out dotfiles and credential files.
`aireg`	Up to 1,000 files and 20 MiB uncompressed per skill. Refuses paths with a `.git` segment, `..`, `:`, `\`, or control characters.

Write a good description

Atlan’s skill search reads only name and description, so the description decides whether people and agents find the skill. when_to_use isn’t searched.

Say what it does and when to use it. Write it as a trigger, not a title.
Name the request it answers, in the words people use.
Keep detail out of it. Put long material in references/ files and link to them from the body.

Weak	Strong
`Preview deployment skill.`	`Deploy a branch to a preview environment and report the URL. Use when asked to put a branch somewhere reviewable, or to share work in progress.`

Errors

Response	Cause
`422` `Missing required field 'SKILL.md'.`	No `SKILL.md` at the archive root.
`422` `Missing required field 'SKILL.md.frontmatter'.`	`SKILL.md` doesn’t start with `---`.
`422` `Field 'SKILL.md.frontmatter' is not valid.`	The front matter isn’t closed with `---`, or isn’t valid YAML.
`422` `Missing required field 'SKILL.md.body'.`	Nothing follows the front matter.
`422` `Missing required field 'SKILL.md.name'.` or `Missing required field 'SKILL.md.description'.`	A required field is missing or blank.
`422` `Field 'SKILL.md.name' is not valid.`	The name breaks a naming rule, or doesn’t match the skill’s name.
`422` `Field 'SKILL.md.<field>' is not valid.`	Another field is too long or the wrong type.
`422` `The request is well-formed but failed validation.`	The archive breaks a package limit, such as being over 10 MiB.
`409` `A resource with identical content already exists in this workspace.`	You uploaded a package byte-for-byte identical to an existing one.
`413`	The request body is over 16 MiB.

For help with a failed publish, see Skill errors.

How skill source works: How Atlan shows a package’s files and provenance.
Choose skill publishing method: Ways to publish a package.
How skill security scans work: The scan every version gets after it’s accepted.

Skill management

Agent management

AI Gateway

Metrics Studio

Ontology

Layout

SKILL.md

Front matter fields

Naming rules

Package limits

Limits in Atlan’s tools

Write a good description

Errors

​Layout

​SKILL.md

​Front matter fields

​Naming rules

​Package limits

​Limits in Atlan’s tools

​Write a good description

​Errors

​Related

Layout

SKILL.md

Front matter fields

Naming rules

Package limits

Limits in Atlan’s tools

Write a good description

Errors

Related