> ## 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.

# Skills cookbook

> Publish, retrieve, version, and inspect reusable Skills.

Use this cookbook to publish a reusable Skill, retrieve a known version, and
inspect how it is used. It is for developers automating that lifecycle through
the public API.

<Note>
  **Preview.** Start with a disposable workspace and an approved canonical
  sample bundle. This guide uses the current multipart contract; it does not
  define a new Skill package format.
</Note>

## Publish a Skill

Prepare a ZIP bundle with `SKILL.md` at its root and only the supporting files
the Skill needs. The `metadata` multipart part carries the Skill name, optional
description, and target workspace. The `body` part carries the ZIP.

```bash theme={null}
curl -sS --fail-with-body \
  -X POST "${ATLAN_GATEWAY_URL}/skill/v1/skills" \
  -H "Authorization: Bearer ${ATLAN_TOKEN}" \
  -F 'metadata={"name":"disposable-example","description":"A disposable documentation check","workspace_id":"workspace_01example"};type=application/json' \
  -F 'body=@./disposable-example.zip;type=application/zip'
```

Do not include tokens, customer data, or private source material in the
bundle. A Skill with the same name in the same workspace receives a new version
when its content changes; identical content does not create a duplicate.

The response identifies the Skill and its current version. Preserve those
values in your deployment record rather than finding the Skill again by name.

## Bulk-create Skills

Use the bulk endpoint when an application needs to create a one-time batch of
new skill bundles. It accepts at most 100 items. Each item in the `items` JSON
array supplies the same metadata used for one Skill and a `body_part` name. The
multipart request includes a ZIP body under each of those names.

<Note>
  **Preview.** A bulk response is `207 Multi-Status`, even when some items were
  created. Read every returned item instead of treating the HTTP status alone as
  a successful import.
</Note>

```bash theme={null}
items='[
  {
    "metadata": {
      "name": "incident-brief",
      "description": "Create an incident brief from a reviewed timeline.",
      "workspace_id": "workspace_01example"
    },
    "body_part": "incident-brief"
  },
  {
    "metadata": {
      "name": "release-notes",
      "description": "Turn merged changes into release notes.",
      "workspace_id": "workspace_01example"
    },
    "body_part": "release-notes"
  }
]'

curl -sS --fail-with-body \
  -X POST "${ATLAN_GATEWAY_URL}/skill/v1/skills/bulk" \
  -H "Authorization: Bearer ${ATLAN_TOKEN}" \
  -F "items=${items};type=application/json" \
  -F 'incident-brief=@./incident-brief.zip;type=application/zip' \
  -F 'release-notes=@./release-notes.zip;type=application/zip'
```

The response `items` array follows the request order. A `201` item includes the
created skill. A rejected item includes its own status and problem document;
successful items are not rolled back. For a duplicate-content rejection, the
problem can include `existing_artifact_id`, which identifies the skill that
already holds that content.

Use the returned IDs to inspect every created skill and record failed item
indexes for a corrected retry. Do not resubmit a whole batch until you know
which items were created.

## Find and retrieve a version

Use the current Skill when you need the latest maintained package. Use a pinned
version when an environment needs reproducible content. The **Skill** API
category covers listing, searching, reading a selected version, and downloading
its bundle. Verify that the selected version contains the files your consuming
environment expects.

```bash theme={null}
curl -sS --fail-with-body \
  -H "Authorization: Bearer ${ATLAN_TOKEN}" \
  -o ./disposable-example.zip \
  "${ATLAN_GATEWAY_URL}/skill/v1/skills/skill_01example/versions/1/bundle"
```

The bundle response is `application/zip`, not JSON. Compare the downloaded
package with the source bundle before a consuming environment uses it.

## Publish a content change

Upload an updated ZIP to publish updated Skill content. Use the
version-specific read or bundle actions in the **Skill** API category to verify
that a consumer will receive the intended version. Use the same category when
only a name or description needs to change.

## Inspect usage

Use the trace actions in the **Skill** API category to investigate use after
publication. For product guidance on reviewing a Skill before use, see
[Discover and use a skill](/guides/skills/discover-and-use).