Tutorial: criar e compartilhar habilidades do Unity Catalog
Este tutorial é destinado a autores de habilidades e equipes centrais que desejam gerenciar habilidades como ativos governados do Unity Catalog. Você desenvolve uma habilidade localmente, publica-a em um esquema do Unity Catalog e a compartilha, para que o agente de qualquer colega de equipe possa usá-la sob as mesmas permissões e auditoria que governam o restante dos seus dados do Databricks.
Requisitos
- Um workspace do Databricks com o Unity Catalog habilitado e a URL do seu workspace (por exemplo,
https://my-company.cloud.databricks.com). - Python 3.12+ e uv na sua máquina (usado para instalar
ucode). - 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 SCHEMAeCREATE VOLUMEno esquema de destino. Seu administrador do Databricks concede esses privilégios. Consulte Govern skills para o modelo completo.
Instalar e conectar o ucode
Instale o ucode e use-o para conectar seu agente de codificação ao registro de habilidades do seu workspace do Databricks.
O ucode conecta você ao seu Workspace e faz o registro do servidor MCP de Habilidades do Databricks (databricks-skill-registry) que seu agente usa para criar e atualizar habilidades.
Peça ao seu agente para instalar e conectar o ucode para você:
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.
Para fazer isso você mesmo, execute os mesmos comandos no seu terminal:
uv tool install git+https://github.com/databricks/ucode
ucode configure --agents <your-agent> --workspaces https://<workspace-host>
ucode 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 ucode configure para você fazer login. Reinicie seu agente depois (ucode <your-agent>) para que ele carregue as novas ferramentas.
Desenvolver uma habilidade localmente
Uma skill é apenas uma pasta: um arquivo SKILL.md com instruções, além de quaisquer arquivos de suporte que o agente deva ler.
Neste tutorial, você cria uma habilidade databricks-sql-guide: as convenções da sua equipe para escrever Databricks SQL, para que cada query que um agente escreve siga os mesmos padrões.
Peça ao seu agente para redigir a habilidade para você:
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.
O agente grava uma pasta como esta:
databricks-sql-guide/
└── SKILL.md
Uma SKILL.md mínima tem front matter YAML e instruções:
---
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.
O description é o que mais importa: é com ele que os agentes fazem a correspondência ao decidir se devem usar uma habilidade, portanto, seja específico sobre o que a habilidade cobre e quando recorrer a ela. Revise o rascunho e refine-o até que ele capture suas convenções.
Publicar a habilidade no Unity Catalog
A publicação faz upload da sua pasta local para um esquema do Unity Catalog como uma habilidade governada. Você se torna o proprietário da habilidade, e ela é privada para você até que você a compartilhe.
Peça ao seu agente para publicá-lo para você:
Publish my ./databricks-sql-guide folder to the acme.sql_skills schema in Databricks.
O agente chama a ferramenta MCP create_skill para fazer upload da pasta e registrar a skill.
Para alterar a habilidade posteriormente, edite a pasta local e solicite que o agente a atualize a partir da sua pasta. O agente chama update_skill no mesmo servidor.
Compartilhe sua skill
Uma skill publicada é privada para você até que você conceda acesso. Você o compartilha a partir do Explorador de Catálogos concedendo READ VOLUME.
Permissões necessárias: você deve ser o proprietário da habilidade ou ter MANAGE nela.
- No seu workspace do Databricks, clique em
Catálogo . - Navegue até o esquema que contém a habilidade e, em seguida, selecione a habilidade.
- Vá para a tab Permissões.
- Clique em Conceder .
- Insira o endereço de email de um usuário ou o nome de um grupo.
- Selecione
READ VOLUME. - Clique em OK .
Os destinatários também precisam de USE CATALOG em acme e USE SCHEMA em sql_skills para acessar a skill. Conceda-os no catálogo e no esquema da mesma maneira. Para revogar o acesso posteriormente, selecione a concessão na tab Permissions e clique em Revogar .
O compartilhamento de uma skill é uma concessão, não uma cópia: o agente do destinatário lê a skill ativa sob suas concessões e auditoria, portanto, não há nada para manter sincronizado. Para o modelo de privilégio completo, consulte Governar skills.
Uma vez compartilhado, os colegas de equipe encontram e usam sua skill a partir de seus próprios agentes. Consulte Descobrir e usar habilidades do Unity Catalog.
Sincronizar um repository de habilidades Git com um esquema do UC
Se sua equipe mantém skills em um repository Git, você pode publicá-las todas em um esquema automaticamente, para que o esquema rastreie uma branch do repo.
Importe o seguinte Notebook para o seu Databricks workspace, defina os widgets git_url, catalog, schema e branch (e git_credential_id para um repo privado) e, em seguida, execute-o em uma programar. Ele clona o repo, cria novas skills e atualiza as alteradas; ele nunca exclui, portanto, uma skill removida do repo permanece no esquema até que você a remova. Ele é executado com as credenciais do seu workspace e publica como você.
Sincronizar um repo Git de habilidades com um esquema do Unity Catalog
Uma vez que um esquema é mantido em sincronia desta forma, os consumidores podem carregar todo o esquema ao vivo para que seus agentes sempre obtenham as habilidades publicadas mais recentes.
Referência
ucode é de código aberto. Para a referência completa e atual de comandos, consulte o repository ucode. 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 |
|---|---|
| Publicar, atualizar ou excluir uma skill |
Para compartilhar uma habilidade, conceda READ VOLUME a ela no Explorador de Catálogos. Consulte Compartilhar sua habilidade.
Passos seguintes
- O que são as Skills do Unity Catalog para os conceitos por trás deste tutorial.
- Descubra e use as Habilidades do Unity Catalog para trazer habilidades publicadas para o seu agente.
- Governe habilidades para configurar esquemas governados e gerenciar o modelo de privilégios.