Pular para o conteúdo principal

Tutorial: criar e compartilhar Skills do Unity Gateway

info

Beta

Esse recurso está em 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.

Crie uma habilidade com seu agente de codificação, publique-a no Unity Catalog e compartilhe-a com seus colegas de equipe. Se você já gerencia habilidades no GitHub, publique-as com um GitHub Action. Para repository upstream onde você não pode adicionar um fluxo de trabalho, sincronize-os com um notebook. Para criar e gerenciar habilidades com a API REST, a CLI do Databricks ou os SDKs, consulte Referência de API e SDK de habilidades.

Requisitos​

  • Um workspace do Databricks habilitado para Unity Catalog e sua URL do workspace (por exemplo, https://my-company.cloud.databricks.com). A criação e atualização de habilidades devem estar habilitadas para o seu workspace. Workspace que usam o perfil de segurança de compliance bloqueiam essas operações. Consulte Considerações sobre account e compliance.
  • Um esquema existente em um catálogo do Unity Catalog padrão com um local de armazenamento gerenciado. Veja Configurar um esquema governado para habilidades.
  • Python 3.12+ e uv na sua máquina (usado para instalar a CLI do Unity Gateway).
  • A CLI do Databricks, instalada e autenticada, para execução dos comandos retornados pelo servidor MCP de Habilidades ao publicar ou atualizar uma habilidade.
  • Um agente de codificação compatível com MCP (MCP, o Protocolo de Contexto do Modelo, é o padrão aberto que os agentes usam para se conectar aos servidores).
  • USE CATALOG no catálogo de destino e USE SCHEMA e CREATE VOLUME no esquema de destino. O administrador do Databricks concede isso. Consulte Gerenciar habilidades para o modelo completo.
  • Para compartilhar uma habilidade, propriedade da habilidade ou MANAGE sobre ela. Como editor, você é o proprietário.

Criar e publicar uma skill interativamente​

Para rascunhar e publicar uma habilidade do seu agente de codificação, instale o Python 3.12+ e o uv e siga os passos. Você precisa de um agente de codificação que suporte o Model Context Protocol (MCP), o padrão que os agentes usam para se conectar às ferramentas. Você pode pular os passos de configuração da CLI ao publicar uma habilidade existente do GitHub.

Instalar e conectar a CLI do Unity Gateway​

Instale a CLI do Unity Gateway e use-a para conectar seu agente de codificação ao registro de habilidades do seu workspace do Databricks.

A CLI do Unity Gateway registra você no seu workspace e conecta seu agente ao servidor MCP do Databricks Skills (databricks-skill-registry). Seu agente o usa para descobrir habilidades publicadas e obter os comandos para criar ou atualizar uma.

prompt

Peça ao seu agente para instalar e conectar a CLI do Unity Gateway para você:

Install the Unity Gateway 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.

Para fazer isso você mesmo, execute os mesmos comandos no seu terminal:

Bash
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 será aberto durante ug configure para que você faça o login. Reinicie o seu agente depois (ug <your-agent>) para que ele carregue a conexão do registro de habilidades.

Autentique a CLI do Databricks no mesmo workspace antes de publicar. Use um perfil de configuração para manter os comandos de publicação apontados para esse workspace:

Bash
databricks auth login --host https://<workspace-host> --profile <profile>

Use o mesmo <workspace-host> que em ug configure. Adicione --profile <profile> a cada comando da CLI do Databricks retornado pelo servidor Skills MCP quando você o executar.

Desenvolver uma habilidade localmente​

Uma habilidade é uma pasta: um arquivo SKILL.md com instruções, além de quaisquer arquivos de suporte que o agente deva ler. Você pode pedir ao seu agente de codificação ou ao Genie Code para rascunhar e refinar esses arquivos. Para uma habilidade criada no Genie Code, faça o download da pasta localmente e publique-a com o agente de codificação conectado.

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.

prompt

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:

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.

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.

prompt

Peça ao seu agente para publicá-lo para você:

Publish my ./databricks-sql-guide folder to the acme.sql_skills schema in Databricks.
Use the Skills MCP server to get the publishing steps, then run the
returned Databricks CLI commands locally with --profile <profile>.
Show me the commands before running them.

O servidor MCP de habilidades retorna os comandos da CLI do Databricks para criar a habilidade, fazer upload de sua pasta e finalizá-la. Seu agente de codificação pode fazer a execução desses comandos localmente, ou você pode revisá-los e fazer a execução deles por conta própria. O servidor MCP não executa os comandos nem faz upload dos arquivos.

Para alterar a habilidade mais tarde, edite a pasta local e peça ao seu agente para atualizá-la. O servidor retorna comandos para fazer upload e finalizar a nova versão. Se você excluiu arquivos locais, peça ao seu agente para comparar a pasta local com o bundle publicado e remover esses arquivos do bundle antes de finalizar. Revise os comandos antes de executá-los.

Compartilhe sua skill​

Uma skill publicada é privada até que você conceda acesso. As skills que o GitHub Action cria são de propriedade do seu service principal. O proprietário da skill ou um principal com MANAGE as compartilha. Você compartilha uma skill do Catalog Explorer concedendo READ VOLUME.

  1. No seu workspace do Databricks, clique em Ícone de dados. Catálogo .
  2. Navegue até o esquema que contém a habilidade e, em seguida, selecione a habilidade.
  3. Vá para a tab Permissões.
  4. Clique em Conceder .
  5. Insira o endereço de email de um usuário ou o nome de um grupo.
  6. Selecione READ VOLUME.
  7. 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 habilidade concede acesso à habilidade ao vivo. O agente do destinatário lê isso sob as concessões e auditoria da habilidade, portanto, dentro do seu metastore não há nada para manter em sincronia. Para obter o modelo de privilégio completo, consulte Governar habilidades.

As concessões alcançam as entidades em Workspace anexados ao mesmo metastore do Unity Catalog. Para compartilhar uma skill com Workspace anexados a outros metastores ou accounts, adicione-a a um compartilhamento OpenSharing, onde os destinatários obtêm acesso somente leitura à skill, e suas alterações chegam a eles automaticamente, ou liste-a no Databricks Marketplace. O compartilhamento de skills usando OpenSharing está em Beta.

Depois de compartilhar uma habilidade, os colegas de equipe a encontram e usam em seus próprios agentes. Consulte Descobrir e usar as habilidades do Unity Gateway.

Publicar habilidades do seu repository GitHub​

Se você já usa o GitHub para gerenciar suas habilidades, use a ação de publicação de habilidades do Unity Gateway para criar e atualizar suas contrapartes no Unity Catalog. Você precisa de permissão para adicionar um fluxo de trabalho ao repository que contém suas habilidades. O fluxo de trabalho é publicado a partir de um runner do GitHub após as alterações serem aplicadas com merge à sua branch de publicação. Você não precisa de um notebook, cluster ou job agendado do Databricks.

Para um repository upstream onde você não pode configurar fluxos de trabalho, consulte Avançado: Sincronizar um repository Git upstream.

Configure o acesso de publicação​

Um administrador do Databricks e um administrador do repository do GitHub completam esta configuração:

  1. Crie ou selecione um service principal de publicação, atribua-o ao workspace de destino e conceda-lhe os privilégios de catálogo e esquema em Requisitos em cada esquema de destino. Para skills existentes que ela atualiza, conceda também READ VOLUME e WRITE VOLUME. Novas skills são de propriedade do principal de publicação, então conceda MANAGE em cada esquema de destino aos usuários ou grupo que compartilham as skills. Eles também precisam de USE CATALOG e USE SCHEMA no catálogo pai e no esquema. A concessão de esquema se aplica às suas skills filhas. Consulte Herança de privilégios.
  2. Crie um ambiente GitHub chamado production no seu repository de habilidades. Restrinja suas Branch de implantação para main, ou a Branch da qual você pretende publicar.
  3. Configure a federação de identidade de carga de trabalho do GitHub no service principal de publicação. Combine o assunto OpenID Connect (OIDC) exato para o seu repository de habilidades e o ambiente production. O GitHub emite um token de identidade de curta duração que o Databricks SDK troca por um access token do Databricks, para que nenhum segredo de cliente do Databricks seja armazenado no GitHub. Repositórios mais novos podem incluir IDs numéricos de organização e repository em seu assunto. Siga o guia de federação para configurar o assunto e o público para o seu repository.
  4. Em Configurações > Ambientes > produção > Variáveis de ambiente , adicione DATABRICKS_HOST com a URL base do seu workspace e DATABRICKS_CLIENT_ID com o ID do aplicativo do service principal. Nenhum dos valores é secreto.
  5. Escolha um runner Linux que possa acessar seu workspace. O exemplo usa um runner hospedado no GitHub. Um workspace com rede privada ou listas de acesso de IP pode exigir um runner em sua rede.

Para instruções detalhadas do administrador e uma alternativa de máquina para máquina OAuth, consulte o guia de autenticação da ação.

Os exemplos fazem referência à ação em main, portanto, eles recebem suas atualizações mais recentes. Para fluxos de trabalho reproduzíveis, substitua main na referência da ação por um commit SHA revisado do repository Unity Gateway. Você não precisa instalar a CLI do Unity Gateway.

Adicionar o fluxo de trabalho​

  1. Adicione suas habilidades ao repository. Cada pasta filha imediata de skills que contém SKILL.md torna-se uma skill. Os arquivos de suporte em cada pasta estão incluídos:

    Text
    skills/
    ├── sql-guide/
    │ ├── SKILL.md
    │ └── references/conventions.md
    └── code-review/
    └── SKILL.md

    O nome base da pasta determina o identificador de habilidade do Unity Catalog ao usar skills-directory: skills/sql-guide torna-se acme.team_skills.sql-guide. O name em SKILL.md permanece como metadado de habilidade obrigatório, mas a ação não o usa para escolher o identificador do Unity Catalog. Para maior clareza, use name: sql-guide neste exemplo. Um mapeamento explícito usa seu valor target em vez do nome base da pasta.

    Para obter conteúdos de skills e frontmatter, consulte Desenvolver uma skill localmente.

  2. Crie .github/workflows/publish-skills.yml com o seguinte conteúdo. Substitua acme.team_skills por seu catálogo e esquema existentes. Se sua branch de publicação ou pasta de origem for diferente, atualize também os filtros de branch e caminho.

    YAML
    name: Publish skills to Databricks
    on:
    push:
    branches: [main]
    paths: ['skills/**', '.github/workflows/publish-skills.yml']
    workflow_dispatch:
    inputs:
    dry_run:
    description: Validate folders without publishing
    type: boolean
    default: true
    permissions:
    contents: read
    id-token: write
    concurrency:
    group: publish-uc-skills
    cancel-in-progress: false
    jobs:
    publish:
    runs-on: ubuntu-latest
    environment: production
    env:
    DATABRICKS_AUTH_TYPE: github-oidc
    DATABRICKS_HOST: ${{ vars.DATABRICKS_HOST }}
    DATABRICKS_CLIENT_ID: ${{ vars.DATABRICKS_CLIENT_ID }}
    steps:
    - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
    with:
    persist-credentials: false
    - uses: databricks/unity-gateway/actions/publish-skills@main
    with:
    skills-directory: skills
    target-schema: acme.team_skills
    dry-run: ${{ github.event_name == 'workflow_dispatch' && inputs.dry_run || false }}

    Isso mapeia skills/sql-guide para acme.team_skills.sql-guide e skills/code-review para acme.team_skills.code-review.

  3. Faça merge do fluxo de trabalho e das skills para main. Isso Trigger a primeira publicação. Para validar arquivos de origem em pull requests antes de publicar, adicione o fluxo de trabalho de validação da action. Execuções a seco validam pastas de skills locais sem entrar em contato com o Databricks. Eles não testam autenticação, acesso à rede ou permissões. Como o ambiente production permite apenas main, execute dry runs manuais a partir de main e use o fluxo de trabalho de validação para verificar outras Branch.

  4. No GitHub, abra Actions > Publish skills to Databricks e verifique os logs de execução. No Databricks, abra o Catalog Explorer e confirme que as skills aparecem no seu schema de destino. Após o fluxo de trabalho estar no main, você também pode selecionar Run fluxo de trabalho e deixar Validate folders without publishing selecionado para uma execução de teste, ou desmarcá-lo para publicar.

Os merges subsequentes que alteram a pasta skills publicam atualizações para as mesmas skills. A propriedade e as concessões existentes são preservadas. Após a publicação, um proprietário de skill ou um principal com MANAGE concede acesso aos membros da equipe. Consulte Compartilhar sua skill. A ação não concede acesso ao consumidor. Os consumidores podem carregar as skills do esquema ao vivo.

Remover uma pasta de origem não exclui sua skill do Unity Catalog, e renomear um destino de mapeamento cria uma nova skill e mantém a antiga. Por default, se uma skill mapeada contiver arquivos remotos ausentes da pasta local, a publicação dessa skill falhará antes de fazer upload das alterações e deixará esses arquivos no local. Defina prune-files: 'true' para remover arquivos remotos ausentes de cada pasta publicada. As atualizações de skill não são atômicas; portanto, inspecione as execuções com falha antes de tentar novamente.

Mapear pastas selecionadas para nomes de habilidades​

Para nomes personalizados, pastas fora de skills ou vários esquemas de destino, adicione um arquivo de mapeamento skills.yaml na raiz do repository:

YAML
version: 1
skills:
- path: skills/sql-guide
target: acme.team_skills.sql-guide
- path: .claude/skills/review
target: acme.team_skills.code-review

Substitua skills-directory e target-schema no o passo de publicação por mapping-file:

YAML
- uses: databricks/unity-gateway/actions/publish-skills@main
with:
mapping-file: skills.yaml
dry-run: ${{ github.event_name == 'workflow_dispatch' && inputs.dry_run || false }}

Atualize o filtro paths do fluxo de trabalho para incluir skills.yaml, cada pasta de origem mapeada e o arquivo de fluxo de trabalho. Conceda ao principal de publicação acesso a cada destino mapeado. Consulte os exemplos de ação para configurações de fluxo de trabalho adicionais.

Avançado: Sincronizar um repository Git upstream​

Use a abordagem de notebook quando você não puder adicionar um fluxo de trabalho de publicação ao repository de origem, como um repository de terceiros que sua equipe consome. Você controla o esquema de destino e a sincronização agendada em seu workspace. Se você pode configurar o GitHub Actions no repository de origem, consulte Publicar skills do seu repository do GitHub.

Importe o seguinte Notebook para o seu Workspace do Databricks, configure os widgets git_url, catalog, schema e branch (e git_credential_id para um repo privado), depois faça a execução dele em programar. Ele clona o repo, cria novas habilidades e atualiza as que foram alteradas. Ele nunca exclui, portanto, uma habilidade removida do repo permanece no esquema até que você a solte. A execução ocorre com suas credenciais do Workspace e é publicada como você.

Sincronizar um repo Git de habilidades com um esquema do Unity Catalog

Quando um esquema é mantido em sincronia dessa forma, os consumidores podem carregar todo o esquema ao vivo para que seus agentes obtenham as habilidades publicadas mais recentes.

Referência​

A CLI do Unity Gateway é de código aberto. Para obter a referência completa e atual dos comandos, consulte o repository da CLI do Unity Gateway. Os comandos usados neste tutorial aparecem em linha nos passos acima.

Para interfaces suportadas pelo servidor Skills MCP e compatibilidade de cliente, consulte Acessar skills via MCP. Para compartilhar uma skill, conceda READ VOLUME a ela no Catalog Explorer. Consulte Compartilhar sua skill.

Passos seguintes​