Tutorial: Discover and use 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.
Connect your coding agent to the skills your team published to Unity Catalog, then discover and use them from any agent session. Everyone points at the same governed schemas, so you reuse what exists instead of rebuilding it. To author and publish your own skills, see Create and share Unity Gateway Skills.
You can use a skill for one session, download it to disk for every session, or load it live from the Databricks Skills MCP server to get the latest published version.
Requirements
- A Unity Catalog-enabled Databricks workspace, and your workspace URL (for example,
https://my-company.cloud.databricks.com). - Python 3.12+ and uv on your machine (used to install the Unity Gateway CLI).
- An MCP-capable coding agent (MCP, the Model Context Protocol, is the open standard agents use to connect to servers).
USE CATALOG,USE SCHEMA, andREAD VOLUMEon the skills you want to use. Your Databricks admin grants these. If a command fails with a permission error, ask your admin for these on your team's schema.
Connect to the Databricks skill registry
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 registers the Databricks Skills MCP server (databricks-skill-registry) that your agent uses to list, load, and download skills.
Have your agent install and connect the Unity Gateway CLI for you:
Install the :re[UG] 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.
If no browser can open, install the Databricks CLI, run `databricks configure --host https://<workspace-host>` to create a profile named DEFAULT, then run `ug configure --agents <your-agent> --profile DEFAULT --use-pat` in a terminal instead.
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.
On a headless machine or in CI, where no browser can open, run ug configure --agents <your-agent> --profile DEFAULT --use-pat in a terminal to sign in with a personal access token from an existing Databricks CLI configuration profile instead. This path requires the Databricks CLI, which you can install. To create the profile, run databricks configure --host <workspace-url> first. See the ug CLI reference.
Discover skills
Ask your agent in plain language. The databricks-skill-registry MCP server returns only the skills you have permission to use.
List a schema to see every skill in it. The examples on this page use acme.sql_skills; replace it with your own <catalog>.<schema>.
List the Databricks skills in acme.sql_skills.
The agent reports which skills you can access in the schema. If the list is empty, either you don't have the required privileges on the schema or no one has published skills there. To publish one, see Create and share Unity Gateway Skills.
Use skills
Choose how to use a skill you found:
Method | Persists across sessions | Works offline | Gets updates | Best for |
|---|---|---|---|---|
No | No | Loads the current version | A single task | |
Yes | Yes | Download again for a newer version | Skills you use regularly | |
Yes | No | Loads the latest published version | A large set of skills that changes often |
Load a skill for one session
To use a skill for this session only, ask your agent to use it by name:
Use acme.sql_skills.databricks-sql-guide to review this query.
The agent reads the skill's instructions and any supporting files it needs for the task.
Download a skill
To keep a skill available in every session, download it to your local skills folders.
Ask your agent:
Download acme.sql_skills.databricks-sql-guide with the :re[UG] CLI so I have it every session:
run ug skills add --names acme.sql_skills.databricks-sql-guide.
Or run the command yourself:
ug skills add --names acme.sql_skills.databricks-sql-guide # one skill
ug skills add --names acme.sql_skills.databricks-sql-guide,acme.sql_skills.dbt-conventions # several skills
ug skills add --location acme.sql_skills # a whole schema
--names takes a comma-separated list of fully-qualified <catalog>.<schema>.<name> skills. To download every skill in a schema instead, pass that <catalog>.<schema> to --location.
Restart your agent afterward (ug <your-agent>). Downloaded skills live in your local skills folders (.claude/skills/ and .agents/skills/) and load every session. To test the downloaded skill, ask:
Using our SQL guide skill, write a query on samples.nyctaxi.trips for average fare by trip distance.
samples.nyctaxi.trips exists in every workspace, so this works with no setup.
A downloaded skill is a point-in-time copy. Download it again for a newer version, or load the schema live to get the latest.
Load a schema live
Scope the Databricks Skills MCP server to a schema so your agent can read its skills on demand.
Ask your agent:
Load the skills in acme.sql_skills live so I always get the latest version:
run ug skills add --location acme.sql_skills --via mcp.
Or run the command yourself:
ug skills add --location acme.sql_skills --via mcp
Restart your agent afterward (ug <your-agent>) so it connects to the schema. When a task matches a skill's description, the agent can load it on demand; publish a new version and everyone on the connection gets it immediately. This pairs well with a schema that a central team keeps in sync from Git.
Live loading works on a whole schema at a time. You can't scope it to a single skill. To use just one skill without loading its whole schema, load it for one session instead.
For supported agents, the Unity Gateway CLI configures the connection to load live skills automatically. Other agents may expose their own "always load" (or equivalent) setting that you'll need to turn on.
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.
Troubleshooting
- Your agent stops working after
ug configureruns. Start or restart your agent (ug <your-agent>). The command changes how your agent signs in to its model.
Next steps
- Skills support in Unity Gateway for the concepts behind this tutorial.
- Create and share Unity Gateway Skills to publish your own.
- Govern skills for the privileges that control who can read and share skills.