Tutoriel : créer et partager des compétences Unity Catalog

Ce tutoriel est destiné aux auteurs de compétences et aux équipes centrales qui souhaitent gérer les compétences en tant qu’assets Unity Catalog gouvernés. Vous développez une compétence localement, vous la publiez dans un schéma Unity Catalog et vous la partagez, afin que l’agent de n’importe quel coéquipier puisse l’utiliser sous les mêmes autorisations et audits qui régissent le reste de vos données Databricks.

Exigences

• Un workspace Databricks compatible avec Unity Catalog, et l'URL de votre workspace (par exemple, https://my-company.cloud.databricks.com).
• Python 3.12+ et uv sur votre machine (utilisé pour installer ucode).
• Un agent de codage compatible MCP (MCP, le Model Context Protocol, est la norme ouverte que les agents utilisent pour se connecter aux outils).
• USE SCHEMA et CREATE VOLUME sur le schéma cible. Votre administrateur Databricks les accorde. Voir Gérer les compétences pour le modèle complet.

Installer et connecter ucode

Installez ucode et utilisez-le pour connecter votre agent de codage au registre de compétences de votre workspace Databricks.

ucode vous connecte à votre workspace et enregistre le serveur MCP Databricks Skills (databricks-skill-registry) que votre agent utilise pour créer et mettre à jour des compétences.

prompt

Demandez à votre agent d'installer et de connecter ucode pour vous :

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.

Pour le faire vous-même, exécutez les mêmes commandes dans votre terminal :

Bash

uv tool install git+https://github.com/databricks/ucode
ucode configure --agents <your-agent> --workspaces https://<workspace-host>
ucode configure skills

Remplacez <your-agent> par le nom de l’agent de codage que vous utilisez (par exemple, claude, codex, gemini, opencode ou copilot), et <workspace-host> par l’hôte de l’URL de votre workspace. Un navigateur s’ouvre pendant ucode configure pour vous permettre de vous connecter. Redémarrez votre agent par la suite (ucode <your-agent>) afin qu’il charge les nouveaux outils.

Développer une compétence en local

Une compétence est simplement un dossier : un fichier SKILL.md contenant des instructions, ainsi que tous les fichiers de support que l’agent doit lire.

Dans ce tutoriel, vous créez une compétence databricks-sql-guide : les conventions de votre équipe pour l'écriture de Databricks SQL, afin que chaque query écrite par un agent respecte les mêmes normes.

prompt

Demandez à votre agent de rédiger la compétence pour vous :

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.

L’agent écrit un dossier comme suit :

databricks-sql-guide/
└── SKILL.md

Un SKILL.md minimal possède un frontmatter YAML et des 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.

Le description est primordial : c'est ce sur quoi les agents s'appuient pour décider s'ils doivent utiliser une compétence. Soyez donc précis sur ce que la compétence couvre et quand l'utiliser. Examinez le brouillon et affinez-le jusqu'à ce qu'il reflète vos conventions.

Publiez la compétence dans Unity Catalog

La publication importe votre dossier local vers un schéma Unity Catalog en tant que compétence gouvernée. Vous devenez le propriétaire de la compétence, et celle-ci reste privée jusqu’à ce que vous la partagiez.

prompt

Demandez à votre agent de le publier pour vous :

Publish my ./databricks-sql-guide folder to the acme.sql_skills schema in Databricks.

L’agent appelle l’outil MCP create_skill pour upload le dossier et enregistrer la compétence.

Pour modifier la compétence ultérieurement, modifiez le dossier local et demandez à l’agent de la mettre à jour à partir de votre dossier. L’agent appelle update_skill sur le même serveur.

Partagez votre compétence

Une compétence publiée vous est privée jusqu'à ce que vous accordiez l'accès. Vous le partagez depuis Catalog Explorer en accordant READ VOLUME.

Autorisations requises : vous devez être le propriétaire de la compétence ou disposer de MANAGE sur celle-ci.

1. Dans votre workspace Databricks, cliquez sur Catalog .
2. Accédez au schéma qui contient la compétence, puis sélectionnez la compétence.
3. Accédez à l'onglet tab .
4. Cliquez sur Accorder .
5. Saisissez l’adresse e-mail d’un utilisateur ou le nom d’un groupe.
6. Sélectionner READ VOLUME.
7. Cliquez sur OK .

Les destinataires ont également besoin de USE CATALOG sur acme et de USE SCHEMA sur sql_skills pour accéder à la compétence. Accordez-les sur le catalogue et le schéma de la même manière. Pour révoquer l'accès ultérieurement, sélectionnez l'autorisation dans la Permissions tab et cliquez sur Révoquer .

Le partage d'une compétence est une autorisation, pas une copie : l'agent du destinataire lit la compétence en temps réel sous vos autorisations et votre audit ; il n'y a donc rien à synchroniser. Pour le modèle de privilèges complet, voir Gérer les compétences.

Une fois partagée, vos coéquipiers peuvent trouver et utiliser votre compétence depuis leurs propres agents. Voir Découvrir et utiliser les compétences Unity Catalog.

Synchroniser un Git skill repository avec un schéma UC

Si votre équipe conserve des compétences dans un repository Git, vous pouvez toutes les publier automatiquement dans un schéma, afin que le schéma suive une branch du repository.

Importez le notebook suivant dans votre workspace Databricks, configurez les widgets git_url, catalog, schema et branch (ainsi que git_credential_id pour un repository privé), puis exécutez-le selon une planification. Il clone le repository, crée de nouvelles compétences et met à jour celles qui ont été modifiées ; il ne supprime jamais rien, donc une compétence retirée du repository reste dans le schéma jusqu’à ce que vous la supprimiez. Il s’exécute avec vos identifiants de workspace et publie en votre nom.

Synchroniser un repository Git de compétences avec un schéma Unity Catalog

Ouvrir le notebook dans un nouvel ongletOuvrir dans Databricks

Une fois qu'un schéma est synchronisé de cette manière, les consommateurs peuvent charger l'intégralité du schéma en direct afin que leurs agents obtiennent toujours les dernières compétences publiées.

Référence

ucode est open source. Pour la référence complète et actuelle des commandes, consultez le repository ucode. Les commandes utilisées dans ce tutoriel apparaissent en ligne dans les étapes ci-dessus.

Outils de compétences (votre agent les appelle sur le serveur MCP databricks-skill-registry une fois connecté) :

Outil	Usage
create_skill / update_skill / delete_skill	Publier, mettre à jour ou supprimer une compétence

Outil	Usage
create_skill / update_skill / delete_skill	Publier, mettre à jour ou supprimer une compétence

Pour partager une compétence, accordez READ VOLUME sur celle-ci dans Catalog Explorer. Voir Partager votre compétence.

Étapes suivantes

• Qu'est-ce que les compétences Unity Catalog pour les concepts derrière ce tutoriel.
• Découvrez et utilisez les compétences Unity Catalog pour intégrer des compétences publiées dans votre agent.
• Gouverner les compétences pour configurer des schémas gouvernés et gérer le modèle de privilèges.