メインコンテンツまでスキップ

チュートリアル: Unity Gateway スキルの作成と共有

備考

ベータ版

この機能はベータ版です。使用するには、ワークスペース管理者が プレビュー ページから GenieのUnity Gatewayスキル を有効にする必要があります。Databricksのプレビューを管理するを参照してください。

コーディングエージェントでスキルを作成し、Unity Catalog に公開し、チームメイトと共有します。すでに GitHub でスキルを管理している場合は、GitHub Action を使用して公開してください。ワークフローを追加できないアップストリームリポジトリについては、ノートブックと同期します。代わりに REST API、Databricks CLI、または SDK を使用してスキルを作成および管理するには、スキル API および SDK リファレンスを参照してください。

要件​

  • Unity Catalog が有効な Databricks ワークスペース、およびワークスペース URL(例:https://my-company.cloud.databricks.com)。スキルを作成および更新するには、ワークスペースで有効にする必要があります。コンプライアンスセキュリティプロファイルを使用するワークスペースは、これらの操作をブロックします。アカウントおよびコンプライアンスに関する考慮事項を参照してください。
  • 管理ストレージの場所を持つ標準の Unity Catalog カタログ内の既存のスキーマ。スキルの管理対象スキーマの設定を参照してください。
  • マシン上のPython 3.12以降およびuv(Unity Gateway CLIのインストールに使用)
  • Databricks CLI(インストールおよび認証済み)。スキルを発行または更新するときに、スキル MCP サーバーが返すコマンドを実行するために必要です。
  • MCP 対応のコーディングエージェント(MCP は Model Context Protocol の略で、エージェントがサーバーに接続するために使用するオープン標準です)。
  • USE CATALOG ターゲットカタログに、そしてターゲットスキーマに USE SCHEMA および CREATE VOLUME。これらはDatabricks管理者が付与します。完全なモデルについては、「 スキルの管理」を参照してください。
  • スキルを共有するには、スキルまたはそのスキルに対する MANAGE の所有権が必要です。パブリッシャーとして、所有者になります。

インタラクティブにスキルを作成して公開する​

コーディングエージェントからスキルをドラフトおよび公開するには、Python 3.12 以降と uv をインストールしてから、以下のステップに従ってください。エージェントがツールに接続するために使用する標準である Model Context Protocol (MCP) をサポートするコーディングエージェントが必要です。GitHub から既存のスキルを公開する場合、これらの CLI セットアップステップはスキップできます。

Unity Gateway CLIのインストールと接続​

Unity Gateway CLI をインストールし、それを使用してコーディングエージェントを Databricks ワークスペースのスキルレジストリに接続します。

Unity Gateway CLIを使うと、ワークスペースにサインインし、エージェントを Databricks Skills MCPサーバー (databricks-skill-registry)に接続できます。エージェントはそれを使って公開済みのスキルを検出し、スキルを作成または更新するためのコマンドを取得します。

プロンプト

エージェントに Unity Gateway CLI をインストールおよび接続させます:

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.

ご自身で行う場合は、ターミナルで同じコマンドを実行してください。

Bash
uv tool install git+https://github.com/databricks/unity-gateway
ug configure --agents <your-agent> --workspace https://<workspace-host>
ug skills

<your-agent> は使用するコーディングエージェントの名前(例: claude、codex、gemini、opencode、または copilot)に、<workspace-host> はワークスペースのURLホストに置き換えてください。ug configure の間にブラウザーが開き、サインインを求められます。その後、エージェントを再起動して (ug <your-agent>) スキルレジストリ接続を読み込みます。

公開する前に、Databricks CLIを同じワークスペースに対して認証します。構成プロファイルを使用して、公開コマンドがそのワークスペースを指すようにします。

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

ug configureと同じ<workspace-host>を使用します。Skills MCPサーバーを実行したときに返される各Databricks CLIコマンドに--profile <profile>を追加します。

スキルをローカルで開発する​

スキルとはフォルダーです。このフォルダーには、SKILL.md ファイル(指示が含まれます)と、エージェントが読み取る必要のあるサポートファイルが含まれます。コーディングエージェントまたは Genie Code に依頼して、これらのファイルのドラフトを作成・修正することができます。Genie Codeで作成されたスキルの場合、フォルダーをローカルにdownloadしてから、接続されているコーディングエージェントを使用して公開します。

このチュートリアルでは databricks-sql-guide スキルを構築します。これは Databricks SQL を記述するためのチームの規約であり、エージェントが記述するすべてのクエリーが同じ標準に従うようにします。

プロンプト

エージェントにスキルをドラフト作成させます:

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.

エージェントは次のようなフォルダーを書き込みます:

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

最小限の SKILL.md には、YAMLフロントマターと指示が含まれています:

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.

description が最も重要です。これは、エージェントがスキルを使用するかどうかを決定する際に照合される対象であるため、そのスキルが 何を カバーし、 いつ 使用すべきかを具体的に記述してください。下書きを確認し、独自の規則が反映されるまで修正してください。

スキルを Unity Catalog に公開する​

公開すると、ローカルフォルダーがガバナンス対象のスキルとしてUnity Catalogスキーマにuploadされます。あなたがそのスキルの 所有者 となり、共有するまで非公開となります。

プロンプト

エージェントに公開を依頼する:

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.

Skills MCPサーバーは、スキルを作成し、そのフォルダーをuploadし、終了するためのDatabricks CLIコマンドを返します。コーディングエージェントはそれらのコマンドをローカルでランできます。または、自分でレビューしてランすることもできます。MCPサーバーは、コマンドを実行したりファイルをuploadしたりしません。

後でスキルを変更するには、ローカルフォルダを編集し、エージェントに更新するように依頼します。サーバーは、新しいバージョンをuploadして完了するためのコマンドを返します。ローカルファイルを削除した場合は、エージェントにローカルフォルダと公開されたバンドルを比較させ、ファイナライズする前にバンドルからそれらのファイルを削除するように依頼してください。コマンドを実行する前に、コマンドを確認してください。

スキルの共有​

公開されたスキルは、アクセス権を付与するまでプライベートです。GitHub Actionsが作成するスキルは、そのService Principalが所有します。スキル所有者またはMANAGEを持つプリンシパルがそれらを共有します。あなたは、カタログエクスプローラーからREAD VOLUMEを付与することでスキルを共有します。

  1. Databricks ワークスペースで、データアイコン。 カタログ をクリックします。
  2. スキルが保持されているスキーマに移動し、そのスキルを選択します。
  3. 権限 タブに移動します。
  4. 付与 をクリックします。
  5. ユーザーのメールアドレスまたはグループ名を入力します。
  6. READ VOLUMEを選択してください。
  7. OK をクリックします。

受信者がスキルにアクセスするには、acmeに対するUSE CATALOGと、sql_skillsに対するUSE SCHEMAも必要です。カタログとスキーマに対しても同様の方法で権限を付与します。後でアクセス権を取り消すには、[ 権限 ] tab で付与された権限を選択し、[ 取り消し ] をクリックします。

スキルを共有すると、ライブスキルへのアクセスが許可されます。受信者のエージェントはスキルの許可と監査の下でそれを読み取るため、メタストア内で同期を維持する必要はありません。完全な権限モデルについては、「スキルをガバナンスする」を参照してください。

同じUnity Catalogメタストアにアタッチされたワークスペースのプリンシパルにアクセス権を付与します。他のメタストアやアカウントにアタッチされたワークスペースとスキルを共有するには、そのスキルをOpenSharing共有に追加します。これにより、受信者はスキルに対して読み取り専用のアクセス権を取得し、あなたの変更が自動的に受信者に反映されるか、またはそのスキルがDatabricks Marketplaceにリストされます。OpenSharingを使用したスキルの共有はベータ版です。

スキルを共有すると、チームメンバーは自分のエージェントからスキルを見つけて使用できます。Unity Gateway Skillsの発見と使用を参照してください。

GitHubリポジトリからスキルを公開する​

すでにGitHubを使用してスキルを管理している場合は、 Unityゲートウェイ スキル公開アクションを使用して、Unity Catalogの対応するスキルを作成および更新します。スキルを保持するリポジトリにワークフローを追加する権限が必要です。ワークフローは、変更が公開BranchにMergeされた後にGitHubランナーから公開します。Databricksノートブック、クラスター、またはスケジュールされたジョブは必要ありません。

ワークフローを設定できないアップストリームリポジトリについては、上級編: アップストリーム Git リポジトリの同期を参照してください。

公開アクセスをセットアップする​

Databricks管理者とGitHubリポジトリ管理者がこのセットアップを完了します。

  1. 公開Service Principalを作成または選択し、ターゲットワークスペースに割り当て、すべての宛先スキーマの要件でカタログおよびスキーマ権限を付与します。既存のスキルについては、READ VOLUMEおよびWRITE VOLUMEも付与します。新しいスキルは公開プリンシパルが所有するため、スキルを共有するユーザーまたはグループにすべての宛先スキーマでMANAGEを付与します。また、親カタログとスキーマに対してUSE CATALOGとUSE SCHEMAが必要です。スキーマ権限は、その子スキルに適用されます。特権の継承を参照してください。
  2. スキルリポジトリに production という名前の GitHub環境 を作成します。デプロイBranchを main 、または公開元とするBranchに制限します。
  3. 公開Service PrincipalでGitHubワークロードIDフェデレーションを設定します。スキルリポジトリとproduction環境の正確なOpenID Connect(OIDC)サブジェクトを一致させます。GitHubは短期間のIDトークンを発行し、Databricks SDKはそれをDatabricksアクセストークンと交換するため、GitHubにはDatabricksクライアントシークレットは保存されません。新しいリポジトリには、そのサブジェクトに数値の組織 ID とリポジトリ ID が含まれる場合があります。フェデレーションガイドに従って、リポジトリのサブジェクトとオーディエンスを構成します。
  4. [Settings] > [Environments] > [本番運用] > [環境変数] で、DATABRICKS_HOSTをワークスペースのベースURL、DATABRICKS_CLIENT_IDをService PrincipalのアプリケーションIDで追加します。どちらの値もシークレットではありません。
  5. ワークスペースに接続できるLinuxランナーを選択してください。この例では、GitHubホステッドランナーを使用します。プライベートネットワークまたはIPアクセスリストを使用するワークスペースでは、ネットワーク上のランナーが必要になる場合があります。

管理者の詳細手順およびOAuth Machine-to-Machineの代替案については、このアクションの認証ガイドをご覧ください。

例ではmainのアクションを参照しているため、最新のアップデートが取得されます。再現可能なワークフローにするには、アクション参照のmainをUnity Gatewayリポジトリのレビュー済みcommit SHAに置き換えてください。Unity Gateway CLIをインストールする必要はありません。

ワークフローを追加する​

  1. リポジトリにスキルを追加します。SKILL.mdを含むskillsの各直下フォルダがスキルになります。各フォルダのサポートファイルは次のとおりです:

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

    skills-directoryを使用する場合、フォルダのベース名によってUnity Catalogのスキル識別子が決まります:skills/sql-guideはacme.team_skills.sql-guideになります。SKILL.mdのnameは引き続き必須のスキルメタデータですが、このアクションではUnity Catalogの識別子を選択するために使用されません。わかりやすくするため、この例ではname: sql-guideを使用します。明示的なマッピングでは、フォルダのベース名ではなく、そのtarget値が使用されます。

    スキルコンテンツとフロントマターについては、「 スキルをローカルで開発する」を参照してください。

  2. 次の内容で .github/workflows/publish-skills.yml を作成します。acme.team_skills を既存のカタログとスキーマに置き換えます。公開する Branch またはソースフォルダーが異なる場合は、Branch とパスのフィルターも更新してください。

    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 }}

    これはskills/sql-guideをacme.team_skills.sql-guideに、skills/code-reviewをacme.team_skills.code-reviewにマッピングします。

  3. ワークフローとスキルをmainにMergeします。これにより、最初の公開がTriggerされます。公開前にプルリクエスト内のソースファイルを検証するには、アクションの検証ワークフローを追加します。ドライランは、Databricksに接続することなくローカルスキルフォルダーを検証します。認証、ネットワークアクセス、または権限はテストされません。production環境はmainのみを許可するため、mainから手動でドライランを実行し、検証ワークフローを使用して他のBranchをチェックしてください。

  4. GitHubで、 Actions > Publish skills to Databricks を開き、ランLogsを確認します。DatabricksでCatalog Explorerを開き、スキルがターゲットスキーマに表示されていることを確認します。ワークフローがmainに配置されたら、 [ワークフローをラン] を選択し、 [公開せずにフォルダーを検証] をオンにしてドライランを行うか、オフにして公開することもできます。

skills フォルダを変更する以降のMergeは、同じスキルに対してアップデートを発行します。既存の所有権と権限は保持されます。公開後、スキルの所有者、または MANAGE を持つプリンシパルが、チームメンバーにアクセス権を付与します。スキルを共有するをご覧ください。このアクションはコンシューマーアクセスを許可しません。消費者はスキーマのスキルをライブで読み込むことができます。

ソースフォルダを削除しても Unity Catalog スキルは削除されず、マッピングターゲットの名前を変更すると新しいスキルが作成され、古いスキルは保持されます。defaultでは、マップされたスキルにローカルフォルダに存在しないリモートファイルが含まれている場合、そのスキルの公開は変更をuploadする前に失敗し、それらのファイルはそのまま残されます。prune-files: 'true' を設定して、公開された各フォルダに存在しないリモートファイルを削除します。スキル更新はアトミックではないため、再試行する前に失敗したランを検査してください。

選択したフォルダーをスキル名にマッピングする​

カスタム名、skills以外のフォルダー、または複数の宛先スキーマの場合は、リポジトリのルートにskills.yamlマッピングファイルを追加します。

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

パブリッシングステップのskills-directoryとtarget-schemaを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 }}

ワークフローの paths フィルターを更新して、skills.yaml、マッピングされた各ソースフォルダー、およびワークフローファイルを含めます。公開プリンシパルに、マップされたすべての宛先へのアクセス権を付与します。追加のワークフロー設定については、アクションの例を参照してください。

高度な設定:アップストリームGitリポジトリを同期する​

チームが使用するサードパーティのリポジトリなど、ソースリポジトリに公開ワークフローを追加できない場合は、ノートブックアプローチを使用します。ワークスペース内の宛先スキーマとスケジュールされた同期を制御します。ソースリポジトリで GitHub Actions を構成できる場合は、「 GitHub リポジトリからスキルを公開する」を参照してください。

次のノートブックをDatabricksワークスペースにインポートし、git_url、catalog、schema、およびbranchウィジェット(プライベートリポジトリの場合はgit_credential_id)を設定し、スケジュールで実行します。これはリポジトリをクローンし、新しいスキルを作成し、変更されたスキルを更新します。これは削除を行わないため、リポジトリから削除されたスキルは、ドロップするまでスキーマに残ります。これはワークスペースの資格情報で実行され、ユーザーとして公開されます。

スキルの Git リポジトリを Unity Catalog スキーマに同期する

スキーマがこのように同期されると、コンシューマーはスキーマ全体をライブでロードでき、エージェントは公開された最新のスキルを取得できます。

リファレンス​

Unity Gateway CLI はオープンソースです。完全な最新のコマンドリファレンスについては、「Unity Gateway CLI リポジトリ」を参照してください。このチュートリアルで使用するコマンドは、上記の手順内にインラインで表示されています。

Skills MCPサーバーでサポートされているインターフェイスとクライアントの互換性については、「MCPを介したスキルのアクセス」を参照してください。スキルを共有するには、カタログエクスプローラーでそのスキルに対するREAD VOLUMEを付与します。「スキルの共有」を参照してください。

次のステップ​