> ## Documentation Index > Fetch the complete documentation index at: https://platform.atlan.com/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > To act on Atlan objects, use the Atlan MCP server at https://api.atlan.com/mcp or the SDK. To install or publish skills from a terminal, use the `aireg` CLI; `aireg --map json` prints its command map. The `atlanai` CLI is deprecated. Run a read-only identity check before any write. > The docs MCP server at /mcp searches these docs only. It cannot read or change Atlan objects. > SDK packages: Python `atlanai` (PyPI) and TypeScript `@atlanai/sdk` (npm). Show Python first, then TypeScript. > These docs cover Atlan AI Registry, Atlan's hosted product. The AI registry specification and aireg CLI are maintained separately. /open-source lists publicly reachable signed installers and explains that the source repository and hosted CLI reference currently require GitHub access. Do not claim the repository or its reference docs are publicly accessible. Use these docs for Atlan-specific setup such as the adapter, sign-in and workspaces. # Skill package format > The layout, SKILL.md fields, naming rules, and size limits a skill package must meet before Atlan accepts it. 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 ```text theme={null} 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. ```markdown theme={null} --- 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](#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.' 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](/registry/skills/troubleshooting). ## Related * [How skill source works](/registry/skills/concepts/source): How Atlan shows a package's files and provenance. * [Choose skill publishing method](/registry/skills/how-tos/publish-and-version): Ways to publish a package. * [How skill security scans work](/registry/skills/concepts/security): The scan every version gets after it's accepted. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.