Субагенты, скиллы
и команды в Cursor

Содержание гайда

Четыре механизма расширения, не три

В Cursor 2.4+ есть четыре разных способа расширить поведение агента. Их часто путают, потому что они все живут в папке .cursor/ и все основаны на Markdown-файлах. Но работают они по-разному и решают разные задачи.

Изолированные исполнители подзадач

Субагент — это самостоятельный агент с собственным окном контекста, который Cursor вызывает для решения отдельной части задачи. Главный агент остаётся оркестратором и видит только финальный результат.

Зачем нужны субагенты

Структура файла субагента

Каждый субагент — это Markdown-файл в .cursor/agents/ с YAML-фронтматтером и промптом.

---
name: security-auditor
description: Security specialist. Use when implementing auth, payments, or handling sensitive data.
model: inherit
readonly: true
background: false
---

Ты — эксперт по безопасности, который проверяет код на уязвимости.

При вызове:
1. Найди security-чувствительные пути в коде
2. Проверь на типичные уязвимости (SQL-инъекции, XSS, обход авторизации)
3. Убедись, что секреты не захардкожены
4. Проверь валидацию и санитизацию входных данных

Результат структурируй по уровню критичности:
- Critical (исправить до деплоя)
- High (исправить в ближайшее время)
- Medium (можно отложить)

Поля фронтматтера

Три встроенных субагента

Cursor поставляется с тремя субагентами «из коробки» — их не нужно настраивать. Они автоматически срабатывают для своих задач и помогают разгрузить главный контекст.

Способы вызова кастомных субагентов

1. Автоматически. Cursor читает description и решает делегировать. Полезные фразы для триггера: «Use proactively», «Always use for X».
2. Явно через слэш: /security-auditor проверь модуль платежей
3. Естественным языком: «Используй субагента verifier, чтобы убедиться, что миграции отработали»
4. Параллельно: «Проверь API и обнови документацию параллельно» — Cursor отправит несколько Task-вызовов одним сообщением.

Resume — продолжение разговора с субагентом

Каждый запуск субагента возвращает agent ID. Можно вернуться к нему позже:

Resume agent abc123 and analyze the remaining test failures

Background-субагенты пишут своё состояние в ~/.cursor/subagents/ по мере работы — родитель может читать эти файлы, чтобы следить за прогрессом.

Trade-off: что взамен

Динамические навыки агента

Skill — это переносимый, версионируемый пакет, который учит агента делать domain-specific задачи. Скилл может включать скрипты, шаблоны и референсы — всё, что подгружается на лету, когда агент решит, что навык релевантен.

Структура папки скилла

.cursor/skills/deploy-app/
├── SKILL.md           // обязательный файл
├── scripts/           // опционально, любой исполняемый код
│   ├── deploy.sh
│   └── validate.py
├── references/        // доп. документация on-demand
│   └── REFERENCE.md
└── assets/            // шаблоны, картинки, JSON
    └── config-template.json

Прогрессивная загрузка: основной SKILL.md короткий, тяжёлые референсы Cursor подтянет только когда понадобятся.

Фронтматтер скилла

---
name: deploy-app
description: Deploy the application to staging or production. Use when deploying code or when the user mentions deployment, releases, or environments.
disable-model-invocation: false
---

# Deploy App

Развёртывание приложения через скрипты.

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

Запусти скрипт деплоя: `scripts/deploy.sh <environment>`
Где `<environment>` — это `staging` или `production`.

## Pre-deployment валидация

Перед деплоем запусти `python scripts/validate.py`

Где Cursor ищет скиллы

• .cursor/skills/ — проектные
• .agents/skills/ — проектные (универсальный путь)
• ~/.cursor/skills/ — глобальные пользовательские
• Также читаются .claude/skills/ и .codex/skills/ для совместимости

Когда ставить disable-model-invocation: true

По умолчанию агент сам решает, применять скилл или нет, читая его description. Это удобно для скиллов общего назначения — типа «как написать README» или «как поправить миграцию».

Но для скиллов-оркестраторов (которые описывают цепочку шагов с субагентами) автоприменение часто мешает. Ты хочешь запускать пайплайн только через явную команду — тогда ставь disable-model-invocation: true и подключай через /имя-скилла.

Быстрые промпты на каждый день

Команда — это самый простой механизм расширения. Markdown-файл в .cursor/commands/, его содержимое становится промптом, когда ты вводишь /имя в чате.

Главное отличие от скилла

Простейшая команда

# /pr — создать pull request

Создай pull request для текущих изменений.

1. Посмотри staged и unstaged изменения через `git diff`
2. Напиши понятное сообщение коммита по изменениям
3. Закоммить и запушь в текущую ветку
4. Используй `gh pr create`, чтобы открыть PR с описанием
5. Верни URL созданного PR

Никакого фронтматтера. Просто промпт. Файл сохранил → ввёл /pr в чате → агент выполнил.

Команда + субагенты = пайплайн

Связка из практики: команда запускает скилл-оркестратор, который описывает цепочку субагентов. Так устроен, например, мой пайплайн новостей:

# /новости — запуск пайплайна публикации

Выполни navigate `news-post-pipeline` (см. @news-post-pipeline).

Каждый шаг 1–6 — отдельный вызов Task с subagent_type из таблицы навыка.
НЕ используй generalPurpose — иначе модели из карточек субагентов не подхватятся.

Нужны: 4 текста и 4 картинки. Дождись выбора пользователя, затем публикация.

Когда вводишь /новости @news-post-pipeline — агент получает текст команды + текст скилла одним пакетом. В скилле прописаны имена субагентов, их обязанности и схемы handoff. Дальше агент сам играет роль оркестратора.

Что выбрать в поле model:

Это самая практическая часть. Здесь у большинства гайдов в интернете путаница — потому что Cursor часто меняет названия моделей в UI быстрее, чем обновляет публичную документацию.

Что показывает дропдаун в редакторе субагента

Когда ты создаёшь субагент через UI Cursor, в селекторе «Model» ты видишь не «все модели в природе», а только то, что доступно в твоём аккаунте с твоими настройками видимости.

Что писать в YAML-фронтматтере

В файле субагента можно использовать три типа значений в поле model:

Два пула расхода — это важно знать

У каждого тарифа есть два разных бюджета, которые сбрасываются раз в месяц:

Архитектурный вывод: тяжёлые шаги пайплайна на конкретных моделях ест API-pool, простые шаги с model: inherit или Auto/Composer — практически не тратят бюджет.

Пример распределения моделей по шагам пайплайна

Главные ошибки, которые ломают пайплайн

Ловушка 1: generalPurpose вместо имени

Самая распространённая ошибка. Когда Cursor вызывает Task без точного subagent_type, он использует generalPurpose — встроенный fallback. Что в этом случае происходит:

• Файл .cursor/agents/news-candidate-hunter.md не открывается
• Поле model: gemini-3.1-pro не применяется
• В UI и биллинге увидишь не ту модель, которую прописал

Task(subagent_type="generalPurpose", prompt="Ты — news-candidate-hunter, найди новости...")

Task(subagent_type="news-candidate-hunter", prompt="Найди новости за 24–72 часа...")

Ловушка 2: устаревшее поле is_background

В старых гайдах из 2025 года часто встречается is_background: true. В актуальной документации (Cursor 2.4+) поле называется просто background. Старое имя не сработает — субагент будет запускаться в foreground независимо от значения.

Ловушка 3: несуществующие ID моделей

Cursor часто меняет названия и версии моделей. Если в YAML прописано composer-1.5, а в твоём UI модель называется «Composer 2» — может быть, что это та же модель под новым именем, а может быть, что Cursor молча падает на дефолт.

Ловушка 4: вложенные субагенты

Субагент не может запустить другого субагента. Если в твоей архитектуре оркестратор — это субагент, и он должен дёргать ещё несколько ролей — пайплайн просто не запустится. Оркестратор всегда должен быть основным агентом Cursor.

Ловушка 5: автоматическое применение скилла-оркестратора

Если у скилла-пайплайна не стоит disable-model-invocation: true, агент может попытаться применить его в случайном моменте — например, когда юзер просто спросил «как у тебя настроен пайплайн». Скилл-оркестратор должен запускаться только явно — через /имя.

Чеклист: «почему субагент не слушается»

Скопируй и подставь свои значения

Эти три шаблона — минимальный комплект для запуска собственного пайплайна. Создай папку .cursor/ в корне проекта, положи файлы в нужные подпапки, замени значения в квадратных скобках на свои.

Шаблон 1 — Скилл-оркестратор

---
name: мой-пайплайн
description: >-
  Краткое описание: что делает, какие команды его запускают.
disable-model-invocation: true
---

# Мой пайплайн (оркестратор)

## Итог

[Опиши, что должно получиться на выходе]

## Обязательный вызов субагентов через Task

Каждый шаг — ТОЛЬКО через инструмент Task.
- `subagent_type` = точное значение `name` из таблицы ниже
- ЗАПРЕЩЕНО использовать `generalPurpose` для замены ролей
- `prompt` — только входные данные шага, не копировать инструкцию из .md субагента

## Субагенты

| Шаг | Файл | name | Назначение |
|-----|------|------|------------|
| 1 | `мой-шаг-один.md` | мой-шаг-один | [что делает] |
| 2 | `мой-шаг-два.md` | мой-шаг-два | [что делает] |

## Схемы данных между шагами

### После шага 1 → шагу 2
```json
{ "поле": "значение" }
```

## Зоны ответственности

- [Что делает оркестратор сам, что — субагенты]
- [Что запрещено делать без явного согласия пользователя]

Шаблон 2 — Субагент

---
name: мой-шаг-один
model: claude-sonnet-4-6
description: [Что делает; когда главный агент должен его вызвать]
readonly: false
background: false
---

Ты — субагент [роль].

## Вход

[Опиши, что субагент получает на вход]

## Задача

1. [Шаг 1]
2. [Шаг 2]

## Выход

### HANDOFF → следующий-субагент

```json
{ "поле": "значение" }
```

Шаблон 3 — Команда запуска

# моя-команда — запуск пайплайна

## Результат

[Что должно получиться]

## Делегирование (обязательно)

Каждый шаг — отдельный Task с subagent_type из навыка.
НЕ используй generalPurpose для замены ролей.

## Стартовая формулировка

Выполни [название навыка]. На шагах вызывай Task с subagent_type:
- мой-шаг-один
- мой-шаг-два

После каждого шага показывай мне результат для проверки.

Как начать новый проект пошагово

1. Опиши пайплайн на бумаге. Что на входе, что на выходе, сколько шагов, где можно параллелить.
2. Создай файлы субагентов в .cursor/agents/: один файл = один шаг. Прописывай name, model, description, readonly, background.
3. Подбирай модели по сложности шага. Простые шаги → Auto / Composer 2 / inherit. Сложные креативные шаги → Sonnet 4.6 / Opus 4.7. Веб-поиск → Gemini 3.1 Pro. Классификация → Gemini 3 Flash.
4. Создай скилл-оркестратор в .cursor/skills/имя/SKILL.md: таблица субагентов, правило вызова через Task, схемы handoff между шагами.
5. Создай команду в .cursor/commands/имя.md: правило делегирования + стартовая формулировка.
6. Открой проект в Cursor от корневой папки (там, где лежит .cursor/).
7. Первый запуск: в чате /моя-команда @мой-навык — добавь в первое сообщение фразу «вызывай Task с subagent_type из таблицы, не используй generalPurpose».
8. Проверь UI: у каждого шага должна быть видна своя модель — это признак того, что карточки субагентов реально применяются.

Ты работаешь над проектом, в котором используется архитектура Cursor 2.4+ с субагентами, скиллами и командами.

Ключевые правила, которые нельзя нарушать:

1. Субагенты живут в .cursor/agents/*.md с YAML-фронтматтером.
   Поля: name, description, model, readonly, background.
   Поле background, не is_background.

2. Скиллы живут в .cursor/skills//SKILL.md.
   Скилл-оркестраторы должны иметь disable-model-invocation: true.

3. Команды живут в .cursor/commands/*.md, фронтматтер не обязателен.

4. Вызов субагентов всегда через инструмент Task.
   subagent_type = точное значение name из карточки.
   НЕ использовать generalPurpose для замены ролей — карточка не подключится.

5. В model можно указать: inherit, fast, либо точный ID модели
   (composer-2, claude-sonnet-4-6, claude-opus-4-7, gemini-3.1-pro,
    gemini-3-flash, gpt-5.4, codex-5.3 и т.д.)
   Точный ID лучше брать через UI Cursor (выбрать в дропдауне → сохранить → посмотреть YAML).

6. Каждый субагент возвращает JSON по чёткой схеме handoff.
   Следующий шаг получает этот JSON на вход.

7. Субагенты — однослойные. Субагент не может запустить другой субагент.
   Оркестратор — всегда основной агент Cursor, не субагент.

Когда я опишу задачу — учитывай эти правила при генерации файлов конфигурации.

Частые вопросы

Чем субагент отличается от скилла?

Субагент — отдельное окно контекста и своя модель, вызывается через Task. Скилл — инструкция, которую основной агент подгружает по ситуации, без отдельного изолированного чата.

Нужен ли фронтматтер у команды?

Не обязателен: команда — это в первую очередь текст, который подставляется после /имя. Скиллы и субагенты как раз опираются на YAML-шапку.

Можно ли вызывать субагента из субагента?

Короткий ответ: в модели «один слой» оркестратор — основной агент Cursor; вложенные Task из субагента недоступны. Декомпозицию делайте шагами у оркестратора.