# Использование навыков в dbt Wizard CLI [Бета-версия](https://docs.getdbt.tech/docs/dbt-versions/product-lifecycles "Подробнее о статусе или тарифе")

Локальная разработка

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

dbt Wizard также включает встроенные навыки из [dbt Agent skills](https://github.com/dbt-labs/dbt-agent-skills), которые поддерживает dbt Labs. Они всегда доступны и не требуют настройки.

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

Сведения об общем контексте проекта (`AGENTS.md`, `CLAUDE.md`) см. в разделе [Переход на dbt Wizard](https://docs.getdbt.tech/docs/dbt-ai/wizard-migrate.md) — dbt Wizard читает эти файлы инструкций без дополнительной настройки.

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

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

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

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

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

Пользовательские навыки используют формат [Agent Skills](https://agentskills.io/specification) — тот же формат, что и [dbt Agent Skills](https://github.com/dbt-labs/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](https://github.com/dbt-labs/dbt-agent-skills) | Встроенные   | Нет. Поставляются с dbt Wizard.                                        | Самый низкий.                                                                                                                                    |

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

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

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

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

Чтобы включить эту возможность, задайте для `ai_provider` одно из значений из [списка поддерживаемых провайдеров](https://docs.getdbt.tech/docs/dbt-ai/package-skills.md?version=2#set-the-ai_provider-flag). Если вы используете Wizard, задайте для `ai_provider` значение `wizard` в корневом проекте:

dbt\_project.yml

```yml
flags:
  ai_provider: wizard
```

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

Полное описание настройки, включая поставку навыков в пакете, отключение ненужных навыков, примеры и другие сведения, см. в разделе [Установка навыков агента из пакетов dbt](https://docs.getdbt.tech/docs/dbt-ai/package-skills.md).

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

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

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

Затем напишите файл навыка. Дополнительные сведения см. в следующем разделе [Формат файла навыка](#skill-file-format). Чтобы применить изменения, начните новый сеанс `wizard`. Навыки обнаруживаются в начале сеанса, и изменения, внесённые во время сеанса, не будут учтены до его перезапуска.

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

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

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

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

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

```markdown
---
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`](https://github.com/dbt-labs/dbt-agent-skills/blob/main/skills/dbt/skills/adding-dbt-unit-test/SKILL.md).

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

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

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

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

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

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

```text
Use my-team-style to refactor fct_orders.
```

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

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

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

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

\~/.agents/skills/

```text
personal-defaults/
SKILL.md
```

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

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

dbt Wizard поставляется с навыками из [dbt Agent Skills](https://github.com/dbt-labs/dbt-agent-skills), которые поддерживают dbt Labs и сообщество. В них собраны знания в области аналитической инженерии для типовых рабочих процессов, и они всегда доступны. Агент автоматически загружает подходящий навык, когда ваш запрос соответствует его сценарию использования.

Все перечисленные ниже навыки входят в состав dbt Wizard. Вам не нужно вызывать их напрямую: агент загружает тот, который лучше всего соответствует вашему запросу. Сведения об установке в других ИИ-клиентах, добавлении новых навыков и актуальный каталог см. в [репозитории dbt Agent Skills](https://github.com/dbt-labs/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](https://docs.getdbt.tech/docs/dbt-ai/package-skills.md?version=2) и установите его с помощью `dbt deps`. См. раздел [Навыки из пакетов dbt](https://docs.getdbt.tech/docs/dbt-ai/package-skills.md?version=2). Для личных навыков, которые нужны во всех ваших локальных проектах, используйте \~/.agents/skills/.

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

* [dbt Wizard в Studio IDE](https://docs.getdbt.tech/docs/dbt-ai/wizard-ide.md)
* [Использование навыков в dbt platform](https://docs.getdbt.tech/docs/dbt-ai/wizard-platform-skills.md)
* [Установка навыков агента из пакетов dbt](https://docs.getdbt.tech/docs/dbt-ai/package-skills.md)
* [Как работает dbt Wizard](https://docs.getdbt.tech/docs/dbt-ai/wizard-how-it-works.md)
* [Обзор dbt Wizard CLI](https://docs.getdbt.tech/docs/dbt-ai/wizard-cli.md)