Databricks Opens the Unity Gateway Skills API and SDKs in Beta

If your team builds AI agents, you may have written the same instructions more than once. One agent needs to follow your company's SQL naming rules. Another needs to review Python code using your team's standards. A third needs to prepare reports in a specific format.

Keeping these instructions in separate prompts makes them difficult to maintain. When a rule changes, developers must find every place where it is used and update it manually.

Databricks is addressing this problem with the Unity Gateway Skills API, now available in Beta. Announced on October 12, 2026, the API lets developers create, manage, publish, and share agent skills programmatically through Databricks developer tools.

A skill is a reusable set of instructions and supporting files that tells an AI agent how to handle a particular task. Databricks registers these skills in Unity Catalog, where teams can manage access using permissions.

The new API supports the main lifecycle operations, including creating a skill, uploading its files, finalizing it, listing available skills, updating its metadata, and deleting it. Developers can work with the REST API, Databricks CLI, and supported SDKs for Python, Go, Java, and JavaScript.

For teams managing multiple agents, this means skills can become shared, governed resources instead of instructions copied between projects.

What Is a Skill in Unity Gateway?

A skill is a bundle of instructions and supporting files that an AI agent can load when it needs to perform a particular task.

For example, a data engineering team might create a skill that explains how to write SQL queries against its warehouse. The skill could specify approved table names, naming conventions, rules for handling null values, and the checks that should run before a query is deployed.

A coding agent could load those instructions when working on a data pipeline. Another agent could use the same skill when reviewing a pull request.

A typical skill contains a SKILL.md file with YAML frontmatter and Markdown instructions. It can also include supporting files when the task needs them.

Here is a simple example:

---
name: sql-review
description: Review SQL queries for correctness and maintainability.
---

# SQL Review

When reviewing a SQL query:

1. Check whether joins use the correct keys.
2. Look for filters that may exclude valid records.
3. Check how NULL values are handled.
4. Identify repeated calculations that can be simplified.
5. Explain potential performance problems.
6. Do not claim that a query is correct without checking its logic.

The frontmatter provides the skill's name and description. The Markdown section contains the instructions the agent should follow when the skill is loaded.

The example is a basic instruction file, not a complete SQL validation system. The agent still needs access to the relevant query and context to apply the instructions correctly.

Why Register Skills in Unity Catalog?

Keeping a skill in a local project folder works for a small application. It becomes harder to manage when several teams and agents need the same instructions.

Unity Catalog gives skills a managed resource identity and access controls.

A skill has a resource name in this format:

skills/{catalog}.{schema}.{skill}

For example, a skill named sql_review in the main catalog and default schema could be identified as:

skills/main.default.sql_review

This identity lets developers manage the skill through the API and apply Unity Catalog permissions to it.

Without centralized skill management	With Unity Catalog skills
Instructions may be copied into multiple repositories	A shared skill can be registered once
Teams must coordinate updates manually	Developers can update the registered bundle
Access rules may differ between projects	Unity Catalog permissions control who can read or manage the skill
Finding available instructions can be difficult	Authorized users can list skills in a schema
Changes may be hard to track across deployments	Skill metadata and resource identity provide a managed reference

Registering a skill does not automatically make it available to every agent. Users and applications still need the appropriate permissions, and the agent must support loading the skill.

What Does the New Skills API Support?

The Beta REST API provides operations for managing the full skill lifecycle.

Operation	Purpose
Create	Register a skill and provision its bundle storage
Upload	Add `SKILL.md` and supporting files
Finalize	Validate the skill file and publish its name and description as metadata
List	Find skills available in a schema
Get	Retrieve a skill's metadata
Update	Change the skill's comment
Delete	Remove the skill and its bundle

There is an important distinction between uploading and finalizing a skill. Uploading the files does not complete the registration process. Finalization reads and validates SKILL.md, then sets the skill's bundle name and description from its frontmatter.

The API also supports an etag value for conditional updates and deletions. This helps prevent a client from unintentionally changing or deleting a skill after another user has modified it.

Creating a Skill with the Python SDK

The Python SDK is a convenient starting point if your team already uses Python to manage Databricks resources.

Before running the example, install a supported SDK version and authenticate a Databricks workspace client. The current Skills API documentation requires databricks-sdk version 0.142.0 or later.

The following code creates the skill resource:

from databricks.sdk import WorkspaceClient
from databricks.sdk.service import catalog as c

w = WorkspaceClient()

skill = w.ai_gateway.create_skill(
    parent="schemas/main.default",
    skill_id="sql_review",
    skill=c.Skill(
        comment="Shared SQL review instructions for data teams"
    ),
)

print(skill.name)

The parent parameter identifies the Unity Catalog schema where the skill will live. The skill_id provides its resource identifier, and comment gives administrators a short explanation of its purpose.

This operation creates the resource and its bundle storage. It does not upload the instructions or make the skill ready for use.

Keep that distinction in mind when automating deployment. A successful create request is only the first step.

Uploading and Finalizing the Skill

After creating the resource, prepare a SKILL.md file with the required frontmatter and instructions.

The Python SDK's Files API can upload the file to the skill's storage path:

with open("SKILL.md", "rb") as skill_file:
    w.files.upload(
        "/Skills/main/default/sql_review/SKILL.md",
        skill_file,
        overwrite=True,
    )

The path uses the catalog, schema, and skill identifier from the example. The overwrite=True option allows the upload to replace an existing file at that path, so use it carefully in automated deployments.

Once the file has been uploaded, finalize the skill:

finalized = w.ai_gateway.finalize_skill(
    name="skills/main.default.sql_review"
)

print(finalized.bundle_name)
print(finalized.description)

Finalization validates SKILL.md and reads its frontmatter. If the file is missing the required name or description fields, or otherwise fails validation, finalization will not succeed.

If you change the skill's instructions later, upload the updated bundle and finalize it again. Updating a skill's comment is a separate operation from changing its content.

The complete process is therefore:

Create the skill resource.
Upload SKILL.md and any supporting files.
Finalize the skill.
Grant access to the users or groups that need it.
Test that an agent can discover and load the skill.

Managing Permissions and Access

Unity Catalog permissions determine who can work with a registered skill.

The required permissions depend on the operation. Creating a skill requires CREATE VOLUME on the parent schema. Uploading files requires WRITE VOLUME and READ VOLUME on the skill. Finalization requires READ VOLUME.

Listing and reading a skill's metadata require suitable access, such as READ VOLUME, READ METADATA, or MANAGE. Updating or deleting a skill requires MANAGE.

The caller also needs USE CATALOG and USE SCHEMA on the parent resources.

For example, an administrator can grant a data team permission to read and download a skill bundle:

databricks grants update skill main.default.sql_review \
  --json '{
    "changes": [
      {
        "principal": "data-team",
        "add": ["READ_VOLUME"]
      }
    ]
  }'

Replace data-team with the actual group or principal in your workspace. Grant only the permissions the team needs. Users who only need to load a skill should not automatically receive permission to modify or delete it.

A registered skill can contain instructions that affect how an agent behaves. Review changes before granting broad access, especially when the skill is used by agents that can query data or call tools.

Which Developer Tools Are Supported?

The Skills API is available through several Databricks development tools, although each has its own minimum version.

Tool	Minimum supported version
Databricks CLI	1.20.0
Python SDK	`databricks-sdk` 0.142.0
Go SDK	`databricks-sdk-go` 0.184.0
Go Modular SDK	`github.com/databricks/sdk-go/aigateway` 0.1.0
Java SDK	`databricks-sdk-java` 0.157.0
JavaScript SDK	`@databricks/sdk-aigateway` 0.23.0

The REST API has no corresponding client-version requirement, but callers must still follow the API contract and authenticate correctly.

The API supports create, read, update, list, delete, and finalize operations. File uploads use the Files API. These are separate calls, so a deployment script should handle failures at each stage instead of assuming that creating a resource completes the whole workflow.

Skills currently do not have Terraform or Declarative Automation Bundles resources. Teams that use those tools for infrastructure management will need to account for this limitation in their deployment process.

Advantages and Disadvantages

Advantages

Reusable instructions: Teams can share a common skill instead of copying prompts between projects.
Programmatic management: The API and SDKs make it possible to automate skill creation, publication, and cleanup.
Access control: Unity Catalog permissions let administrators decide who can read, update, or delete a skill.
Clear resource identity: Each skill has a managed name that applications and automation can reference.
Multiple language options: Teams can use supported Python, Go, Java, or JavaScript clients.

Disadvantages

Beta status: The API is still in Beta, so teams should review current behavior and limitations before making it part of a critical workflow.
Several deployment steps: Creating a resource, uploading files, and finalizing it are separate operations.
Permissions require planning: Missing catalog, schema, volume, or management privileges can cause individual steps to fail.
No Terraform resource: Teams using infrastructure-as-code workflows cannot currently manage skills through a dedicated Terraform resource.
Agent compatibility still matters: Registering a skill does not guarantee that every coding agent or application can load it.

Best Practices for Production Teams

Keep each skill focused. A skill that handles one clear task is easier to test and maintain than a large file containing unrelated instructions.

Use version control for skill files. Store SKILL.md and supporting files in a repository, review changes through pull requests, and publish only approved versions.

Validate before finalizing. Check the frontmatter, instruction quality, and supporting files before uploading a new version. Then test the skill with the agent that will use it.

Separate publishing from access management. Developers responsible for editing a skill do not necessarily need to grant access to every user. Keep those responsibilities clear.

Handle failed API calls. A script should detect upload and finalization errors and avoid marking a skill as ready when the process is incomplete.

Use conditional updates where needed. When multiple administrators might edit the same resource, use the current etag to prevent an update from silently overwriting a newer change.

Conclusion

The Unity Gateway Skills API gives Databricks teams a way to manage reusable AI agent instructions as governed resources in Unity Catalog. Developers can create a skill, upload its files, finalize it, and control access through the REST API or supported SDKs.

The practical benefit is easier maintenance of shared instructions across agents and teams. The API does not remove the need to review skill content, test agent behavior, or manage permissions carefully.

Because the feature is in Beta, start with a non-critical skill and automate the complete lifecycle before using it across a large set of agents. That will help your team understand the API's behavior and establish a repeatable publishing process.