databricks/databricks-agent-skills

Claude Code, Cursor, Codex, GitHub Copilot과 같은 AI 코딩 에이전트를 사용하여 Databricks에서 구축하세요.

이 저장소는 Databricks AI Tools를 위한 스킬(skills) 및 에이전트 플러그인(agent plugins)을 제공합니다. 스킬은 에이전트가 앱, 작업(jobs), 데이터 파이프라인을 구축하고, Lakebase 및 Model Serving과 작업하며, 선언적 자동화 번들(Declarative Automation Bundles)로 리소스를 배포하는 데 필요한 Databricks 전용 지침을 제공합니다. 플러그인은 지원되는 곳에 훅(hooks)과 명령(commands)을 추가합니다.

설정 및 관리형 MCP 서버와 함께 AI Tools를 사용하는 방법에 대한 자세한 내용은 Databricks AI Tools 문서를 참조하세요.

안정적인(stable) 스킬에는 두 가지 설치 경로가 있습니다. 이들은 서로 다른 위치에 설치되지만 동일한 에이전트에 의해 로드됩니다. 따라서 작업 흐름에 맞는 것을 선택하세요.

Databricks CLI는 SKILL.md 파일을 각 에이전트의 스킬 디렉터리(~/.claude/skills/, ~/.cursor/extensions/<...>, 등)에 직접 작성합니다. 플러그인 마켓플레이스(Claude Code, Cursor)는 플러그인을 에이전트의 플러그인 디렉터리(예: ~/.claude/plugins/cache/databricks-agent-skills/)에 캐시하며, 에이전트는 그곳에서 스킬을 발견합니다.

Databricks CLI를 통해 (표준 방식; 실험적 스킬 지원):

databricks aitools install

CLI는 코딩 에이전트를 자동으로 감지하고 안정적인 스킬을 올바른 위치에 설치합니다:

Claude Code → ~/.claude/skills/
Cursor, Codex CLI, OpenCode, GitHub Copilot, Antigravity → 각각의 스킬 디렉터리

더 세밀한 제어를 위해, aitools skills install 하위 명령을 직접 사용하세요. 이 명령어는 위치 기반의 스킬 이름과 --experimental 플래그를 받습니다 (실험적 스킬 섹션 참조).

Claude Code 플러그인 마켓플레이스를 통해 (안정적인 스킬만 — 모든 스킬을 ./skills/ 아래에 설치):

/plugin marketplace add databricks/databricks-agent-skills
/plugin install databricks@databricks-agent-skills

Cursor 플러그인 마켓플레이스를 통해:

/add-plugin databricks

Cursor 플러그인은 스킬과 함께 databricks-setup 및 databricks-doctor를 제공합니다.

명령어(commands)와 세 가지 후크 중 두 개(세션 컨텍스트, 인증 실패 힌트), 그리고 Databricks 프롬프트를 스킬로 안내하는 라우팅 규칙을 제공합니다. 자세한 내용은 명령 및 후크를 참조하세요.

GitHub Copilot 플러그인 마켓플레이스를 통해:

copilot plugin marketplace add databricks/databricks-agent-skills
copilot plugin install databricks@databricks-agent-skills

Copilot CLI(플러그인은 GA 버전)와 VS Code(에이전트 플러그인, 프리뷰; 확장 프로그램 보기에서도 설치 가능)에서 작동합니다. 스킬과 두 개의 후크를 제공합니다: 세션 컨텍스트 프라이머 및 인증 실패 힌터(둘 다 Copilot CLI 및 클라우드 에이전트에서 실행되며, VS Code는 자체 후크 시스템을 가집니다). github.com의 Copilot 클라우드 에이전트는 플러그인을 사용하지 않으므로, 해당 환경에서는 스킬을 대상 리포지토리(.github/skills/)에, 인증 힌트 후크를 .github/hooks/에 직접 제공해야 합니다.

Codex 플러그인 마켓플레이스를 통해:

codex plugin marketplace add databricks/databricks-agent-skills
codex plugin add databricks

Codex 플러그인은 스킬과 세 가지 후크(프롬프트 라우팅, 세션 컨텍스트, 인증 실패 힌트)를 모두 제공합니다. Codex는 해시 핀(hash-pins) 방식의 플러그인 후크를 사용하므로, 설치 후(및 업데이트 후 매번) /hooks를 실행하여 검토하고 활성화해야 합니다. Codex에는 배포 가능한 슬래시 명령어(slash commands)가 없으므로, setup/doctor 워크플로우는 해당 스킬을 통해 접근할 수 있습니다.

확신이 서지 않으면 CLI를 사용하세요. 이것이 표준 설치 경로이며 실험적 스킬을 노출하는 유일한 방법입니다.

skills/에서 제공되는 안정화된 스킬:

databricks-core: CLI, 인증(authentication), 프로필 선택(profile selection), 데이터 탐색을 위한 부모 스킬. 모든 제품 스킬의 기반입니다.databricks-data-discovery: Genie One을 통해 데이터를 찾고, 탐색하고, 쿼리합니다 (자연어 데이터 Q&A 및 SQL 생성). 수동 information_schema 탐색으로 폴백(fallback)됩니다.databricks-apps: AppKit을 사용하여 Databricks에서 풀스택 TypeScript 앱을 구축합니다.databricks-app-design: 데이터 앱의 UX를 설계합니다: 대시보드, KPI 페이지, 보고서, 차트 및 Genie/채팅 표면을 AppKit 구성 요소에 매핑합니다.databricks-dabs: Databricks 리소스를 배포하고 관리하기 위한 선언적 자동화 번들(Declarative Automation Bundles, 이전 명칭: Asset Bundles).databricks-jobs: Lakeflow Jobs 오케스트레이션: 작업 유형, 트리거, 스케줄, 알림.databricks-lakebase: Lakebase Postgres: 프로젝트, 브랜칭, 자동 확장(autoscaling), 동기화된 테이블, Data API.databricks-model-serving: 모델 서빙 엔드포인트 관리, AI Gateway, 트래픽 구성(traffic config).databricks-pipelines: 배치 및 스트리밍을 위한 Lakeflow Spark 선언적 파이프라인 (Declarative Pipelines, 이전 명칭: DLT).databricks-serverless-migration: 클래식 컴퓨트 워크로드를 서버리스 컴퓨트로 마이그레이션합니다.databricks-vector-search: RAG 및 시맨틱 검색을 위한 벡터 검색 엔드포인트와 인덱스.databricks-agent-bricks: 에이전트 브릭(Agent Bricks): 지식 비서(Knowledge Assistants), Genie Spaces, 다중 에이전트 감독자(Multi-Agent Supervisor).databricks-ai-functions: SQL 및 PySpark 내장 AI 함수 (ai_query, ai_classify, ai_extract, ai_parse_document, ai_forecast).databricks-aibi-dashboards: SQL 검증 워크플로우가 포함된 AI/BI 대시보드.databricks-apps-python: Python 데이터 앱(Streamlit, Dash, Gradio, Flask, FastAPI, Reflex); 신규 앱의 경우 AppKit을 선호합니다.databricks-dbsql: Databricks SQL 웨어하우스 패턴.databricks-docs: LLM을 통한 Databricks 문서 조회.txt.databricks-execution-compute: Databricks 컴퓨트에서 코드 실행.databricks-iceberg: Apache Iceberg 테이블 (관리형/외부), UniForm, Iceberg REST Catalog, 클라이언트

**interoperability.databricks-lakeflow-connect— Lakeflow Connect를 활용한 관리형 수집 커넥터.databricks-metric-views— 거버넌스된 메트릭을 위한 Unity Catalog Metric Views.databricks-ml-training— Databricks에서 ML 모델 훈련 수행.databricks-mlflow-evaluation— MLflow를 사용한 엔드투엔드 에이전트/GenAI 평가.databricks-python-sdk— Python SDK, Databricks Connect, CLI, REST API 제공.databricks-spark-structured-streaming— Spark Structured Streaming 패턴 구현.databricks-synthetic-data-gen— Faker를 사용한 현실적인 합성/테스트 데이터 생성.databricks-unity-catalog— 계보(lineage), 감사(audit), 청구(billing)를 위한 Unity Catalog 시스템 테이블 제공.databricks-unstructured-pdf-generation— RAG를 위한 합성 PDF 생성.databricks-zerobus-ingest— Zerobus 스트리밍 수집 패턴 구현.

The experimental/ 디렉터리는 다음에서 가져온 추가 스킬을 포함합니다:
원래는 databricks-solutions/ai-dev-kit 에서 임포트되었으나, 현재는 더 이상 사용되지 않으며(deprecated) — 앞으로 이 레포지토리가 진실의 원천(source of truth)입니다.

• Experimen

/databricks:setup [workspace-url]

: auth/onboarding. 설치 확인 후, OAuth / PAT / 서비스 주체(service-principal) 프로필을 설정하고 검증합니다./databricks:doctor [profile]`

: 읽기 전용 상태 확인 (CLI 버전, 인증, 워크스페이스 도달 가능성, 컴퓨팅 자원, 최근 작업 실패).

(앱, 작업(jobs), 파이프라인, DABs 등과 같은 제품 워크플로우는 명령어(commands)가 아닌 스킬(skills)에 의해 처리되므로 여기에 중복되지 않았습니다.)

훅(Hooks) (hooks/, 모두 fail-open):

프롬프트 라우터(UserPromptSubmit): 각 프롬프트에 대해 빠른 키워드 정규 표현식 검색을 수행합니다 (50ms 미만, LLM 사용 안 함, 네트워크 연결 없음). 프롬프트가 Databricks 관련일 경우, Claude에게 databricks-core를 로드하도록 유도하는 메모와 일치하는 제품 스킬을 답변 전에 주입합니다. 전체 메모는 세션당 한 번 발동하며, 이후의 Databricks 프롬프트에는 한 줄짜리 알림이 표시됩니다. 관련 없는 프롬프트는 건드리지 않습니다. 권한 게이팅이나 비용 경고가 없습니다.컨텍스트 프라이머(SessionStart, 재개 시 생략): 라우팅 규칙, CLI 버전, 구성된 프로필 이름 및 모든 [__settings__].default_profile (로컬에서 읽으며 네트워크 호출이나 토큰 값 없음), 그리고 환경/플랫폼 내 인증 상태를 주입합니다.인증 실패 힌트(PostToolUse on Bash): databricks 명령어가 인증 관련 오류와 함께 실패할 경우, 재시도하기 전에 /databricks:doctor 또는 databricks auth login을 제안하는 한 줄을 추가합니다. 명령어를 차단하거나 다시 작성하지는 않습니다.

커서(Cursor). 커서는 평평한 / 메뉴를 가지고 있어 (plugin:command 네임스페이스가 없음), 동일한 명령어들이 /databricks-setup과 /databricks-doctor로 제공되며, 이는 단일 템플릿화된 commands/ 소스에서 Cursor 번들 폴더로 렌더링됩니다. 커서 방언(Cursor-dialect) 훅 와이어링은 Cursor 번들 폴더의 hooks/hooks.json으로 전송됩니다 (플러그인 루트에서 자동 발견되며, 선언이 필요 없음): 컨텍스트 프라이머 (sessionStart)와 인증 실패 힌트 (postToolUse) 모두 --platform cursor로 호출되어 Cursor의 출력 형태를 방출하고 Cursor 명령어 이름을 참조합니다. 프롬프트 라우터 훅은 포팅되지 않습니다 (Cursor의 beforeSubmitPrompt).

컨텍스트를 주입할 수 없기 때문에 라우팅 대신 Cursor 규칙(rules/databricks-routing.mdc)으로 제공되며, 이 규칙은 프롬프트가 Databricks 관련일 때 라우팅 테이블을 주입합니다. 이는 현재 additional_context 훅을 누락하는 Cursor의 버그와는 별개입니다. 네이티브 스킬 선택 기능도 도움이 됩니다.

배포 파리티(후속 작업). 플러그인 마켓플레이스는 전체 레포지토리(marketplace.json source: "./")를 제공하므로, 명령어와 훅이 함께 제공됩니다. 현재 databricks aitools install은 skills/만 패키징하기 때문에, CLI-install 사용자는 아직 명령어/훅을 얻지 못합니다. 이 격차를 해소하는 작업은 CLI 측 작업으로 추적되고 있습니다.

각 스킬은 Agent Skills Specification을 따릅니다:

skill-name/
├── SKILL.md # 프론트매터 + 명령어 포함 메인 스킬 파일
└── references/ # 필요할 때 로드되는 추가 문서

기존 스킬의 더 좁은 변형을 위해서는, 프론트매터를 통해 부모를 선언하는 서브스킬을 생성합니다. 이것이 현재 안정적인 스킬들이 구성되는 방식입니다—각 제품 스킬은 parent: databricks-core를 설정합니다.

---
name: "databricks-apps-chatbots"
description: "채팅봇 기능을 갖춘 Databricks 앱"
...

이 접근 방식은 다음과 같습니다:

• 메인 스킬을 안정적이고 집중적으로 유지합니다.
• 핵심 스킬을 수정하지 않고 실험을 허용합니다.
• 메인 스킬의 변경 사항을 쉽게 추적할 수 있게 합니다.

manifest.json은 스킬 디렉토리와 프론트매터로부터 scripts/skills.py에 의해 생성됩니다. 손으로 편집하지 마십시오. CI는 두 가지 검사를 통해 수동 변경을 거부합니다: 콘텐츠 드리프트(파싱된 딕셔너리가 generate가 생성할 내용과 일치하지 않음) 및 표준 형식(디스크 상의 바이트가 json.dumps(..., indent=2, sort_keys=True)와 일치하지 않음).

CLI가 manifest.json을 읽고 플러그인 설치가 main에서 생성된 카탈로그와 프로바이더 번들을 실시간으로 읽기 때문에, main은 릴리스 간에 자체 소스에 대한 일관된 인덱스로 유지되어야 합니다. .github/workflows/self-heal-manifest.yml이 이를 강제합니다: main에 푸시될 때마다 생성 입력물에 영향을 주는 경우 scripts/skills.py generate를 다시 실행합니다.

그리고 갱신된 manifest.json을 커밋합니다.

플러그인, 카탈로그(catalogs), hook/라우팅 파일, 그리고 프로바이더 번들(provider bundle)을 main 브랜치로 되돌립니다.

따라서 하나의 PR에서 스킬이 추가되거나 삭제되거나 재구성되어도 설치 과정에서 누락된 파일을 가져오는 문제가 발생하지 않습니다. 따라서 PR별 커밋된 매니페스트 확인은 권고 사항일 뿐입니다 (단순히 main 브랜치로부터 상속받았을 경우에도 오래되었음을 보여줄 뿐, PR 자체를 차단하지는 않습니다).

스킬을 추가하거나 업데이트한 후 에셋(assets)을 동기화하고 매니페스트를 재생성합니다:

python3 scripts/skills.py

에셋과 매니페스트가 최신 상태인지 검증합니다 (CI에서 사용됨):

python3 scripts/skills.py validate

커밋된 매니페스트가 리포지토리(repo)에 존재하는 파일을 가리키는지 여부만 확인합니다:

python3 scripts/skills.py validate-committed-manifest