Skills cookbook

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.

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.

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.

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.

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.

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.

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.

Overview

CLI

SDK

Cookbooks

Operate safely

API reference

Publish a Skill

Bulk-create Skills

Find and retrieve a version

Publish a content change

Inspect usage

​Publish a Skill

​Bulk-create Skills

​Find and retrieve a version

​Publish a content change

​Inspect usage

Publish a Skill

Bulk-create Skills

Find and retrieve a version

Publish a content change

Inspect usage