Claude Code в 2026: Skills, Sub-agents и Hooks — полный гайд с примерами от практика

Ладно, давайте начистоту. Если вы сейчас пишете код и не используете AI-агенты — вы, конечно, имеете на это полное право. Но это примерно как в 2010 году отказываться от Git, потому что «и на SVN нормально». Работает? Работает. Эффективно? Ну такое.

Я за последний год перепробовал кучу подходов к интеграции AI в свой рабочий процесс. Начинал банально — кидал промты в чат, копировал ответы, вставлял в IDE. Потом перешёл на Cursor, покрутил Copilot. И в какой-то момент осел на Claude Code — CLI-шном инструменте от Anthropic, который работает прямо в терминале. Не потому что он «лучше всех» (эти холивары я оставлю для Reddit), а потому что лично мне так удобнее и продуктивнее.

И вот сейчас хочу подробно рассказать про три вещи, которые реально изменили мой подход к работе с этим инструментом: Skills (навыки), Sub-agents (субагенты) и Hooks (хуки). Это не абстрактная теория — я покажу конкретные конфиги, реальные сценарии и грабли, на которые уже наступил.

Зачем вообще это всё нужно

Перед тем как нырять в детали, давайте разберёмся с проблемой, которую эти штуки решают.

Типичный сценарий работы новичка с AI-агентом выглядит так: открываете чат, пишете что-то вроде «поправь баг в файле auth.py, там пароль не хешируется», получаете ответ, применяете. Окей, для простых задач это работает. Но когда проект растёт — начинается боль.

Вы раз за разом объясняете агенту одно и то же. «У нас тут DDD», «коммиты пиши по Conventional Commits», «не трогай legacy-код в /old», «для тестов используй pytest, не unittest». Каждая новая сессия — чистый лист. Агент ничего не помнит. Вы, по сути, тратите половину контекстного окна на то, чтобы довести его до нужного состояния.

Skills, sub-agents и hooks — это способ один раз описать все эти правила, роли и автоматизации, и дальше просто работать, не думая об этом.

Причём штука в том, что Skills — это часть открытой спецификации Agent Skills IO. Не привязана конкретно к Claude Code. Написали skill один раз — он будет работать и в Cursor, и в других агентах, которые поддерживают этот стандарт. Мелочь, а приятно.

Skills: инструкции, которые агент подбирает сам

Что это такое на пальцах

Skill — это, по сути, папка с файлом SKILL.md и (опционально) дополнительными материалами: скрипты, шаблоны, примеры. В SKILL.md вы описываете, что этот навык делает и как им пользоваться. А дальше агент сам решает, когда его применить, основываясь на вашем запросе и описании скилла.

Вот тут важный момент — скиллы не вызываются вручную (ну, можно и вручную, но основной режим — автоматический). Вы пишете «сделай ревью безопасности в директории app/Ports», агент смотрит на доступные скиллы, видит security-review с подходящим описанием и сам его подхватывает. Магия? Нет, просто хорошо написанный description.

Где лежат скиллы

Два варианта:

Персональные — в ~/.claude/skills/. Доступны во всех ваших проектах. Сюда кладём всякое универсальное: генератор коммитов, форматирование кода, личные утилиты.

Проектные — в .claude/skills/ внутри репозитория. Коммитятся в git, доступны всей команде. Сюда — специфику проекта: ревью по архитектуре, проверки на соответствие DDD, стандарты именования.

Анатомия SKILL.md

Файл состоит из двух частей: YAML-мета сверху и Markdown-контент ниже.

---
name: security-review
description: >
  Проверяет код на типичные уязвимости: SQL-инъекции, XSS, небезопасное
  хеширование, утечки секретов. Используй при запросах на security review,
  аудит безопасности, проверку на уязвимости.
allowed-tools: Read, Grep, Glob
---

# Security Review

## Что проверяем

1. SQL-инъекции и небезопасные запросы к БД
2. XSS-уязвимости в шаблонах
3. Хардкод секретов (API-ключи, пароли, токены)
4. Небезопасное хеширование паролей
5. Открытые эндпоинты без авторизации

## Как проверяем

- Используй `Grep` для поиска подозрительных паттернов
- Проверяй `Glob`-ом наличие .env файлов в репозитории
- Читай конфигурационные файлы через `Read`

## Формат отчёта

Выдай результат в виде таблицы:
| Файл | Строка | Тип уязвимости | Критичность | Рекомендация |

В конце — общая оценка от 1 до 10 и резюме.

Пара нюансов:

name — только латиница, цифры и дефисы, до 64 символов. Не выпендривайтесь с нэймингом.
description — пишите его так, будто объясняете коллеге, когда и зачем использовать этот навык. Именно по описанию агент решает, подходит скилл или нет.
allowed-tools — ограничивает, какие инструменты агент может использовать в рамках этого скилла. В примере выше — только чтение. Никакого редактирования. Это для ревью идеально: смотрим, но не трогаем.

Структура посложнее

Для простых скиллов одного SKILL.md достаточно. Но если навык серьёзный — добавляйте поддерживающие файлы:

security-review/
├── SKILL.md              # Основные инструкции
├── reference.md          # Детальная документация по типам уязвимостей
├── examples.md           # Примеры хороших и плохих паттернов
├── scripts/
│   └── scan_secrets.py   # Скрипт для поиска захардкоженных секретов
└── templates/
    └── report.md         # Шаблон отчёта

В SKILL.md ссылаетесь на эти файлы: «для подробностей смотри reference.md», «запусти скрипт scripts/scan_secrets.py». Агент подгрузит их только при необходимости — не будет тащить всё сразу в контекстное окно.

Практический пример: скилл для коммитов

Один из первых скиллов, которые я написал — и пользуюсь каждый день:

---
name: smart-commit
description: >
  Создаёт коммит на основе staged изменений. Использует Conventional Commits.
  Применяй при запросах сделать коммит, закоммитить, commit.
allowed-tools: Bash
---

# Smart Commit

## Инструкции

1. Запусти `git diff --staged` и проанализируй изменения
2. Определи тип коммита:
   - feat: новая фича
   - fix: исправление бага
   - refactor: рефакторинг без изменения поведения
   - docs: только документация
   - test: добавление или правка тестов
   - chore: обновление зависимостей, конфиг и т.п.
3. Сформируй сообщение:
   - Заголовок до 50 символов, на английском
   - Пустая строка
   - Тело: что изменено и почему (не как)
4. Выполни `git commit -m "..."` с получившимся сообщением

## Примеры

Хорошо: `feat(auth): add JWT token refresh endpoint`
Плохо: `fixed stuff` или `update code`

Хорошо: `fix(api): handle null response from payment gateway`
Плохо: `bugfix`

Теперь я просто пишу «закоммить это» — и получаю аккуратный conventional commit без лишних телодвижений.

disable_model_invocation: защита от самодеятельности

Есть скиллы, которые агенту категорически нельзя запускать самостоятельно. Деплой, миграции БД, truncate таблиц — всё, что может что-то сломать. Для этого в мете есть флаг:

---
name: deploy-production
description: Деплоит текущую ветку на продакшен.
disable_model_invocation: true
---

С disable_model_invocation: true агент никогда не выберет этот скилл автоматически. Только ручной вызов через команду. Спите спокойно.

context: fork — изоляция контекста

Ещё одна полезная мета-опция. Когда вы ставите context: fork, скилл выполняется в изолированном контексте. То есть вся предыдущая история диалога не попадает в запрос — агент работает только с тем, что относится к текущей задаче.

Зачем это? Представьте: вы час обсуждали архитектуру, потом говорите «закоммить». Агенту для коммита не нужен весь тот контекст про архитектуру — он только засоряет окно и может вызвать галлюцинации. С context: fork коммит делается чисто: агент смотрит git diff, формирует сообщение, выполняет.

---
name: smart-commit
description: Создаёт коммит на основе staged изменений.
context: fork
allowed-tools: Bash
---

Но для ревью, например, fork ставить не надо — там как раз важен контекст того, что обсуждалось.

Sub-agents: у каждой задачи свой специалист

Идея

Скиллы — это навыки. А субагент — это «человек», обладающий набором навыков. Грубо говоря, у вас может быть:

Ревьювер — знает security-review, ddd-review, code-style-review
Имплементатор — умеет писать код по заданному стилю, покрывать тестами
Архитектор — анализирует структуру, предлагает рефакторинг

Каждый субагент работает в своём изолированном контексте, со своим системным промтом и набором разрешённых инструментов.

Как создать субагента

Субагенты лежат в .claude/agents/ (проектные) или ~/.claude/agents/ (персональные). Формат — Markdown с YAML-метой, как у скиллов, но с другими полями:

---
name: code-reviewer
description: >
  Делает ревью кода на предмет качества, безопасности и соответствия
  архитектурным принципам проекта.
tools: Read, Glob, Grep
model: sonnet
---

Ты — опытный ревьювер кода. Твоя задача — находить проблемы,
а не хвалить. Будь конкретен: указывай файл, строку, суть проблемы
и рекомендацию.

Никогда не редактируй файлы. Только читай и анализируй.

## Приоритеты при ревью

1. Безопасность (критические уязвимости)
2. Логические ошибки
3. Производительность
4. Читаемость и поддерживаемость
5. Стилевые замечания

## Формат вывода

Раздели замечания по критичности:
- 🔴 Critical — нужно исправить до мержа
- 🟡 Warning — желательно исправить
- 🔵 Info — рекомендации по улучшению

Пара вещей, на которые стоит обратить внимание:

tools — ограничивает инструменты. Ревьювер не должен ничего редактировать, только Read/Glob/Grep. Если tools не указать — субагент наследует все инструменты основного агента.
model — можно выбрать модель. Для простых субагентов (перевод текста, форматирование) можно поставить что-то полегче — haiku. Для серьёзного ревью — sonnet или opus. Экономим токены там, где можно.
Содержимое после --- — это системный промт субагента. Именно системный, не пользовательский. Частая ошибка новичков: пишут туда что-то вроде «проревьюй мне файл X» — нет, это должно быть описание роли и правил поведения.

Как это работает на практике

Запускаете Claude Code, пишете:

Сделай ревью директории app/Domain на предмет безопасности и архитектуры

Агент смотрит на доступных субагентов, видит code-reviewer с подходящим описанием — и делегирует ему задачу. Субагент запускается в отдельном контексте, со своим системным промтом, сканирует указанную директорию и возвращает отчёт.

В UI Claude Code это выглядит так: вы видите пометку «Agent: code-reviewer» и понимаете, что работает именно субагент, а не основной агент.

Можно также вызвать субагента явно:

/agents code-reviewer

Или создать скилл-обёртку, которая будет запускать нужного субагента:

---
name: review
description: Запускает субагента-ревьювера на указанной директории.
---

# Code Review

Прими аргументы с путём к директории и вызови субагента code-reviewer,
передав ему этот путь для ревью.

Субагенты и хуки: связка

У субагентов могут быть собственные хуки (про хуки подробно — ниже). Например, только ревьювер шлёт уведомления в Telegram после завершения. Остальные субагенты — нет. Гибкость настраивается на уровне каждого агента отдельно.

Hooks: перехватываем события агента

Концепция

Хуки — это скрипты, которые автоматически запускаются при определённых событиях в жизненном цикле агента. Агент начал работать? Хук. Запросил разрешение на редактирование файла? Хук. Закончил задачу и выдал ответ? Хук.

Вот полный список событий, к которым можно привязать хуки:

Событие	Когда срабатывает
`UserPromptSubmit`	Пользователь отправил промт (до обработки)
`PreToolUse`	Перед выполнением любого инструмента (Bash, Read и т.д.)
`PostToolUse`	После выполнения инструмента
`Notification`	Агент шлёт уведомление (ждёт ввода и т.п.)
`PermissionRequest`	Агент запрашивает разрешение на действие
`Stop`	Агент закончил работу, сформировал ответ
`SubagentStop`	Субагент завершил работу
`SessionEnd`	Сессия Claude Code завершена

Настройка

Хуки задаются в JSON-конфиге:

Проектные: .claude/settings.json
Глобальные: ~/.claude/settings.json

Вот пример конфига, который я использую — Telegram-уведомления при завершении задачи и при запросе разрешений:

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/telegram-notify.sh stop"
          }
        ]
      }
    ],
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/telegram-notify.sh notification"
          }
        ]
      }
    ],
    "PermissionRequest": [
      {
        "matcher": "edit|write",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/telegram-notify.sh permission"
          }
        ]
      }
    ]
  }
}

Важно: используйте $CLAUDE_PROJECT_DIR в путях — иначе хуки не найдут скрипты, если вы запустите Claude Code из другой директории.

Telegram-нотификатор: пошаговая реализация

Это, пожалуй, самый практически полезный хук, который я настроил. Идея простая: запускаете задачу в Claude Code, уходите пить кофе, а в Telegram приходит сообщение «Задача завершена» с кратким summary. Или «Claude запрашивает разрешение на редактирование файла X» — и вы прямо с телефона решаете, что делать.

Сам скрипт:

#!/bin/bash
# .claude/hooks/telegram-notify.sh

TELEGRAM_BOT_TOKEN="YOUR_BOT_TOKEN"
TELEGRAM_CHAT_ID="YOUR_CHAT_ID"
EVENT_TYPE="$1"

# Читаем JSON из stdin (Claude Code передаёт данные о событии)
INPUT=$(cat)

case "$EVENT_TYPE" in
  stop)
    MESSAGE="✅ Задача завершена

$(echo "$INPUT" | python3 -c "
import sys, json
try:
    data = json.load(sys.stdin)
    # Обрезаем до 500 символов, чтоб Telegram не ругался
    text = data.get('response', 'Нет данных')[:500]
    print(text)
except:
    print('Не удалось распарсить ответ')
")"
    ;;
  notification)
    MESSAGE="🔔 Claude Code требует внимания

$(echo "$INPUT" | python3 -c "
import sys, json
try:
    data = json.load(sys.stdin)
    print(data.get('message', 'Нет данных')[:300])
except:
    print('Уведомление без деталей')
")"
    ;;
  permission)
    MESSAGE="🔐 Запрос разрешения

$(echo "$INPUT" | python3 -c "
import sys, json
try:
    data = json.load(sys.stdin)
    tool = data.get('tool_name', '?')
    inp = json.dumps(data.get('tool_input', {}), indent=2, ensure_ascii=False)[:400]
    print(f'Инструмент: {tool}\n{inp}')
except:
    print('Ошибка разбора запроса')
")"
    ;;
esac

# Отправляем в Telegram
curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendMessage" \
  -d chat_id="${TELEGRAM_CHAT_ID}" \
  -d text="${MESSAGE}" \
  -d parse_mode="HTML" > /dev/null 2>&1

Не забудьте дать права на выполнение:

chmod +x .claude/hooks/telegram-notify.sh

Для создания бота — идёте к @BotFather в Telegram, создаёте бота, получаете токен. CHAT_ID — ваш ID (можно узнать через @userinfobot). Ничего сложного, занимает пять минут.

PreToolUse: блокируем опасные команды

Ещё один крайне полезный хук — перехват опасных bash-команд перед их выполнением:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/safe-bash.sh"
          }
        ]
      }
    ]
  }
}

Скрипт safe-bash.sh:

#!/bin/bash
# Блокируем опасные команды

INPUT=$(cat)
COMMAND=$(echo "$INPUT" | python3 -c "
import sys, json
data = json.load(sys.stdin)
print(data.get('tool_input', {}).get('command', ''))
")

# Список запрещённых паттернов
BLOCKED_PATTERNS=(
  "rm -rf /"
  "DROP DATABASE"
  "TRUNCATE"
  "> /dev/sda"
  "mkfs"
  ":(){:|:&};:"
)

for pattern in "${BLOCKED_PATTERNS[@]}"; do
  if echo "$COMMAND" | grep -qi "$pattern"; then
    # Exit code 2 = заблокировать выполнение
    echo '{"error": "Команда заблокирована хуком безопасности: '"$pattern"'"}' >&2
    exit 2
  fi
done

# Всё ок, пропускаем
exit 0

Exit code 2 — специальный код для Claude Code, который означает «заблокировать операцию и показать ошибку агенту». Агент увидит сообщение об ошибке и попытается найти альтернативный подход.

PostToolUse: модификация результатов

Хуки PostToolUse позволяют перехватывать результаты выполнения инструментов. Например, автоматически прогонять ruff или flake8 после каждого сохранения Python-файла:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/auto-lint.sh"
          }
        ]
      }
    ]
  }
}

Правда, тут есть нюанс: если хук срабатывает на каждую операцию записи, это может сильно замедлить агента. Подумайте, что именно вам нужно, и настраивайте matcher аккуратно.

Output Styles: настраиваем формат вывода

Это фича, про которую почему-то мало кто говорит, а она классная. По умолчанию Claude Code отвечает в своём стиле — техническом, на английском, с определённым форматированием. Но вы можете полностью это переопределить.

Стили лежат в .claude/output-styles/ или ~/.claude/output-styles/.

Пример — русскоязычный ревьювер:

# .claude/output-styles/code-reviewer.md
---
name: code-reviewer
keep_coding_instructions: true
---

Ты — русскоязычный код-ревьювер. Пиши результаты ревью на русском языке.
Используй технический, но понятный язык. Структурируй по критичности.
Избегай воды — только конкретика.

keep_coding_instructions: true означает, что системный промт Claude Code про работу с кодом остаётся. Убираете эту опцию — и агент перестаёт быть «кодером», становится просто чат-ботом с вашими инструкциями.

Переключаемся:

/output-style code-reviewer

А можно сделать и что-нибудь поинтереснее. Я ради эксперимента как-то создал стиль «менеджер» — без технических деталей, на русском, со сленгом. Агент выдал ревью в духе «ну ребята, это полная катастрофа, кто это вообще писал». Забавно, но для демонстрации заказчику — вполне рабочий формат.

Всё вместе: реальный workflow на проекте

Давайте соберём всё в единую картинку. Вот как выглядит мой типичный сетап на Symfony-проекте с DDD:

.claude/
├── settings.json          # Хуки (Telegram, безопасность)
├── skills/
│   ├── security-review/
│   │   └── SKILL.md
│   ├── ddd-review/
│   │   ├── SKILL.md
│   │   └── reference.md   # Описание слоёв, правила зависимостей
│   ├── symfony-review/
│   │   └── SKILL.md
│   ├── smart-commit/
│   │   └── SKILL.md
│   └── deploy/
│       └── SKILL.md        # disable_model_invocation: true
├── agents/
│   ├── code-reviewer.md    # Субагент-ревьювер (Read, Grep, Glob)
│   └── implementer.md      # Субагент-имплементатор (все инструменты)
├── output-styles/
│   ├── code-reviewer.md
│   └── manager.md
└── hooks/
    ├── telegram-notify.sh
    └── safe-bash.sh

Рабочий день:

Открываю терминал, запускаю claude в директории проекта
Пишу «сделай полное ревью app/Domain» — агент автоматически выбирает субагента-ревьювера, тот подхватывает скиллы security-review, ddd-review, symfony-review
Ухожу наливать кофе — в Telegram приходит уведомление «задача завершена» с кратким отчётом
Возвращаюсь, смотрю полный отчёт в терминале, вношу свои правки
Пишу «закоммить» — срабатывает smart-commit с context: fork
Деплой — только руками: /deploy production

Весь этот сетап я настраивал постепенно, в процессе работы. Не садился на выходных «писать идеальные скиллы» — просто каждый раз, когда замечал повторяющуюся проблему или паттерн, добавлял правило в соответствующий скилл. Итерация за итерацией.

Частые проблемы и как с ними бороться

«Агент не подхватывает мой скилл»

В 90% случаев проблема в description. Пишите конкретнее, включайте слова-триггеры:

# Плохо
description: Помогает с данными

# Хорошо
description: >
  Анализирует Excel-файлы, строит сводные таблицы, генерирует графики.
  Используй при работе с .xlsx файлами, табличными данными, отчётами.

«Два скилла конфликтуют»

Если у вас data-analysis и log-analysis, а описания похожи — агент может выбрать не тот. Разводите описания по конкретным триггерам. Один — для Excel и CRM, другой — для логов и метрик.

«Хук тормозит работу агента»

Если хук на PreToolUse срабатывает на каждый вызов Bash (включая безобидные ls и pwd) — это проблема. Либо оптимизируйте скрипт хука (чтобы выполнялся за миллисекунды), либо добавьте в скрипт проверку: если команда безопасная — сразу exit 0, без лишней логики.

«Скилл сломался после обновления Claude Code»

Проверяйте YAML-синтаксис:

cat .claude/skills/my-skill/SKILL.md | head -n 15

Частые ошибки: табы вместо пробелов, отсутствие закрывающего ---, спецсимволы в строках без кавычек.

Полезные утилиты и ресурсы

Вот что я рекомендую подтянуть, если собираетесь серьёзно работать со скиллами:

Agent Skills IO — сама спецификация. Читайте первоисточник, не пересказы.
Документация Claude Code — официальная документация по скиллам, субагентам и хукам.
claude-code-hooks-mastery — отличный GitHub-репозиторий с примерами хуков: TTS-уведомления, блокировка опасных команд, логирование всех действий агента.
Claude Code Sub Agent Manager — CLI-утилита для управления субагентами. Можно ставить готовых агентов одной командой: claude-agents install code-reviewer.
Warp — терминал, который отлично дружит с Claude Code. Голосовой ввод, нормальное отображение вывода (в отличие от встроенного терминала JetBrains, который при работе с Claude Code начинает моргать как новогодняя гирлянда).

Итого

Три вещи, которые стоит запомнить из всего вышенаписанного:

Skills — модульные инструкции, которые агент подбирает автоматически. Пишете один раз, пользуетесь везде. Начните с простого: коммиты, ревью, линтинг. Дополняйте по мере работы.

Sub-agents — специализированные роли с изолированным контекстом и своим набором инструментов. Один ревьювит, другой пишет код, третий деплоит. Каждый знает свои границы.

Hooks — автоматизация событий в жизненном цикле агента. Уведомления, валидация, логирование, блокировка опасных операций. Shell-скрипты, которые привязываются к конкретным событиям.

И главное — не бойтесь генерировать скиллы с помощью самого же AI. Серьёзно. Скажите агенту «сгенерируй мне скилл для ревью безопасности по спецификации Agent Skills IO» — и он вам выдаст болванку. Дальше допилите руками по ходу работы. Это нормальный, рабочий подход. Идеальный скилл с первого раза всё равно не получится — он дозревает итеративно, вместе с вашим пониманием проекта.

Ну и напоследок: не экономьте на модели. Если используете бесплатную tier-1 модель для сложного ревью проекта — результат вас, мягко говоря, не впечатлит. И вы решите, что «всё это не работает». Работает. Просто инструмент требует соответствующих ресурсов, как и любой другой.