Tutorial: Create and share Unity Gateway Skills
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 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
- A Unity Catalog-enabled Databricks workspace, and your workspace URL (for example,
https://my-company.cloud.databricks.com). Creating and updating skills must be enabled for your workspace. Workspaces that use the compliance security profile block these operations. See Account and compliance considerations. - An existing schema in a standard Unity Catalog catalog with a managed storage location. See Set up a governed schema for skills.
- Python 3.12+ and uv on your machine (used to install the Unity Gateway CLI).
- The Databricks CLI, installed and authenticated, to run the commands returned by the Skills MCP server when publishing or updating a skill.
- An MCP-capable coding agent (MCP, the Model Context Protocol, is the open standard agents use to connect to servers).
USE CATALOGon the target catalog, andUSE SCHEMAandCREATE VOLUMEon the target schema. Your Databricks admin grants these. See Govern skills for the full model.- To share a skill, ownership of the skill or
MANAGEon it. As the publisher, you're its owner.
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 Databricks workspace's skill registry.
The Unity Gateway CLI signs you in to your workspace and connects your agent to the Databricks Skills MCP server (databricks-skill-registry). Your agent uses it to discover published skills and get the commands to create or update one.
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> --workspace 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 opens 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> --workspace 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 skill registry connection.
Authenticate the Databricks CLI to the same workspace before publishing. Use a configuration profile to keep the publishing commands pointed at that workspace:
databricks auth login --host https://<workspace-host> --profile <profile>
Use the same <workspace-host> as in ug configure. Add --profile <profile> to each Databricks CLI command returned by the Skills MCP server when you run it.
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 Databricks SQL, so every query an agent writes follows the same standards.
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.
Have your agent publish it for you:
Publish my ./databricks-sql-guide folder to the acme.sql_skills schema in Databricks.
Use the Skills MCP server to get the publishing steps, then run the
returned Databricks CLI commands locally with --profile <profile>.
Show me the commands before running them.
The Skills MCP server returns the Databricks CLI commands to create the skill, upload its folder, and finalize it. Your coding agent can run those commands locally, or you can review and run them yourself. The MCP server does not run the commands or upload the files.
To change the skill later, edit the local folder and ask your agent to update it. The server returns commands to upload and finalize the new version. If you deleted local files, ask your agent to compare the local folder with the published bundle and remove those files from the bundle before finalizing. Review the commands before running them.
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.
- In your Databricks workspace, click
Catalog.
- Navigate to the schema that holds the skill, then select the skill.
- Go to the Permissions tab.
- Click Grant.
- Enter the email address for a user or the name of a group.
- Select
READ VOLUME. - 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 within your metastore there is nothing to keep in sync. For the full privilege model, see Govern skills.
Grants reach principals on workspaces attached to the same Unity Catalog metastore. To share a skill with workspaces attached to other metastores or accounts, add it to a OpenSharing share, where recipients get read-only access to the skill, and your changes reach them automatically, or list it on Databricks Marketplace. Sharing skills using OpenSharing is in Beta.
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 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 Databricks admin and a GitHub repository admin complete this setup:
- 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 VOLUMEandWRITE VOLUME. New skills are owned by the publishing principal, so grantMANAGEon every destination schema to the users or group who share the skills. They also needUSE CATALOGandUSE SCHEMAon the parent catalog and schema. The schema grant applies to its child skills. See Privilege inheritance. - Create a GitHub environment named
productionin your skills repository. Restrict its deployment branches tomain, or the branch you intend to publish from. - Configure GitHub workload identity federation on the publishing service principal. Match the exact OpenID Connect (OIDC) subject for your skills repository and the
productionenvironment. GitHub issues a short-lived identity token that the Databricks SDK exchanges for a Databricks access token, so no 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. - In Settings > Environments > production > Environment variables, add
DATABRICKS_HOSTwith your workspace base URL andDATABRICKS_CLIENT_IDwith the service principal's application ID. Neither value is secret. - 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
-
Add your skills to the repository. Each immediate child folder of
skillsthat containsSKILL.mdbecomes a skill. Supporting files in each folder are included:Textskills/├── sql-guide/│ ├── SKILL.md│ └── references/conventions.md└── code-review/└── SKILL.mdThe folder basename determines the Unity Catalog skill identifier when using
skills-directory:skills/sql-guidebecomesacme.team_skills.sql-guide. ThenameinSKILL.mdremains required skill metadata, but the action does not use it to choose the Unity Catalog identifier. For clarity, usename: sql-guidein this example. An explicit mapping uses itstargetvalue instead of the folder basename.For skill contents and frontmatter, see Develop a skill locally.
-
Create
.github/workflows/publish-skills.ymlwith the following content. Replaceacme.team_skillswith your existing catalog and schema. If your publishing branch or source folder differs, update the branch and path filters as well.YAMLname: Publish skills to Databrickson:push:branches: [main]paths: ['skills/**', '.github/workflows/publish-skills.yml']workflow_dispatch:inputs:dry_run:description: Validate folders without publishingtype: booleandefault: truepermissions:contents: readid-token: writeconcurrency:group: publish-uc-skillscancel-in-progress: falsejobs:publish:runs-on: ubuntu-latestenvironment: productionenv:DATABRICKS_AUTH_TYPE: github-oidcDATABRICKS_HOST: ${{ vars.DATABRICKS_HOST }}DATABRICKS_CLIENT_ID: ${{ vars.DATABRICKS_CLIENT_ID }}steps:- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1with:persist-credentials: false- uses: databricks/unity-gateway/actions/publish-skills@mainwith:skills-directory: skillstarget-schema: acme.team_skillsdry-run: ${{ github.event_name == 'workflow_dispatch' && inputs.dry_run || false }}This maps
skills/sql-guidetoacme.team_skills.sql-guideandskills/code-reviewtoacme.team_skills.code-review. -
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 Databricks. They do not test authentication, network access, or permissions. Because theproductionenvironment allows onlymain, run manual dry runs frommainand use the validation workflow to check other branches. -
In GitHub, open Actions > Publish skills to Databricks and check the run logs. In 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 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
When a schema is kept in sync this way, consumers can load the whole schema live so their agents 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.
For the Skills MCP server's supported interfaces and client compatibility, see Access skills over MCP. To share a skill, grant READ VOLUME on it in Catalog Explorer. See Share your skill.
Next steps
- Skills support in Unity Gateway for the concepts behind this tutorial.
- Discover and use Unity Gateway Skills to bring published skills into your agent.
- Govern skills to set up governed schemas and manage the privilege model.
- Skills API and SDK reference to automate skill management with the REST API, the Databricks CLI, and the SDKs.