О чём этот гайд? Короткий ответ
Короткий ответ: Что такое субагенты в Cursor, зачем они нужны, как оформить файл в .cursor/agents/ и чем субагент отличается от скилла и команды — пошагово для новичков.
Субагенты в Cursor: что это и как создать своих
Что такое субагенты, зачем нужны параллельные помощники, как создать своих — и чем они отличаются от скиллов и команд
Субагент в Cursor — это отдельный ИИ-помощник со своим контекстом, которого основной агент может запускать параллельно с другими задачами. Он описывается Markdown-файлом с YAML-шапкой в папке .cursor/agents/ и подходит для сложных задач, где нужна изоляция и специализация, в отличие от skills (общая инструкция) и commands (короткий сценарий по /).
Что такое субагенты
Короткий ответ: субагент — это отдельный ИИ-помощник со своим контекстом, которого основной агент может запустить для узкой задачи, в том числе параллельно другим субагентам.
Субагент (Subagent) — это независимый ИИ-помощник, которого основной агент может запустить для выполнения конкретной задачи. Каждый субагент работает в своём отдельном контексте, не мешая главному разговору. Несколько субагентов могут работать одновременно.
Представь тимлида, который руководит командой. Он не пишет весь код сам — он даёт задания разработчикам: «Ты — сделай фронтенд, ты — напиши тесты, ты — проверь безопасность». Каждый работает параллельно и отчитывается тимлиду. Основной агент в Cursor — это тимлид. Субагенты — его команда специалистов.
Без субагентов
Один агент делает всё последовательно: сначала ищет файлы, потом пишет код, потом запускает тесты. Каждый шаг блокирует следующий. Контекст засоряется.
С субагентами
Основной агент запускает 3 помощника параллельно: один ищет файлы, второй пишет код, третий проверяет тесты. Быстрее, чище, точнее.
Когда появились
Субагенты были добавлены в Cursor в версии 2.4 (январь 2026). Это было одно из главных обновлений — Cursor перешёл от модели «один агент делает всё» к модели «команда агентов работает вместе».
Зачем нужны субагенты — 3 причины
Короткий ответ: субагенты дают изоляцию контекста, параллельность и специализацию — то есть меньше шума, выше скорость и точнее экспертиза на узкой задаче.
Чистый контекст
У каждого субагента свой контекст. Шум от поиска файлов не засоряет основной разговор.
Параллельность
Несколько субагентов работают одновременно. То, что занимало час — делается за 15 минут.
Специализация
Субагент-аудитор безопасности найдёт уязвимости лучше, чем агент-универсал.
У Cursor уже есть встроенные субагенты — они работают «из коробки» и подключаются автоматически: один для поиска по кодовой базе, один для запуска команд в терминале, один для параллельных задач. Ты их даже не замечаешь — просто агент стал работать быстрее и умнее.
Субагенты vs Скиллы vs Команды — когда что?
Короткий ответ: скилл — это инструкция «как делать» в общем контексте; команда — быстрый сценарий по /; субагент — отдельный «работник» с изолированным контекстом и возможностью параллельной работы.
Чтобы разобраться в скиллах (длинные процедуры в .cursor/skills/), открой полный гайд по скиллам в Cursor. Если тебе нужны короткие сценарии по кнопке в чате, смотри гайд по командам Cursor (через /).
| Критерий | Скиллы | Команды | Субагенты |
|---|---|---|---|
| Суть | Инструкция «как делать» | Кнопка «сделай это» | Отдельный работник |
| Контекст | Общий с агентом | Общий с агентом | Свой изолированный |
| Параллельность | Нет | Нет | Да — несколько сразу |
| Модель | Та же, что у агента | Та же, что у агента | Можно выбрать другую |
| Может менять файлы | Да | Да | Настраивается (readonly) |
| Где хранится | .cursor/skills/ | .cursor/commands/ | .cursor/agents/ |
| Когда использовать | Повторяемые процедуры | Частые быстрые действия | Сложные задачи, нужна изоляция |
Скилл — когда хочешь, чтобы агент следовал процедуре лучше (инструкция).
Команда — когда нужно быстрое действие по кнопке (ярлык).
Субагент — когда нужен отдельный работник с чистым контекстом (специалист).
Как устроен субагент
Короткий ответ: кастомный субагент — это Markdown-файл с YAML-шапкой в папке .cursor/agents/; в шапке задаются имя, описание триггера, модель, readonly и фоновый режим.
Кастомный субагент — это Markdown-файл с YAML-шапкой в папке .cursor/agents/.
📁 .cursor/
📁 agents/
📄 security-auditor.md ← субагент-аудитор
📄 test-writer.md ← субагент для тестов
📄 researcher.md ← субагент-исследователь
Формат файла
---
name: security-auditor
description: Проверяет код на уязвимости безопасности.
Используй, когда добавляются новые API-эндпоинты,
логика авторизации или работа с данными.
model: inherit
readonly: true
is_background: false
---
Ты — эксперт по безопасности веб-приложений.
Когда тебя вызывают:
1. Проверь все изменённые файлы
2. Найди уязвимости: SQL-инъекции, XSS, утечки данных
3. Проверь обработку аутентификации и авторизации
4. Составь отчёт с указанием файлов и строк
Не исправляй код — только находи проблемы.
Параметры в шапке
| Параметр | Что делает | Значения |
|---|---|---|
| name | Имя субагента | Любое уникальное имя |
| description | Когда использовать — агент решает по этому полю | Подробное описание задачи |
| model | Какую модель использовать | inherit (как у родителя), fast (быстрая дешёвая), или конкретная модель |
| readonly | Может ли менять файлы | true — только читает, false — может редактировать |
| is_background | Работает ли в фоне | true — не блокирует основной чат, false — работает в основном потоке |
Как создать своего субагента
Короткий ответ: создай .cursor/agents/, добавь .md с YAML и инструкцией, перезапусти Cursor — субагент подхватится и будет вызываться по совпадению description.
Создай папку agents
mkdir -p .cursor/agents
Создай файл субагента
touch .cursor/agents/test-writer.md
Напиши YAML-шапку + инструкцию
Шапка определяет когда и как запускать. Тело — что делать.
Перезапусти Cursor
Субагент появится и будет вызываться автоматически, когда основной агент решит, что задача совпадает с description.
Для глобальных субагентов (во всех проектах) используй ~/.cursor/agents/.
Топ-3 субагента для новичка
Начни с этих трёх — они безопасные (readonly) и сразу приносят пользу.
security-auditor
Проверяет код на уязвимости после каждого изменения. readonly: true — не может ничего сломать, только находит проблемы. Идеальный первый субагент.
---
name: security-auditor
description: Проверяет код на уязвимости.
Используй при добавлении API, авторизации,
работы с базой данных или пользовательских данных.
model: inherit
readonly: true
is_background: false
---
Ты — эксперт по безопасности.
При вызове:
1. Проверь изменённые файлы через git diff
2. Найди: SQL-инъекции, XSS, утечки данных,
проблемы с аутентификацией
3. Для каждой проблемы укажи:
📍 Файл → Строка → Проблема → Как исправить
Не меняй код. Только отчёт.
code-explainer
Когда основной агент находит сложный файл — делегирует разбор этому субагенту. Тот изучает код в своём контексте и возвращает понятное объяснение.
---
name: code-explainer
description: Объясняет сложный код простым языком.
Используй, когда нужно разобраться в незнакомом
модуле, legacy-коде или чужом файле.
model: fast
readonly: true
is_background: false
---
Ты — терпеливый преподаватель программирования.
При вызове:
1. Прочитай указанный файл или фрагмент
2. Объясни, что делает каждая часть
3. Используй аналогии из реальной жизни
4. Укажи, какие данные входят и выходят
Объясняй так, будто человек никогда
не программировал. На русском языке.
test-writer
Автоматически пишет тесты для нового кода. Работает параллельно с основным агентом — пока ты добавляешь функциональность, этот субагент уже пишет тесты для неё.
---
name: test-writer
description: Пишет тесты для нового кода.
Используй после добавления функций, компонентов
или API-эндпоинтов.
model: inherit
readonly: false
is_background: true
---
Ты — специалист по тестированию.
При вызове:
1. Изучи изменённые/новые файлы
2. Определи, какой фреймворк тестов
используется в проекте
3. Напиши тесты: happy path, edge cases,
обработка ошибок
4. Запусти тесты и убедись, что проходят
Стремись к покрытию 80%+.
Частые ошибки
Размытое описание (description)
«Помогает с задачами» — агент не поймёт, когда делегировать. Пиши конкретно: «Используй при добавлении API-эндпоинтов, авторизации или работы с базой данных».
Слишком много субагентов
Начни с 2–3 штук. Больше — агент запутается, кому что делегировать. Добавляй новых только когда есть чёткий отдельный юзкейс.
Параллельная работа с одними файлами
Если два субагента одновременно меняют один файл — будут конфликты. Разделяй задачи по файлам: один работает с фронтендом, другой с бэкендом.
Частые вопросы про субагенты в Cursor
Чем субагент в Cursor отличается от скилла?
Скилл — инструкция в общем контексте агента. Субагент работает в отдельном контексте и может запускаться параллельно с другими субагентами, не засоряя основной диалог.
Где хранятся файлы субагентов?
В проекте — в папке .cursor/agents/. Глобально для всех проектов — в ~/.cursor/agents/.
Нужно ли перезапускать Cursor после добавления субагента?
Да. После создания или изменения файлов в agents перезапусти Cursor, чтобы подхватить новые определения.
Чеклист: что запомнить
Субагент = отдельный ИИ-работник со своим контекстом, запускаемый основным агентом
Файлы хранятся в .cursor/agents/ (проект) или ~/.cursor/agents/ (глобально)
Формат: YAML-шапка (name, description, model, readonly) + Markdown-инструкция
description — ключевое поле: по нему агент решает, когда делегировать задачу
Субагенты работают параллельно — это главное преимущество перед скиллами
readonly: true — безопасный режим, субагент не может менять файлы
Встроенные субагенты уже работают из коробки — ты их даже не замечаешь
Начни с security-auditor (readonly) — безопасный и полезный первый субагент