Использование навыков в dbt Wizard CLI Бета-версия

Навыки — это многократно используемые инструкции, которые помогают dbt Wizard соблюдать принятые в вашей команде соглашения по SQL, правила именования, шаблоны моделирования и рабочие процессы без необходимости повторять их в каждом запросе.

dbt Wizard также включает встроенные навыки из dbt Agent skills, которые поддерживает dbt Labs. Они всегда доступны и не требуют настройки.

При инициализации dbt Wizard в проекте он также может обнаружить существующие навыки Claude Code в текущем каталоге.

Сведения об общем контексте проекта (AGENTS.md, CLAUDE.md) см. в разделе Переход на dbt Wizard — dbt Wizard читает эти файлы инструкций без дополнительной настройки.

Расположения и приоритет

В начале каждого сеанса dbt Wizard ищет навыки уровня проекта в .agents/skills/, начиная с корневого каталога проекта dbt и заканчивая текущим рабочим каталогом:

.agents/
  skills/
    your-skill-name/
      SKILL.md

Сообщить об ошибке в коде

CLI также обнаруживает навыки уровня пользователя в ~/.agents/skills/, навыки Claude Code уровня пользователя в ~/.claude/skills/ и навыки Claude Code уровня проекта в .claude/skills/.

.claude/
  skills/
    your-skill-name/
      SKILL.md

Сообщить об ошибке в коде

Пользовательские навыки используют формат Agent Skills — тот же формат, что и dbt Agent Skills на GitHub. Файл навыка содержит блок метаданных YAML (name, description) и основной текст с инструкциями в формате Markdown.

В следующей таблице перечислены расположения, в которых dbt Wizard ищет навыки. Для новых навыков используйте предназначенные для них расположения, а расположения для совместимости сохраняйте только при переносе существующей конфигурации. Среди расположений уровня проекта текущий рабочий каталог имеет приоритет над родительскими каталогами. Навыки уровня проекта имеют приоритет над навыками уровня пользователя и встроенными навыками.

Расположение	Уровень	Использовать для новых навыков?	Приоритет
.agents/skills/NAME/SKILL.md	Проект	Да. Используйте для навыков, общих для репозитория или подкаталога.	Наивысший приоритет среди расположений навыков проекта; каталоги, более близкие к текущему рабочему каталогу, имеют приоритет над родительскими.
~/.agents/skills/NAME/SKILL.md	Пользователь	Да. Используйте для навыков, которые нужны во всех локальных проектах.	Ниже навыков проекта, выше импортируемых для совместимости и встроенных навыков.
.claude/skills/NAME/SKILL.md	Проект	Нет. Импорт существующих навыков Claude Code для совместимости.	Ниже предназначенных для навыков расположений уровня проекта и пользователя.
~/.claude/skills/NAME/SKILL.md	Пользователь	Нет. Импорт существующих навыков Claude Code для совместимости.	Ниже предназначенных для навыков расположений уровня проекта и пользователя.
Встроенные dbt Agent Skills	Встроенные	Нет. Поставляются с dbt Wizard.	Самый низкий.

Избегайте одинаковых имён навыков в разных расположениях. Если нужно заменить встроенный или импортированный навык, создайте замену в предназначенном для навыков расположении уровня проекта или пользователя и удалите либо переименуйте старую копию.

Навыки из пакетов dbt

(Версии dbt: v2.0 и новее)

В dbt v2 пакет dbt может содержать навыки, а dbt deps устанавливает их в каталог, из которого ваш агент для работы с кодом читает навыки.

Чтобы включить эту возможность, задайте для ai_provider одно из значений из списка поддерживаемых провайдеров. Если вы используете Wizard, задайте для ai_provider значение wizard в корневом проекте:

dbt_project.yml

flags:
  ai_provider: wizard

Сообщить об ошибке в коде

Используйте wizard независимо от того, предоставляете ли вы собственный ключ или используете управляемый ИИ.

Полное описание настройки, включая поставку навыков в пакете, отключение ненужных навыков, примеры и другие сведения, см. в разделе Установка навыков агента из пакетов dbt.

Создание навыка

Выполните в терминале следующие команды, чтобы создать папку и файл навыка:

mkdir -p .agents/skills/my-team-style
touch .agents/skills/my-team-style/SKILL.md

Сообщить об ошибке в коде

Затем напишите файл навыка. Дополнительные сведения см. в следующем разделе Формат файла навыка. Чтобы применить изменения, начните новый сеанс wizard. Навыки обнаруживаются в начале сеанса, и изменения, внесённые во время сеанса, не будут учтены до его перезапуска.

Формат файла навыка

Файл навыка состоит из двух обязательных частей: блока метаданных YAML и основного текста в формате Markdown.

• Блок метаданных: содержит как минимум name и description. Поле description особенно важно: по нему dbt Wizard определяет, когда автоматически применять навык.
• Основной текст: разделы Markdown, объясняющие, когда использовать навык, что он делает и какие соглашения или ограничения нужно соблюдать.
• Справочные материалы (необязательно): вспомогательные файлы .md в подпапке references/ с подробностями, которые сделали бы SKILL.md слишком длинным.

Пример файла навыка

Если вы только начинаете работать с навыками, создайте небольшой SKILL.md, как в следующем примере, и постепенно дополняйте его:

---
name: my-team-style
description: Apply Santi Corp's modeling conventions when editing or creating dbt models. Use when the user asks for refactors, new models, or YAML in this project.
---

# My team style

## When to use

Use this skill whenever you are changing SQL or YAML under `models/` and the user did not override these rules.

## Conventions

- Staging models use prefix `stg_` and live in `models/staging/`.
- Facts and dimensions use `fct_` and `dim_` prefixes respectively.
- Document new columns in the same PR as the model change.

## Optional detail

For edge cases, read `references/naming-conventions.md` in this skill folder before proposing renames.

Сообщить об ошибке в коде

Полноценный пример для практического использования см. в навыке dbt adding-dbt-unit-test.

Структура папок

.agents/
  skills/
    my-team-style/
      SKILL.md                      ← обязательно
      references/                   ← необязательно: дополнительные сведения, которые Wizard загружает при необходимости
        naming-conventions.md
        sql-patterns.md

Сообщить об ошибке в коде

Подпапка references/ предназначена для вспомогательных материалов, которые сделали бы SKILL.md слишком длинным. dbt Wizard читает справочные файлы, когда навык активен и задача связана с их содержимым.

Использование навыка

dbt Wizard применяет навыки автоматически, когда обнаруживает соответствие между полем description навыка и вашей задачей. Вы также можете явно вызвать навык:

Укажите имя навыка в запросе:

Use my-team-style to refactor fct_orders.

Сообщить об ошибке в коде

Или укажите файл напрямую с помощью @:

@.agents/skills/my-team-style/SKILL.md — apply these conventions to the new model.

Сообщить об ошибке в коде

Глобальные навыки (только CLI)

Если вы используете CLI, вы можете хранить навыки в ~/.agents/skills/, чтобы они были доступны во всех ваших проектах dbt. Это удобно для личных соглашений, которые вы хотите применять повсюду:

~/.agents/skills/

personal-defaults/
SKILL.md

Сообщить об ошибке в коде

Если навык проекта и глобальный навык имеют одинаковое имя, приоритет имеет навык проекта.

Встроенные навыки dbt

dbt Wizard поставляется с навыками из dbt Agent Skills, которые поддерживают dbt Labs и сообщество. В них собраны знания в области аналитической инженерии для типовых рабочих процессов, и они всегда доступны. Агент автоматически загружает подходящий навык, когда ваш запрос соответствует его сценарию использования.

Все перечисленные ниже навыки входят в состав dbt Wizard. Вам не нужно вызывать их напрямую: агент загружает тот, который лучше всего соответствует вашему запросу. Сведения об установке в других ИИ-клиентах, добавлении новых навыков и актуальный каталог см. в репозитории dbt Agent Skills.

Навык	Что делает
using-dbt-for-analytics-engineering	Создаёт и изменяет модели dbt, помогает устранять ошибки, исследовать источники данных и писать тесты
adding-dbt-unit-test	Добавляет модульные тесты для моделей dbt; помогает применять разработку через тестирование
building-dbt-semantic-layer	Создаёт семантические модели, метрики и измерения с помощью MetricFlow
answering-natural-language-questions-with-dbt	Отвечает на бизнес-вопросы, выполняя запросы к семантическому слою
working-with-dbt-mesh	Реализует управление в dbt Mesh и взаимодействие между проектами
troubleshooting-dbt-job-errors	Диагностирует и устраняет сбои заданий на платформе dbt
configuring-dbt-mcp-server	Настраивает сервер dbt MCP для Claude, Cursor или VS Code
fetching-dbt-docs	Помогает эффективно находить сведения в документации dbt
running-dbt-commands	Выполняет команды dbt CLI с правильными флагами, селекторами и форматами параметров

Миграция (разовое использование)

Эти навыки предназначены для проектов миграции, а не для повседневных сеансов:

Навык	Что делает
migrating-dbt-core-to-v2	Переносит проекты dbt с dbt v1 на dbt v2
migrating-dbt-project-across-platforms	Переносит проекты dbt между платформами данных

Встроенные навыки обновляются с каждым выпуском dbt Wizard. Пользовательские навыки с тем же именем имеют приоритет.

Советы

• Не перегружайте SKILL.md. Один навык должен решать одну задачу (руководство по стилю, соглашения о тестировании, процесс развёртывания). Небольшие навыки загружаются надёжнее, чем крупные монолитные.
• Используйте description, чтобы управлять тем, когда dbt Wizard активирует навык. Точное описание («Используйте при создании или редактировании моделей в models/marts/») позволяет активировать навык по необходимости, а не при каждом запросе.
• Начинайте новый сеанс после добавления или редактирования навыка. Навыки обнаруживаются в начале сеанса — изменения, внесённые во время сеанса, не учитываются, пока вы не начнёте новый чат.
• Используйте общие навыки в разных проектах: чтобы использовать общие навыки в разных проектах в v2, добавьте их в пакет dbt и установите его с помощью dbt deps. См. раздел Навыки из пакетов dbt. Для личных навыков, которые нужны во всех ваших локальных проектах, используйте ~/.agents/skills/.

Связанная документация

• dbt Wizard в Studio IDE
• Использование навыков в dbt platform
• Установка навыков агента из пакетов dbt
• Как работает dbt Wizard
• Обзор dbt Wizard CLI

Нашли ошибку?

Создать GitHub Issue