Tutoriel : créer et partager des compétences Unity Gateway
Bêta
Cette fonctionnalité est en bêta. Pour l'utiliser, un administrateur de workspace doit activer les compétences Unity Gateway dans Genie depuis la page Prévisualisations . Consultez Gérer les aperçus Databricks.
Créez une compétence avec votre agent de codage, publiez-la dans le Unity Catalog et partagez-la avec vos coéquipiers. Si vous gérez déjà des compétences dans GitHub, publiez-les avec une GitHub Action. Pour les repository en amont où vous ne pouvez pas ajouter de workflow, synchronisez-les avec un Notebook. Pour créer et gérer des compétences avec l’API REST, le CLI Databricks ou les SDKs, consultez la référence de l’API et du SDK des compétences.
Exigences
- Un workspace Databricks compatible avec Unity Catalog et votre URL de workspace (par exemple,
https://my-company.cloud.databricks.com). La création et la mise à jour de compétences doivent être activées pour votre workspace. Les Workspace qui utilisent le profil de sécurité de la conformité bloquent ces Opérations. Consultez les considérations relatives au compte et à la conformité. - Un schéma existant dans un catalogue Unity Catalog standard avec un emplacement de stockage géré. Voir Configurer un schéma gouverné pour les compétences.
- Python 3.12+ et uv sur votre machine (utilisés pour installer la CLI Unity Gateway).
- La CLI Databricks, installée et authentifiée, pour exécuter les commandes renvoyées par le serveur Skills MCP lors de la publication ou de la mise à jour d’une compétence.
- Un agent de codage compatible MCP (MCP, le protocole de contexte de modèle, est la norme ouverte que les agents utilisent pour se connecter aux serveurs).
USE CATALOGsur le catalogue cible, etUSE SCHEMAetCREATE VOLUMEsur le schéma cible. Votre administrateur Databricks les accorde. Consultez Gérer les compétences pour le modèle complet.- Pour partager une compétence, la propriété de la compétence ou
MANAGEsur elle. En tant qu'éditeur, vous en êtes le propriétaire.
Créer et publier une compétence de manière interactive
Pour rédiger et publier une compétence à partir de votre agent de codage, installez Python 3.12+ et uv, puis suivez ces étapes. Vous avez besoin d’un agent de codage qui prend en charge le protocole MCP (Model Context Protocol), le standard que les agents utilisent pour se connecter aux outils. Vous pouvez ignorer ces étapes de configuration du CLI lors de la publication d’une compétence existante depuis GitHub.
Installez et connectez la CLI Unity Gateway
Installez la Unity Gateway CLI et utilisez-la pour connecter votre agent de codage au registre de compétences de votre Workspace Databricks.
L'Unity Gateway CLI vous connecte à votre workspace et connecte votre agent au serveur Databricks Skills MCP (databricks-skill-registry). Votre agent l'utilise pour découvrir les compétences publiées et obtenir les commandes pour en créer ou en mettre à jour une.
Laissez votre agent installer et connecter la CLI Unity Gateway pour vous :
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.
Pour le faire vous-même, exécutez les mêmes commandes dans votre terminal :
uv tool install git+https://github.com/databricks/unity-gateway
ug configure --agents <your-agent> --workspace https://<workspace-host>
ug 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 ug configure pour que vous puissiez vous connecter. Redémarrez votre agent par la suite (ug <your-agent>) afin qu'il charge la connexion au registre des compétences.
Authentifiez le CLI Databricks sur le même workspace avant la publication. Utilisez un profil de configuration pour que les commandes de publication pointent vers ce workspace :
databricks auth login --host https://<workspace-host> --profile <profile>
Utilisez le même <workspace-host> que dans ug configure. Ajoutez --profile <profile> à chaque commande Databricks CLI renvoyée par le serveur MCP Skills lorsque vous l'exécutez.
Développer une compétence en local
Une compétence est un dossier : un fichier SKILL.md contenant des instructions, ainsi que tous les fichiers de support que l’agent doit lire. Vous pouvez demander à votre agent de codage ou à Genie Code de rédiger et d’affiner ces fichiers. Pour une compétence créée dans Genie Code, download son dossier localement, puis publiez-la avec l’agent de codage connecté.
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.
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 :
---
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.
Demandez à votre agent de le publier pour vous :
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.
Le serveur MCP Skills renvoie les commandes Databricks CLI pour créer la compétence, upload son dossier et la finaliser. Votre agent de codage peut exécuter ces commandes localement, ou vous pouvez les examiner et les exécuter vous-même. Le serveur MCP n'exécute pas les commandes et ne fait pas d'upload des fichiers.
Pour modifier la compétence plus tard, modifiez le dossier local et demandez à votre agent de la mettre à jour. Le serveur renvoie des commandes pour faire l'upload et finaliser la nouvelle version. Si vous avez supprimé des fichiers locaux, demandez à votre agent de comparer le dossier local avec le bundle publié et de supprimer ces fichiers du bundle avant de finaliser. Passez en revue les commandes avant de les exécuter.
Partagez votre compétence
Une compétence publiée est privée tant que vous n’accordez pas l’accès. Les compétences créées par l’ Action GitHub appartiennent à son Service Principal. Le propriétaire de la compétence ou un principal avec MANAGE les partage. Vous partagez une compétence depuis l’ explorateur de catalogue en accordant READ VOLUME.
- Dans votre workspace Databricks, cliquez sur
Catalog .
- Accédez au schéma qui contient la compétence, puis sélectionnez la compétence.
- Accédez à l'onglet tab .
- Cliquez sur Accorder .
- Saisissez l’adresse e-mail d’un utilisateur ou le nom d’un groupe.
- Sélectionner
READ VOLUME. - 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'un skill donne accès au skill en direct. L'agent du destinataire le lit sous les autorisations et l'audit du skill, donc dans votre metastore, il n'y a rien à synchroniser. Pour le modèle de privilège complet, voir Gouverner les skills.
Les octrois atteignent les principaux sur les Workspace attachés au même metastore Unity Catalog. Pour partager une compétence avec des Workspace attachés à d'autres metastores ou comptes, ajoutez-la à un partage OpenSharing, où les destinataires obtiennent un accès en lecture seule à la compétence et où vos modifications les atteignent automatiquement, ou listez-la sur Databricks Marketplace. Partager des compétences avec OpenSharing est en version bêta.
Une fois que vous avez partagé une compétence, vos coéquipiers la trouvent et l’utilisent à partir de leurs propres agents. Voir Découvrir et utiliser les compétences Unity Gateway.
Publier des compétences à partir de votre repository GitHub
Si vous utilisez déjà GitHub pour gérer vos compétences, utilisez l' action de publication de compétence Unity Gateway pour créer et mettre à jour leurs homologues dans le Unity Catalog. Vous avez besoin d'une autorisation pour ajouter un Workflow au repository qui contient vos compétences. Le workflow publie depuis un runner GitHub après que les modifications sont Merge avec votre Branch de publication. Vous n'avez pas besoin d'un notebook Databricks, d'un cluster ou d'un job planifié.
Pour un repository amont où vous ne pouvez pas configurer de workflows, voir Avancé : Synchroniser un repository Git amont.
Configurer l'accès aux publications
Un administrateur Databricks et un administrateur de repository GitHub effectuent cette configuration :
- Créez ou sélectionnez un Service Principal de publication, attribuez-le au workspace cible et accordez-lui les privilèges de catalogue et de schéma dans Configuration requise sur chaque schéma de destination. Pour les compétences existantes qu'il met à jour, accordez également
READ VOLUMEetWRITE VOLUME. Les nouvelles compétences appartiennent au principal de publication, alors accordezMANAGEsur chaque schéma de destination aux utilisateurs ou au groupe qui partagent les compétences. Ils ont également besoin deUSE CATALOGet deUSE SCHEMAsur le catalogue parent et le schéma. L'autorisation de schéma s'applique à ses compétences enfants. Voir Héritage des privilèges. - Créez un GitHub environment nommé
productiondans votre repository de compétences. Restreignez ses Branch de déploiement àmain, ou à la Branch depuis laquelle vous avez l'intention de publier. - Configurez la fédération d’identités de charge de travail GitHub sur le Service Principal de publication. Faites correspondre le sujet OpenID Connect (OIDC) exact pour votre repository de compétences et l’environnement
production. GitHub émet un jeton d’identité à courte durée de vie que le SDK Databricks échange contre un jeton d’accès Databricks, de sorte qu’aucun secret de client Databricks n’est stocké dans GitHub. Les repository plus récents peuvent inclure des identifiants d’organisation et de repository numériques dans leur sujet. Suivez le guide de fédération pour configurer le sujet et le public de votre repository. - Dans Paramètres > Environnements > production > Variables d'environnement , ajoutez
DATABRICKS_HOSTavec l'URL de base de votre workspace etDATABRICKS_CLIENT_IDavec l'ID d'application du Service Principal. Aucune de ces deux valeurs n'est secrète. - Choisissez un exécutant Linux capable d'atteindre votre workspace. L'exemple utilise un exécutant hébergé par GitHub. Un workspace avec un réseau privé ou des listes d'accès IP pourrait nécessiter un exécutant sur votre réseau.
Pour obtenir des instructions d'administration détaillées et une alternative OAuth de machine à machine, consultez le guide d'authentification de l'action.
Les exemples font référence à l’action sur main, donc ils prennent ses dernières mises à jour. Pour des workflows reproductibles, remplacez main dans la référence d’action par un commit SHA révisé du repository Unity Gateway. Vous n’avez pas besoin d’installer le Unity Gateway CLI.
Ajouter le workflow
-
Ajoutez vos compétences au repository. Chaque sous-dossier immédiat de
skillscontenantSKILL.mddevient une compétence. Les fichiers de support dans chaque dossier sont inclus :Textskills/├── sql-guide/│ ├── SKILL.md│ └── references/conventions.md└── code-review/└── SKILL.mdLe nom de base du dossier détermine l'identifiant de la compétence Unity Catalog lors de l'utilisation de
skills-directory:skills/sql-guidedevientacme.team_skills.sql-guide. LenamedansSKILL.mddemeure une métadonnée de compétence requise, mais l'action ne l'utilise pas pour choisir l'identifiant Unity Catalog. Pour plus de clarté, utilisezname: sql-guidedans cet exemple. Un mappage explicite utilise sa valeurtargetau lieu du nom de base du dossier.Pour le contenu des compétences et le frontmatter, consultez Développer une compétence localement.
-
Créez
.github/workflows/publish-skills.ymlavec le contenu suivant : Remplacezacme.team_skillspar votre catalogue et votre schéma existants. Si votre branch de publication ou dossier source diffère, mettez aussi à jour les filtres de branch et de chemin.YAMLname: Publish skills to Databrickson:push:branches: [main]paths: ['skills/**', '.github/workflows/publish-skills.yml']workflow_dispatch:inputs:dry_run:description: Validate folders without publishingtype: booleandefault: truepermissions:contents: readid-token: writeconcurrency:group: publish-uc-skillscancel-in-progress: falsejobs:publish:runs-on: ubuntu-latestenvironment: productionenv:DATABRICKS_AUTH_TYPE: github-oidcDATABRICKS_HOST: ${{ vars.DATABRICKS_HOST }}DATABRICKS_CLIENT_ID: ${{ vars.DATABRICKS_CLIENT_ID }}steps:- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1with:persist-credentials: false- uses: databricks/unity-gateway/actions/publish-skills@mainwith:skills-directory: skillstarget-schema: acme.team_skillsdry-run: ${{ github.event_name == 'workflow_dispatch' && inputs.dry_run || false }}Cela fait correspondre
skills/sql-guideàacme.team_skills.sql-guideetskills/code-reviewàacme.team_skills.code-review. -
Merge le workflow et les compétences dans
main. Cela Trigger la première publication. Pour valider les fichiers sources dans les pull requests avant la publication, ajoutez le workflow de validation de l'action. Les exécutions à sec valident les dossiers de compétences locaux sans contacter Databricks. Ils ne testent pas l'authentification, l'accès réseau ou les autorisations. Comme l'environnementproductionautorise uniquementmain, effectuez des exécutions à sec manuelles à partir demainet utilisez le workflow de validation pour vérifier les autres Branch. -
Dans GitHub, ouvrez Actions > Publish skills to Databricks et vérifiez les logs d'exécution. Dans Databricks, ouvrez Catalog Explorer et confirmez que les compétences apparaissent dans votre schéma cible. Une fois le workflow sur
main, vous pouvez également sélectionner Run workflow et laisser Validate folders without publishing sélectionné pour un test à blanc, ou le désélectionner pour publier.
Les Merge ultérieures qui modifient le dossier skills publient les mises à jour sur les mêmes compétences. La propriété et les autorisations existantes sont conservées. Après la publication, un propriétaire de compétence ou un principal avec des autorisations MANAGE donne aux coéquipiers accès. Voir Partager votre compétence. L'action ne donne pas accès au consommateur. Les consommateurs peuvent charger les compétences du schéma en direct.
La suppression d’un dossier source ne supprime pas sa compétence Unity Catalog, et le renommage d’une cible de mappage crée une nouvelle compétence tout en conservant l’ancienne. By default, si une compétence mappée contient des fichiers distants absents du dossier local, la publication de cette compétence échoue avant l’upload des modifications et laisse ces fichiers en place. Définissez prune-files: 'true' pour supprimer les fichiers distants absents de chaque dossier publié. Les mises à jour de compétences ne sont pas atomiques ; inspectez donc les exécutions ayant échoué avant de réessayer.
Mapper les dossiers sélectionnés aux noms des compétences
Pour les noms personnalisés, les dossiers en dehors de skills ou les multiples schémas de destination, ajoutez un fichier de mappage skills.yaml à la racine du repository :
version: 1
skills:
- path: skills/sql-guide
target: acme.team_skills.sql-guide
- path: .claude/skills/review
target: acme.team_skills.code-review
Remplacez skills-directory et target-schema dans l'étape de publication par mapping-file:
- uses: databricks/unity-gateway/actions/publish-skills@main
with:
mapping-file: skills.yaml
dry-run: ${{ github.event_name == 'workflow_dispatch' && inputs.dry_run || false }}
Mettez à jour le filtre paths du workflow pour inclure skills.yaml, chaque dossier source mappé et le fichier de workflow. Accordez au principal de publication l'accès à chaque destination mappée. Consultez les exemples d’actions pour des configurations de workflow supplémentaires.
Avancé : Synchroniser un repository Git amont
Utilisez l’approche notebook lorsque vous ne pouvez pas ajouter un workflow de publication au repository source, comme un repository tiers que votre équipe utilise. Vous contrôlez le schéma de destination et la synchronisation planifiée dans votre workspace. Si vous pouvez configurer des GitHub Actions dans le repository source, voir Publier des compétences à partir de votre repository GitHub.
Importez le notebook suivant dans votre workspace Databricks, définissez les widgets git_url, catalog, schema et branch (et git_credential_id pour un repo privé), puis exécutez-le selon une planification. Il clone le repo, crée de nouvelles compétences et met à jour celles qui ont été modifiées. Il ne supprime jamais, donc une compétence supprimée du repo reste dans le schéma jusqu'à ce que vous la supprimiez. Il s'exécute avec les identifiants de votre workspace et publie en tant que vous.
Synchroniser un repository Git de compétences avec un schéma Unity Catalog
Lorsqu'un schéma est synchronisé de cette manière, les consommateurs peuvent charger l'ensemble du schéma en direct afin que leurs agents obtiennent les dernières compétences publiées.
Référence
La CLI Unity Gateway est open source. Pour obtenir la référence complète et actuelle des commandes, consultez le repository de la CLI Unity Gateway. Les commandes utilisées dans ce tutoriel apparaissent en ligne dans les étapes ci-dessus.
Pour les interfaces prises en charge par le serveur Skills MCP et la compatibilité des clients, consultez Accéder aux compétences via MCP. Pour partager une compétence, accordez READ VOLUME sur celle-ci dans l'Explorateur de catalogue. Consultez Partager votre compétence.
Étapes suivantes
- Support des compétences dans Unity Gateway pour les concepts derrière ce tutoriel.
- Découvrez et utilisez les compétences Unity Gateway 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.
- Référence de l’API Skills et du SDK pour automatiser la gestion des compétences avec l’API REST, la CLI Databricks et les SDK.