Tutorial: Create and share Unity Catalog Skills

This tutorial is for skill authors and central teams who want to manage skills as governed Unity Catalog assets. You develop a skill locally, publish it to a Unity Catalog schema, and share it, so any teammate's agent can use it under the same grants and audit that govern the rest of your Databricks data.

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 ucode).
• An MCP-capable coding agent (MCP, the Model Context Protocol, is the open standard agents use to connect to tools).
• USE SCHEMA and CREATE VOLUME on the target schema. Your Databricks admin grants these. See Govern skills for the full model.

Install and connect ucode

Install ucode and use it to connect your coding agent to your Databricks workspace's skill registry.

ucode signs you in to your workspace, and registers the Databricks Skills MCP server (databricks-skill-registry) that your agent uses to create and update skills.

prompt

Have your agent install and connect ucode for you:

Install ucode from its Git source and connect my coding agent to Databricks:

1. Run: uv tool install git+https://github.com/databricks/ucode
2. Run: ucode configure --agents <your-agent> --workspaces https://<workspace-host>
3. Run: ucode configure 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:

Bash

uv tool install git+https://github.com/databricks/ucode
ucode configure --agents <your-agent> --workspaces https://<workspace-host>
ucode configure 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 ucode configure for you to sign in. Restart your agent afterward (ucode <your-agent>) so it loads the new tools.

Develop a skill locally

A skill is just a folder: a SKILL.md file with instructions, plus any supporting files the agent should read.

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.

prompt

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:

Markdown

---
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.

prompt

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 to you until you grant access. You share it from Catalog Explorer by granting READ VOLUME.

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

1. In your Databricks workspace, click 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 is a grant, not a copy: the recipient's agent reads the live skill under your grants and audit, so there is nothing to keep in sync. For the full privilege model, see Govern skills.

Once shared, teammates find and use your skill from their own agents. See Discover and use Unity Catalog Skills.

Sync a Git skill repository to a UC schema

If your team keeps skills in a Git repository, you can publish them all to a schema automatically, so the schema tracks a branch of the repo.

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

Open notebook in new tabOpen in Databricks

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

ucode is open source. For the full, current command reference, see the ucode 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

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

• What are Unity Catalog Skills for the concepts behind this tutorial.
• Discover and use Unity Catalog Skills to bring published skills into your agent.
• Govern skills to set up governed schemas and manage the privilege model.