Продвинутая настройка AI-агента: скиллы, хуки, сабагенты, MCP

После первой настройки агент уже полезен. Но скоро видно, чего не хватает: одни инструкции он забывает, повторяющиеся процедуры приходится объяснять заново, длинные поиски засоряют контекст, а до трекера и базы он не дотягивается. Для каждой из этих проблем в Claude Code есть отдельный механизм. Ниже — когда какой нужен, и рабочие примеры из официальной документации.

#Карта: что за что отвечает

Важная оговорка из документации: CLAUDE.md и правила агент воспринимает как контекст, а не как принудительную конфигурацию. Если действие нужно заблокировать независимо от решения модели, это задача хука.

#Правила по путям

Когда CLAUDE.md разрастается, часть инструкций переезжает в .claude/rules/. Каждый файл — одна тема. Правило с полем paths загружается, только когда агент работает с подходящими файлами:

---
paths:
  - "src/api/**/*.ts"
---
- Каждый хендлер валидирует вход через zod
- Ошибки возвращаются в формате { error: { code, message } }

#Скиллы: процедуры по запросу

Скилл — папка с файлом SKILL.md. Во frontmatter — описание того, когда его применять, в теле — инструкции. Агент подгружает скилл сам, если запрос подходит под описание, или вы вызываете его командой /имя. Главное отличие от CLAUDE.md: тело скилла загружается, только когда он нужен.

Где хранить:

• ~/.claude/skills/<имя>/SKILL.md — ваши личные, во всех проектах;
• .claude/skills/<имя>/SKILL.md — общие для проекта, в git.

Пример из документации — скилл, который подставляет живой diff в инструкцию:

---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points, then list any risks.

Строка с ! — динамическая подстановка: Claude Code выполняет команду и вставляет её вывод до того, как модель прочитает скилл. Старые команды из .claude/commands/ продолжают работать, но рекомендуемый формат теперь скиллы. Скиллы следуют открытому стандарту Agent Skills, который поддерживают и другие инструменты.

#Хуки: правила без исключений

Хук — команда (или HTTP-запрос, промпт, сабагент), которая срабатывает в определённой точке жизненного цикла. Главные события:

• PreToolUse — перед вызовом инструмента, может его заблокировать;
• PostToolUse — после успешного вызова;
• UserPromptSubmit — когда отправлен запрос;
• Stop — когда агент закончил ход;
• SessionStart — начало или возобновление сессии;
• SubagentStart / SubagentStop, PreCompact, Notification и другие.

Хуки настраиваются в settings.json. Пример из руководства по хукам: форматировать каждый изменённый файл и присылать уведомление, когда агенту нужен ответ:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }]
      }
    ]
  }
}

Если хук завершается с кодом 2, действие блокируется: для PreToolUse это отмена вызова инструмента, а текст из stderr агент видит как причину. Так строится сторож для защищённых файлов, например миграций или .env.

Stop-хук как проверка. В лучших практиках Claude Code описан приём: Stop-хук запускает вашу проверку (тесты, сборку) и не даёт агенту закончить ход, пока она не пройдёт. Фактически это детерминированная версия «проверь себя», и она работает, даже когда за агентом никто не следит.

Посмотреть, что настроено, можно командой /hooks.

#Сабагенты: изоляция контекста

Сабагент работает в своём контекстном окне, со своим системным промптом, своими инструментами и правами, и возвращает в основной разговор только итог. Встроенные: Explore (быстрый поиск, только чтение), Plan (исследование для режима плана) и general-purpose.

Свой сабагент — файл в .claude/agents/:

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

По документации сабагент уместен, когда задача выдаёт много шума, который не нужен в основном контексте, когда нужны отдельные права или ограничения инструментов и когда работа самодостаточна и сводится к итогу. Основной разговор лучше, когда нужна частая обратная связь, этапы делят общий контекст или важна скорость. Поле isolation: worktree даёт сабагенту отдельную копию репозитория.

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

#MCP: подключение внешних систем

MCP — открытый протокол, через который агент получает инструменты, данные и шаблоны из внешних систем. Добавление сервера:

# удалённый сервер по HTTP
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

# локальный сервер: всё после -- запускается как команда сервера
claude mcp add playwright -- npx -y @playwright/mcp@latest

Области видимости: по умолчанию local — только вы и только этот проект; --scope user — вы во всех проектах (~/.claude.json); --scope project — вся команда через .mcp.json в корне репозитория. Сервер из .mcp.json нужно одобрить при первом запуске. Внутри сессии серверами управляет команда /mcp. Подробнее о полностью подключённом стеке и рисках — в седьмом посте.

#Плагины

Когда набор скиллов, хуков, сабагентов и MCP-серверов устоялся, его можно упаковать в плагин и раздать команде через маркетплейс. Скиллы плагина получают пространство имён плагин:скилл, поэтому несколько плагинов уживаются вместе.

#Песочница

Режимы прав отвечают на вопрос «спрашивать ли меня». Песочница отвечает на вопрос «до чего команды могут дотянуться физически». Это граница, которую обеспечивает операционная система: вы задаёте, какие файлы и сетевые домены доступны shell-командам агента. Настройка — команда /sandbox. Песочница работает на macOS, Linux и WSL2 и покрывает только shell-команды: файловые инструменты агента, MCP-серверы и хуки работают вне её.

#Запуск без человека: скрипты и CI

Флаг -p выполняет одну задачу и завершается:

claude -p "Find and fix the bug in auth.py" --allowedTools "Read,Edit,Bash"

--output-format json возвращает структурированный результат, в том числе оценку стоимости total_cost_usd. --bare пропускает автозагрузку хуков, скиллов, MCP и CLAUDE.md — так результат одинаков на любой машине. Для GitHub есть Claude Code GitHub Actions: команда /install-github-app ставит приложение и готовит workflow, после чего агент отвечает на упоминания @claude в issue и pull request.

#Аналоги в Codex и Cursor

• Codex: свои агенты описываются в .codex/agents/*.toml с полями name, description, developer_instructions; там же можно задать sandbox_mode = "read-only" для агента-исследователя. MCP-серверы добавляются командой codex mcp add. Для CI — codex exec.
• Cursor: хуки описываются в hooks.json (события вроде beforeShellExecution и afterFileEdit), MCP — в .cursor/mcp.json проекта или ~/.cursor/mcp.json.

#Порядок внедрения

1. Сначала наведите порядок в CLAUDE.md и вынесите частные правила в .claude/rules/.
2. Хук на форматирование и сторож для защищённых файлов — самые дешёвые гарантии.
3. Скилл для процедуры, которую вы объясняете чаще раза в неделю.
4. Сабагент-ревьюер с правами только на чтение.
5. Один-два MCP-сервера под реальные задачи, а не «на всякий случай».

Дальше — виды AI-агентов: чем различаются агенты в чате, IDE, терминале, облаке и CI.