Tutorial: descobrir e usar Skills do Unity Gateway
Beta
Esse recurso está na versão Beta. Os administradores da conta podem gerenciar o acesso a esse recurso na página Previews do console da conta. Consulte Gerenciar prévias em nível de conta.
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ê usa uma skill de duas maneiras: faça o download para o disco para que ela seja carregada em todas as sessões ou carregue-a ao vivo a partir do servidor MCP do Databricks Skills para obter sempre 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 compatível com MCP (MCP, o Model Context Protocol, é o padrão aberto que os agentes usam para se conectar a ferramentas).
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> --workspaces https://<workspace-host>
3. Run: ug 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.
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> --workspaces https://<workspace-host>
ug configure 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 é aberto durante ug configure para você fazer login. Reinicie seu agente depois (ug <your-agent>) para que ele carregue as novas ferramentas.
Descobrir habilidades
Peça ao seu agente em linguagem simples; ele chama a ferramenta correspondente no servidor MCP databricks-skill-registry. Você só vê as habilidades que tem permissão para usar.
Liste um esquema para ver todas as skills nele:
List the Databricks skills in acme.sql_skills.
O agente chama a ferramenta MCP list_skills e relata o que o esquema contém.
Usar habilidades
Há três maneiras de usar uma habilidade que você encontrou:
- Carregar uma habilidade uma vez : apenas para esta sessão. Nada está salvo. Ideal para uma execução única.
- download uma habilidade : para cada sessão. Faz download para o disco para que seja carregado automaticamente a cada sessão, e funciona offline. Melhor para o punhado que você usa diariamente. As cópias são pontuais; faça o download novamente para obter atualizações.
- Carregar um esquema ao vivo : sempre o mais recente. Define o escopo do servidor MCP para um esquema inteiro, para que todas as skills nele permaneçam disponíveis e atuais, sem nada armazenado localmente. Ideal para um conjunto grande e de mudança rápida, mas requer uma conexão.
Em cada caso, o prompt é o que você solicita ao seu agente, seguido pela ferramenta que ele chama ou pelo comando que ele execução.
Carregar uma habilidade uma vez
Use acme.sql_skills.databricks-sql-guide to review this query.
O agente chama a ferramenta MCP load_skill para carregar as instruções da habilidade no contexto, e get_skill_files se a habilidade agrupar arquivos de suporte.
Fazer download de uma skill
Download acme.sql_skills.databricks-sql-guide with the :re[UG] CLI so I have it every session:
run ug configure skills --location acme.sql_skills --skill databricks-sql-guide.
ug configure skills --location acme.sql_skills --skill databricks-sql-guide # one skill
ug configure skills --location acme.sql_skills --skill databricks-sql-guide,dbt-conventions # several skills
ug configure skills --location acme.sql_skills # a whole schema
--location é o esquema que contém as habilidades; --skill restringe o download a uma lista separada por vírgulas de nomes de habilidades dentro dele. Omita --skill para download todas as habilidades no esquema.
Reinicie seu agente posteriormente (ug <your-agent>). As habilidades baixadas residem em suas pastas de habilidades locais (.claude/skills/ e .agents/skills/) e são carregadas a cada sessão. Tente um sem nomear um comando; o agente associa a tarefa à skill e a segue:
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 baixada é uma cópia pontual. Execute novamente o download para uma versão mais recente ou carregue o esquema ao vivo (abaixo) para obter sempre a versão mais recente.
Carregar um esquema ao vivo (opcional)
Define o escopo do servidor MCP de Skills da Databricks para um esquema, de modo que cada skill nele seja exposta como uma ferramenta ativa .
Load the skills in acme.sql_skills live so I always get the latest version:
run ug configure skills --location acme.sql_skills --mcp.
ug configure skills --location acme.sql_skills --mcp
Reinicie seu agente posteriormente (ug <your-agent>) para que as habilidades do esquema sejam carregadas. Cada habilidade em acme.sql_skills aparece então como uma ferramenta ativa chamada skill_acme.sql_skills.<skill>. Quando uma tarefa corresponde à descrição de uma habilidade, o agente a carrega sob demanda; publique uma nova versão e todos na conexão a receberão imediatamente. Isso combina bem com um esquema que uma equipe central mantém sincronizado a partir do Git.
O carregamento ao vivo funciona em um esquema inteiro de cada vez. Não é possível restringir o escopo a uma única skill. Para usar apenas uma skill sem carregar todo o seu esquema, carregue-a para uma execução única.
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.
Ferramentas de habilidades (seu agente as chama no servidor MCP databricks-skill-registry após a conexão):
Ferramenta | Propósito |
|---|---|
| Liste as habilidades em um esquema |
| Carregar as instruções de uma habilidade na sessão atual |
| Obter arquivos agrupados específicos de uma habilidade |
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.