ИИ-агенты, CLAUDE.md, SKILL.md и MCP-серверы: полный гайд по Claude Code

Все говорят про ИИ-агентов, но мало кто объясняет что это. ИИ-агент - не просто чат-бот и не нейросеть в окошке. Это программа, которая сама решает задачи: разбивает цель на шаги, вызывает нужные инструменты, проверяет результат и двигается дальше. Агент - не просто GPT, который отвечает на вопросы, это совершенно другой уровень.

Я работаю с ИИ-агентами каждый день - пишу скиллы, взаимодействую с MCP-серверами, прописываю CLAUDE.md файлы. Когда разобрался как это устроено - стало понятно насколько это мощная штука. В этой статье объясню простым языком что такое ИИ-агент, зачем ему скиллы (SKILL.md), как работает CLAUDE.md и при чём тут MCP-серверы.

Что такое ИИ-агент и чем отличается от обычного чат-бота

Представьте двух помощников. Первый - справочная служба: вы спрашиваете, он отвечает. Не спрашиваете - молчит. Это обычный чат-бот. Второй - личный ассистент: вы говорите "организуй мне поездку в Казань на выходные", а он ищет билеты, бронирует отель, составляет маршрут, проверяет погоду. Это ИИ-агент.

[TGBLOCK]

Ключевое отличие AI agent от чат-бота:

ИИ-агент состоит из трёх частей: мозг (языковая модель - GPT, Claude, GigaChat), инструменты (доступ к файлам, API, базам данных) и память (контекст проекта, история действий). Когда все три части работают вместе - агент становится по-настоящему полезным.

Как работает AI agent изнутри

Разберём на примере. Допустим, вы просите AI agent: "Проанализируй продажи за март и подготовь отчёт". Вот что происходит:

1. Планирование. Агент разбивает задачу на шаги: получить данные → обработать → сформировать отчёт.
2. Выбор инструмента. Для получения данных - обращается к API или базе данных. Для обработки - запускает Python-скрипт. Для отчёта - создаёт файл.
3. Выполнение. Последовательно выполняет каждый шаг, проверяя результат.
4. Самокоррекция. Если что-то пошло не так (API вернул ошибку, данные пришли в неправильном формате) - агент пробует другой подход.

Это и есть главное отличие AI agent от простой нейросети. Нейросеть генерирует текст, а ИИ-агент действует в реальном мире: читает файлы, пишет код, отправляет запросы, создаёт документы.

Кстати, AI agent не обязательно должен быть сложным. Даже простой агент с одним скиллом и парой инструментов уже экономит часы работы. Я начинал с агента который просто парсил данные с сайтов и складывал в таблицу. Ничего космического, но три часа рутины в неделю он закрывал полностью.

Claude skills и SKILL.md - скиллы для ИИ-агентов

Раньше мы писали огромные простыни кода, в которых и была заложена главная ценность нашего бизнеса - работающий продукт. Теперь всё иначе: код стоит всё меньше, а главной ценностью постепенно становятся детальные инструкции для агента - скиллы.

Скиллы (claude skills) - это наборы инструкций, которые учат ИИ-агента выполнять конкретные задачи. Каждый скилл описывается в файле SKILL.md и содержит пошаговый алгоритм: что делать, в каком порядке, какие инструменты использовать.

Зачем нужны claude skills? Без скиллов ИИ-агент - как новый сотрудник без должностной инструкции. Каким бы умным он ни был, он не знает ваших процессов. Файл SKILL.md решает эту проблему - вы один раз описываете процесс и агент выполняет его каждый раз одинаково хорошо.

Пример простого SKILL.md:

---
description: Создание SEO-статьи для блога
---

## Алгоритм

1. Собери ключевые слова через API Wordstat.
2. Проанализируй топ-5 конкурентов.
3. Напиши черновик с нужной плотностью ключей.
4. Очеловечь текст по стайлгайду.
5. Сгенерируй Schema.org разметку.

Это реальный (хотя и сильно упрощённый) agent skill из моего проекта - я использую его для создания скелета статьи в блоге. ИИ-агент читает этот SKILL.md, понимает последовательность и выполняет каждый шаг. Claude skills позволяют автоматизировать любой повторяющийся процесс: от написания кода до анализа данных.

И SKILL.md - это не просто промпт. Это полноценная инструкция с контекстом, ограничениями и примерами. Хороший agent skill экономит десятки часов, потому что агент каждый раз работает по проверенному алгоритму, а не импровизирует. 

Прямо сейчас Claude Code генерирует для меня видео, используя самый детальный скилл из всех, что я когда-либо писал. Это был единственный способ заставить его сделать приемлемый результат. Вы сами всё поймёте когда будете по несколько раз объяснять агенту что нужно сделать, а чего не нужно. Пока просто не оформите подробную инструкцию, чтобы вызывать её одной командой🔥

Как написать свой agent skill

Структура agent skill файла простая:

• Описание (description) - когда и зачем вызывать этот agent skill. Агент читает описание и решает подходит ли скилл для текущей задачи.
• Тело скилла - пошаговый алгоритм. Здесь можно писать что угодно: инструкции, примеры кода, шаблоны, ограничения.
• Привязка к инструментам - какие MCP-серверы или скрипты agent skill использует при выполнении.

Claude skills загружаются по требованию - агент не читает все скиллы заранее, а подгружает нужный по описанию. Это экономит контекстное окно и позволяет иметь десятки skill md файлов без потери производительности.

CLAUDE.md - главная инструкция для ИИ-агента

Если claude skills - это отдельные навыки, то файл CLAUDE.md - это общая инструкция. Что-то вроде должностной инструкции для всей компании, а не для конкретной задачи.

В CLAUDE.md вы описываете:

• Контекст проекта - чем занимается проект, какой стек технологий и структура файлов.
• Правила работы - стиль кода, соглашения по именованию, что можно и нельзя делать.
• Частые команды - как запускать тесты, как деплоить, где лежит конфигурация.
• Предпочтения - ваш стиль общения, уровень детализации ответов, язык.

Зачем нужен CLAUDE.md? Без него ИИ-агент каждый раз начинает с нуля. Не знает вашего проекта, не знает ваших правил, не знает ваших предпочтений. CLAUDE.md решает это раз и навсегда - агент читает файл при старте сессии и работает в вашем контексте.

Пример фрагмента CLAUDE.md:

# Проект: SEO-блог

## Структура
- Статьи хранятся в папке `Статьи/`
- Инструменты в папке `Инструменты/`

## Правила
- Всегда использовать букву ё
- Никаких длинных тире, только дефисы
- Точки в конце пунктов-предложений

Я переписывал свой CLAUDE.md несколько раз, прежде чем нашёл оптимальный формат. Главное правило - будьте конкретны. "Пиши хороший код" - бесполезно. "Используй Python 3.11, type hints обязательны, docstrings в формате Google" - такое работает.

Связь CLAUDE.md и claude skills

CLAUDE.md и claude skills работают в паре. CLAUDE.md задаёт общие правила, а SKILL.md - конкретные алгоритмы. Это как в компании: есть корпоративная культура (CLAUDE.md), а есть регламенты для конкретных процессов (claude skills).

Когда ИИ-агент получает задачу, он сначала читает CLAUDE.md (понимает контекст), потом находит подходящий SKILL.md (понимает алгоритм) и выполняет задачу с учётом обоих файлов. Claude code agent именно так и работает - сочетает общие правила из CLAUDE.md со специализированными скиллами.

MCP-серверы - как ИИ-агент подключается к внешнему миру

MCP (Model Context Protocol) - это стандарт, через который ИИ-агент подключается к внешним инструментам. Если claude skills учат агента ЧТО нужно делать, то MCP-сервер даёт возможность это сделать. MCP-сервер даёт агенту руки: доступ к базам данных, API, браузеру и вообще к чему угодно.

Примеры MCP-серверов:

• postgres - прямые SQL-запросы к PostgreSQL без промежуточных файлов.
• github - работа с репозиториями, PR, issues прямо из агента.
• slack - отправка сообщений, чтение каналов.
• google-drive / google-sheets - работа с документами Google.
• browserbase / playwright - управление браузером.
• docker — управление контейнерами.
• clickhouse, mysql, mongodb — коннекторы к конкретным БД.

MCP-сервер - мост между ИИ-агентом и реальным миром. Один MCP-сервер = один набор инструментов. Серверов можно подключить сколько угодно, но каждый занимает место в системном промпте, поэтому держите только те, что реально нужны.

Как это работает вместе

Вот цепочка: вы даёте задачу → ИИ-агент читает CLAUDE.md (общие правила) → находит нужный SKILL.md (алгоритм) → вызывает MCP-сервер (инструмент) → получает результат → двигается к следующему шагу.

Пример из моей практики. У меня есть agent skill для SEO-анализа статей. Когда я запускаю его, claude code agent: 

1. Получает нашу статью из API блога. 
2. Через веб-поиск находит конкурентов. 
3. Встроенным инструментом WebFetch парсит их страницы. 
4. Считает плотность ключевых слов. 
5. Формирует отчёт и сохраняет файл.

Весь процесс занимает 2-3 минуты. Вручную это заняло бы часа полтора.

Где всё лежит: структура папок и settings.local.json

Когда начинаешь работать с ИИ-агентами, первый вопрос - куда что класть? Вот как устроена файловая структура Claude Code:

проект/
├── CLAUDE.md                      # Главная инструкция
├── .claude/
│   ├── skills/
│   │   ├── article/
│   │   │   └── SKILL.md           # Agent skill для создания статей
│   │   ├── compare/
│   │   │   └── SKILL.md           # Agent skill для SEO-сравнения
│   │   └── send/
│   │       └── SKILL.md           # Agent skill для публикации
│   ├── settings.json              # Настройки проекта (коммит в git)
│   └── settings.local.json        # Локальные настройки (НЕ коммитятся)
├── src/                           # Ваш код
└── ...

Для agent skills вы можете использовать папку commands и в ней создавать файлы article.md, compare.md, send.md и так далее. Claude будет понимать вас и так, но всё же папка skills - более свежий формат.

settings.json vs settings.local.json

Это два файла настроек, и разница между ними принципиальная:

• settings.json - настройки проекта которые шарятся с командой. Коммитятся в git. Сюда кладут общие правила: разрешённые команды, хуки, общие MCP-серверы.
• settings.local.json - ваши личные настройки. НЕ коммитятся. Сюда кладут токены, ключи API, персональные MCP-серверы.

Пример settings.local.json с подключением MCP-серверов:

{
  "permissions": {
    "allow": ["Bash(npm run *)"],
    "deny": ["Bash(rm -rf *)"]
  },
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "your_token_here"
      }
    }
  }
}

Именно здесь ИИ-агент узнаёт какие MCP-серверы ему доступны. Без записи в settings.local.json агент просто не увидит инструмент, даже если MCP-сервер установлен на машине.

Глобальные настройки

Помимо проектных, есть глобальные файлы - они действуют для всех проектов:

C:\Users\твоё_имя\.claude\
├── CLAUDE.md               # Глобальный claude md (для всех проектов)
├── commands/               # Глобальные команды-скиллы (доступны везде)
│   └── review.md           # Например, agent skill для код-ревью
├── settings.json           # Глобальные настройки
└── settings.local.json     # Глобальные личные настройки

Приоритет: проектный CLAUDE.md дополняет глобальный, проектные claude skills дополняют глобальные. Если один и тот же MCP-сервер описан в обоих settings.local.json - проектный побеждает.

Я держу общие вещи в глобальном CLAUDE.md (стиль общения, язык), а проектную специфику - в проектном. Глобальные claude skills - это то что нужно везде (код-ревью, коммиты), проектные - специфичные для задач (SEO-анализ, публикация в блог).

Зачем прописывать роли для AI agent

Один из самых недооценённых приёмов - давать AI agent конкретную роль. Не просто "помоги мне", а "ты senior Python-разработчик с 10-летним опытом в ETL-пайплайнах".

Почему это работает? Роль задаёт рамки. Без роли AI agent пытается быть универсальным - и в итоге посредственным во всём. С ролью он фокусируется на конкретной области и выдаёт результат на порядок лучше.

Примеры ролей которые я использую в claude skills:

• SEO-копирайтер - пишет с учётом ключевых слов, знает правила оптимизации.
• Code Reviewer - проверяет код на баги, предлагает улучшения, знает лучшие практики.
• Тестировщик - пишет тест-кейсы, ищет edge cases, думает как сломать систему.
• Дата-аналитик - работает с SQL и Python, строит отчёты, находит инсайты.

Каждая роль прописывается в agent skill или CLAUDE.md. Когда AI agent "надевает" роль - он начинает думать по-другому. Один и тот же claude code agent с ролью тестировщика найдёт баги, которые пропустит с ролью разработчика. Роль внутри agent skill - это как должностная инструкция для конкретного специалиста.

Практические примеры: как AI agent решает реальные задачи

Теория - это хорошо, но давайте посмотрим как AI agent работает на практике с помощью claude skills.

Пример 1: Автоматизация блога

У меня настроена цепочка claude skills для блога: /article - пишет SEO-статью с нуля: собирает ключи, анализирует конкурентов, пишет текст, генерирует Schema.org. /compare - сравнивает нашу статью с конкурентами по плотности ключей и даёт рекомендации. /send - публикует статью через API блога.

Каждый agent skill знает свой алгоритм и всё это управляется через CLAUDE.md, где прописаны правила проекта. Набор claude skills для блога сейчас покрывает 90% моей рутины - от сбора ключей до публикации.

Пример 2: Создание видео

Для создания видео по собранным материалам у меня настроена другая цепочка: 

/desing - дизайн-превью видео: HTML-файл с фоном, палитрой, шрифтами, SVG-паттерном.  Этот HTML становится эталоном для Remotion - программы для создания видео.

/cadr - 20 превью-кадров: генерирует TSX-компоненты для Remotion, рендерит ключевые моменты в PNG. Каждый элемент появляется строго по SRT-таймингу.

/render - финальный рендер: 1920×1080, 30fps, H.264. Видео длиннее 5 минут автоматически разбиваются на части, рендерятся параллельно, склеиваются через ffmpeg concat.

На выходе - вот такие обучающие видео без воды - только самое интересное и важное🔥

С чего начать работу с AI agent и claude skills

Если хотите попробовать - вот простой план:

1. Установите Claude Code. Это терминальный ИИ-агент от Anthropic. Работает через командную строку, но не пугайтесь - всё проще чем кажется.
2. Создайте CLAUDE.md. Опишите свой проект: чем занимаетесь, какой стек, какие правила. Даже пять строк CLAUDE.md уже сделают агента полезнее.
3. Напишите первый SKILL.md. Возьмите любую повторяющуюся задачу и опишите её по шагам. Это ваш первый agent skill.
4. Запустите и итерируйте. Первый скилл будет неидеальным. Это нормально. Доработаете за пару итераций.

Главное - не пытайтесь автоматизировать всё сразу. Начните с одного agent skill, доведите до ума, потом переходите к следующему. Я начинал с простого скилла для генерации отчётов и за несколько месяцев вырастил целую библиотеку claude skills для автоматизации блога, парсинга данных и анализа конкурентов.

Как итог

ИИ-агенты - это уже настоящее. AI agent уже сейчас закрывает рутинные задачи быстрее и качественнее, чем человек. Но чтобы он работал хорошо, нужна правильная настройка: claude md для контекста, skill md для алгоритмов, MCP-серверы для инструментов.

Главный инсайт: сила не в самой нейросети, а в том как вы её настроите. Хороший claude md + набор claude skills + правильные MCP-серверы = ИИ-агент который реально работает, а не просто красиво отвечает на вопросы. Пусть это будет вашей отправной точкой.