Tutorial: Create and share Unity Gateway Skills

Important

This feature is in Beta. To use it, a workspace admin must turn on Unity Gateway skills in Genie from the Previews page. See Manage Azure Databricks previews.

Create a skill with your coding agent, publish it to Unity Catalog, and share it with teammates. If you already manage skills in GitHub, publish them with a GitHub Action. For upstream repositories where you cannot add a workflow, sync them with a notebook. To create and manage skills with the REST API, the Databricks CLI, or the SDKs instead, see Skills API and SDK reference.

Requirements

Create and publish a skill interactively

To draft and publish a skill from your coding agent, install Python 3.12+ and uv, then follow these steps. You need a coding agent that supports the Model Context Protocol (MCP), the standard agents use to connect to tools. You can skip these CLI setup steps when publishing an existing skill from GitHub.

Install and connect the Unity Gateway CLI

Install the Unity Gateway CLI and use it to connect your coding agent to your Azure Databricks workspace's skill registry.

The Unity Gateway CLI signs you in to your workspace and registers the Azure Databricks Skills MCP server (databricks-skill-registry) that your agent uses to create and update skills.

Tip

Have your agent install and connect the Unity Gateway CLI for you:

Install the Unity Gateway CLI from its Git source and connect my coding agent to Databricks:

1. Run: uv tool install git+https://github.com/databricks/unity-gateway
2. Run: ug configure --agents <your-agent> --workspaces https://<workspace-host>
3. Run: ug skills

Use <your-agent> = my coding agent (claude, codex, gemini, opencode, or copilot) and
<workspace-host> = my workspace URL host (for example, my-company.cloud.databricks.com).
A browser will open during step 2 for me to sign in.

To do it yourself, run the same commands in your terminal:

uv tool install git+https://github.com/databricks/unity-gateway
ug configure --agents <your-agent> --workspaces https://<workspace-host>
ug skills

Replace <your-agent> with the name of the coding agent you use (for example, claude, codex, gemini, opencode, or copilot), and <workspace-host> with your workspace URL host. A browser opens during ug configure for you to sign in. Restart your agent afterward (ug <your-agent>) so it loads the new tools.

Develop a skill locally

A skill is a folder: a SKILL.md file with instructions, plus any supporting files the agent should read. You can ask your coding agent or Genie Code to draft and refine these files. For a skill authored in Genie Code, download its folder locally, then publish it with the connected coding agent.

In this tutorial you build a databricks-sql-guide skill: your team's conventions for writing Azure Databricks SQL, so every query an agent writes follows the same standards.

Tip

Have your agent draft the skill for you:

Draft a databricks-sql-guide skill in a local folder ./databricks-sql-guide. Create a SKILL.md
with our Databricks SQL conventions: snake_case naming, named CTEs over nested subqueries,
filter on partition columns, and avoid SELECT *. Give it a specific description that says what
it covers and when to use it.

The agent writes a folder like this:

databricks-sql-guide/
└── SKILL.md

A minimal SKILL.md has YAML frontmatter and instructions:

---
name: databricks-sql-guide
description: Databricks SQL conventions for writing queries — use for any Databricks SQL authoring or review.
---

# Databricks SQL guide

- Use snake_case for table, column, and CTE names.
- Prefer named CTEs over nested subqueries.
- Always filter on partition columns when they exist.
- Never use `SELECT *`; list columns explicitly.

The description matters most: it is what agents match against when deciding whether to use a skill, so make it specific about what the skill covers and when to reach for it. Review the draft and refine it until it captures your conventions.

Publish the skill to Unity Catalog

Publishing uploads your local folder to a Unity Catalog schema as a governed skill. You become the skill's owner, and it is private to you until you share it.

Tip

Have your agent publish it for you:

Publish my ./databricks-sql-guide folder to the acme.sql_skills schema in Databricks.

The agent calls the create_skill MCP tool to upload the folder and register the skill.

To change the skill later, edit the local folder and prompt the agent to update it from your folder. The agent calls update_skill on the same server.

Share your skill

A published skill is private until you grant access. Skills that the GitHub Action creates are owned by its service principal. The skill owner or a principal with MANAGE shares them. You share a skill from Catalog Explorer by granting READ VOLUME.

Permissions required: you must be the skill's owner or have MANAGE on it.

  1. In your Azure Databricks workspace, click Data icon. Catalog.
  2. Navigate to the schema that holds the skill, then select the skill.
  3. Go to the Permissions tab.
  4. Click Grant.
  5. Enter the email address for a user or the name of a group.
  6. Select READ VOLUME.
  7. Click OK.

Recipients also need USE CATALOG on acme and USE SCHEMA on sql_skills to reach the skill. Grant those on the catalog and schema the same way. To revoke access later, select the grant on the Permissions tab and click Revoke.

Sharing a skill grants access to the live skill. The recipient's agent reads it under the skill's grants and audit, so there is nothing to keep in sync. For the full privilege model, see Govern skills.

After you share a skill, teammates find and use it from their own agents. See Discover and use Unity Gateway Skills.

Publish skills from your GitHub repository

If you already use GitHub to manage your skills, use the Unity Gateway skill publishing action to create and update their Unity Catalog counterparts. You need permission to add a workflow to the repository that holds your skills. The workflow publishes from a GitHub runner after changes merge to your publishing branch. You do not need a Azure Databricks notebook, cluster, or scheduled job.

For an upstream repository where you cannot configure workflows, see Advanced: Sync an upstream Git repository.

Set up publishing access

A Azure Databricks admin and a GitHub repository admin complete this setup:

  1. Create or select a publishing service principal, assign it to the target workspace, and grant it the catalog and schema privileges in Requirements on every destination schema. For existing skills it updates, also grant READ VOLUME and WRITE VOLUME. New skills are owned by the publishing principal, so grant MANAGE on every destination schema to the users or group who share the skills. They also need USE CATALOG and USE SCHEMA on the parent catalog and schema. The schema grant applies to its child skills. See Privilege inheritance.
  2. Create a GitHub environment named production in your skills repository. Restrict its deployment branches to main, or the branch you intend to publish from.
  3. Configure GitHub workload identity federation on the publishing service principal. Match the exact OpenID Connect (OIDC) subject for your skills repository and the production environment. GitHub issues a short-lived identity token that the Azure Databricks SDK exchanges for a Azure Databricks access token, so no Azure Databricks client secret is stored in GitHub. Newer repositories can include numeric organization and repository IDs in their subject. Follow the federation guide to configure the subject and audience for your repository.
  4. In Settings > Environments > production > Environment variables, add DATABRICKS_HOST with your workspace base URL and DATABRICKS_CLIENT_ID with the service principal's application ID. Neither value is secret.
  5. Choose a Linux runner that can reach your workspace. The example uses a GitHub-hosted runner. A workspace with private networking or IP access lists might require a runner on your network.

For detailed administrator instructions and an OAuth machine-to-machine alternative, see the action's authentication guide.

The examples reference the action at main, so they pick up its latest updates. For reproducible workflows, replace main in the action reference with a reviewed commit SHA from the Unity Gateway repository. You do not need to install the Unity Gateway CLI.

Add the workflow

  1. Add your skills to the repository. Each immediate child folder of skills that contains SKILL.md becomes a skill. Supporting files in each folder are included:

    skills/
├── sql-guide/
│   ├── SKILL.md
│   └── references/conventions.md
└── code-review/
    └── SKILL.md

    The folder basename determines the Unity Catalog skill identifier when using skills-directory: skills/sql-guide becomes acme.team_skills.sql-guide. The name in SKILL.md remains required skill metadata, but the action does not use it to choose the Unity Catalog identifier. For clarity, use name: sql-guide in this example. An explicit mapping uses its target value instead of the folder basename.

    For skill contents and frontmatter, see Develop a skill locally.

  2. Create .github/workflows/publish-skills.yml with the following content. Replace acme.team_skills with your existing catalog and schema. If your publishing branch or source folder differs, update the branch and path filters as well.

    name: Publish skills to Databricks
on:
  push:
    branches: [main]
    paths: ['skills/**', '.github/workflows/publish-skills.yml']
  workflow_dispatch:
    inputs:
      dry_run:
        description: Validate folders without publishing
        type: boolean
        default: true
permissions:
  contents: read
  id-token: write
concurrency:
  group: publish-uc-skills
  cancel-in-progress: false
jobs:
  publish:
    runs-on: ubuntu-latest
    environment: production
    env:
      DATABRICKS_AUTH_TYPE: github-oidc
      DATABRICKS_HOST: ${{ vars.DATABRICKS_HOST }}
      DATABRICKS_CLIENT_ID: ${{ vars.DATABRICKS_CLIENT_ID }}
    steps:
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
        with:
          persist-credentials: false
      - uses: databricks/unity-gateway/actions/publish-skills@main
        with:
          skills-directory: skills
          target-schema: acme.team_skills
          dry-run: ${{ github.event_name == 'workflow_dispatch' && inputs.dry_run || false }}

    This maps skills/sql-guide to acme.team_skills.sql-guide and skills/code-review to acme.team_skills.code-review.

  3. Merge the workflow and skills to main. This triggers the first publication. To validate source files in pull requests before publishing, add the action's validation workflow. Dry runs validate local skill folders without contacting Azure Databricks. They do not test authentication, network access, or permissions. Because the production environment allows only main, run manual dry runs from main and use the validation workflow to check other branches.

  4. In GitHub, open Actions > Publish skills to Databricks and check the run logs. In Azure Databricks, open Catalog Explorer and confirm that the skills appear in your target schema. After the workflow is on main, you can also select Run workflow and leave Validate folders without publishing selected for a dry run, or clear it to publish.

Subsequent merges that change the skills folder publish updates to the same skills. Existing ownership and grants are preserved. After publishing, a skill owner or a principal with MANAGE grants teammates access. See Share your skill. The action does not grant consumer access. Consumers can load the schema's skills live.

Removing a source folder does not delete its Unity Catalog skill, and renaming a mapping target creates a new skill and keeps the old one. By default, if a mapped skill contains remote files absent from the local folder, publication of that skill fails before uploading changes and leaves those files in place. Set prune-files: 'true' to remove remote files absent from each published folder. Skill updates are not atomic, so inspect failed runs before retrying.

Map selected folders to skill names

For custom names, folders outside skills, or multiple destination schemas, add a skills.yaml mapping file at the repository root:

version: 1
skills:
  - path: skills/sql-guide
    target: acme.team_skills.sql-guide
  - path: .claude/skills/review
    target: acme.team_skills.code-review

Replace skills-directory and target-schema in the publishing step with mapping-file:

- uses: databricks/unity-gateway/actions/publish-skills@main
  with:
    mapping-file: skills.yaml
    dry-run: ${{ github.event_name == 'workflow_dispatch' && inputs.dry_run || false }}

Update the workflow's paths filter to include skills.yaml, each mapped source folder, and the workflow file. Grant the publishing principal access to every mapped destination. See the action examples for additional workflow configurations.

Advanced: Sync an upstream Git repository

Use the notebook approach when you cannot add a publishing workflow to the source repository, such as a third-party repository that your team consumes. You control the destination schema and the scheduled sync in your workspace. If you can configure GitHub Actions in the source repository, see Publish skills from your GitHub repository.

Import the following notebook into your Azure Databricks workspace, set the git_url, catalog, schema, and branch widgets (and git_credential_id for a private repo), then run it on a schedule. It clones the repo, creates new skills, and updates changed ones. It never deletes, so a skill removed from the repo stays in the schema until you drop it. It runs with your workspace credentials and publishes as you.

Sync a Git repo of skills to a Unity Catalog schema

Get notebook

Once a schema is kept in sync this way, consumers can load the whole schema live so their agents always get the latest published skills.

Reference

The Unity Gateway CLI is open source. For the full, current command reference, see the Unity Gateway CLI repository. The commands this tutorial uses appear inline in the steps above.

Skills tools (your agent calls these on the databricks-skill-registry MCP server once connected):

Tool Purpose
create_skill / update_skill / delete_skill Publish, update, or delete a skill

To share a skill, grant READ VOLUME on it in Catalog Explorer. See Share your skill.

Next steps

  • Last updated on