Tutorial: descobrir e usar Skills do Unity Gateway
Beta
Este recurso está na Beta. Para usá-lo, um administrador do workspace deve ativar Habilidades do Unity Gateway no Genie na página Pré-visualizações . Consulte Gerenciar prévias do Databricks.
Conecte seu agente de codificação às habilidades que sua equipe publicou no Unity Catalog e, em seguida, descubra-as e use-as a partir de qualquer sessão de agente. Todos apontam para os mesmos esquemas governados, portanto, você reutiliza o que já existe em vez de reconstruí-lo. Para criar e publicar suas próprias habilidades, consulte Criar e compartilhar habilidades do Unity Gateway.
Você pode usar uma skill para uma sessão, fazer download dela para o disco para cada sessão ou carregá-la ao vivo do servidor MCP do Databricks Skills para obter a versão publicada mais recente.
Requisitos
- Um workspace do Databricks com o Unity Catalog habilitado e a sua URL do workspace (por exemplo,
https://my-company.cloud.databricks.com). - Python 3.12+ e uv em sua máquina (usado para instalar a CLI do Unity Gateway).
- Um agente de codificação com capacidade MCP (MCP, o Model Context Protocol, é o padrão aberto que os agentes usam para se conectar aos servidores).
USE CATALOG,USE SCHEMAeREAD VOLUMEnas habilidades que você deseja usar. O seu administrador do Databricks concede estes. Se um comando falhar com um erro de permissão, solicite ao seu administrador estas permissões no esquema da sua equipe.
Conectar ao registro de habilidades do Databricks
Instale a Unity Gateway CLI e use-a para conectar seu agente de codificação ao registro de habilidades do seu workspace do Databricks.
A CLI do Unity Gateway autentica você no seu workspace e registra o Databricks Skills MCP server (databricks-skill-registry) que seu agente usa para listar, carregar e fazer download de skills.
Peça ao seu agente para instalar e conectar a CLI do Unity Gateway para você:
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.
Para fazer isso você mesmo, execute os mesmos comandos no seu terminal:
uv tool install git+https://github.com/databricks/unity-gateway
ug configure --agents <your-agent> --workspace https://<workspace-host>
ug skills
Substitua <your-agent> pelo nome do agente de codificação que você usa (por exemplo, claude, codex, gemini, opencode ou copilot) e <workspace-host> pelo host da URL do seu workspace. Um navegador abre durante ug configure para você fazer login. Reinicie seu agente depois (ug <your-agent>) para que ele carregue a conexão do registro de habilidades.
Em uma máquina headless ou em CI, onde nenhum navegador pode abrir, faça a execução de ug configure --agents <your-agent> --profile DEFAULT --use-pat em um terminal para entrar com um access token pessoal de um perfil de configuração da CLI do Databricks existente. Este caminho requer a CLI do Databricks, que você pode instalar. Para criar o perfil, primeiro execução databricks configure --host <workspace-url>. Consulte a referência da CLI ug.
Descobrir habilidades
Peça ao seu agente em linguagem simples. O servidor MCP databricks-skill-registry retorna apenas as skills que você tem permissão para usar.
Liste um esquema para ver todas as habilidades nele. Os exemplos nesta página usam acme.sql_skills; substitua-o pelo seu próprio <catalog>.<schema>.
List the Databricks skills in acme.sql_skills.
O agente informa quais habilidades você pode acessar no esquema. Se a lista estiver vazia, você não terá os privilégios necessários no esquema ou ninguém publicou habilidades lá. Para publicar uma, consulte Criar e compartilhar Habilidades do Unity Gateway.
Usar habilidades
Escolha como usar uma habilidade que você encontrou:
Método | Persiste entre sessões | Funciona offline | Obtém atualizações | Melhor para |
|---|---|---|---|---|
Não | Não | Carrega a versão atual | Uma única tarefa | |
Sim | Sim | Faça o download novamente para uma versão mais recente | Habilidades que você usa regularmente | |
Sim | Não | Carrega a versão publicada mais recente | Um grande conjunto de habilidades que muda com frequência |
Carregar uma skill para uma sessão
Para usar uma skill apenas para esta sessão, peça ao seu agente para usá-la pelo nome:
Use acme.sql_skills.databricks-sql-guide to review this query.
O agente lê as instruções da habilidade e quaisquer arquivos de suporte necessários para a tarefa.
Fazer download de uma skill
Para manter uma habilidade disponível em todas as sessões, faça o download dela para suas pastas de habilidades locais.
Pergunte ao seu agente:
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.
Ou execução o comando você mesmo:
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 aceita uma lista separada por vírgulas de competências de <catalog>.<schema>.<name> totalmente qualificadas. To download every skill in a schema instead, pass that <catalog>.<schema> to --location.
Reinicie seu agente depois (ug <your-agent>). As habilidades download residem nas suas pastas de habilidades locais (.claude/skills/ e .agents/skills/) e carregam a cada sessão. Para testar a habilidade download, pergunte:
Using our SQL guide skill, write a query on samples.nyctaxi.trips for average fare by trip distance.
samples.nyctaxi.trips existe em todos os workspaces, portanto isso funciona sem configuração.
Uma skill download é uma cópia pontual. Download novamente para obter uma versão mais recente ou carregue o esquema ao vivo para obter o mais recente.
Carregar um esquema ao vivo
Defina o escopo do servidor MCP de habilidades do Databricks para um esquema para que seu agente possa ler suas habilidades sob demanda.
Pergunte ao seu agente:
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.
Ou execução o comando você mesmo:
ug skills add --location acme.sql_skills --via mcp
Reinicie seu agente depois (ug <your-agent>) para que ele se conecte ao esquema. Quando uma tarefa corresponde à descrição de uma skill, o agente pode carregá-la sob demanda; publique uma nova versão e todos na conexão a recebem imediatamente. Isso combina bem com um esquema que uma equipe central mantém em sincronia a partir do Git.
O carregamento ao vivo funciona em todo um esquema de uma só vez. Você não pode escopá-lo para uma única skill. Para usar apenas uma skill sem carregar seu esquema inteiro, carregue-a para uma sessão em vez disso.
Para agentes compatíveis, a CLI do Unity Gateway configura a conexão para carregar habilidades ao vivo automaticamente. Outros agentes podem expor sua própria configuração “carregar sempre” (ou equivalente) que você precisará ativar.
Referência
A CLI do Unity Gateway é de código aberto. Para a referência completa e atual de comandos, consulte o repository da CLI do Unity Gateway. Os comandos que este tutorial usa aparecem em linha nos passos acima.
Para interfaces compatíveis com o servidor MCP Skills e compatibilidade com clientes, consulte Acessar skills via MCP.
Solução de problemas
- Seu agente para de funcionar após
ug configureexecuções. Começar ou reinicie seu agente (ug <your-agent>). O comando altera a forma como o agente faz login em seu modelo.
Passos seguintes
- Suporte a Skills no Unity Gateway para os conceitos por trás deste tutorial.
- Crie e compartilhe Skills do Unity Gateway para publicar as suas.
- Govern skills para os privilégios que controlam quem pode ler e compartilhar habilidades.