Использование AI-агентов для автоматизации рутинных задач проекта

Самый быстрый способ прекратить повторно объяснять агенту устройство вашего проекта — один раз зафиксировать рецепт в виде навыка Claude Code (Claude Code skill): директории с файлом SKILL.md, зафиксированной в репозитории, которую агент читает вместо того, чтобы заново выяснять, как запустить, засеять или задеплоить приложение.

Каждый, кто наблюдал, как агент тратит десять минут на повторное обнаружение того, что приложение не запустится без засеянной базы данных и скопированного env-файла, знает это чувство. Вы объясняли эти шаги на прошлой неделе и позапрошлой тоже. В этой статье описан конкретный паттерн: чем навык отличается от npm-скрипта, где хранится навык уровня проекта, и приведён рабочий пример, который поднимает приложение с чистого чекаута и верифицирует его. Тезис прост: перестаньте писать одноразовые скрипты, о которых потом забудете, и добавьте в проект навык агента, которым пользуется вся команда вместе с самим агентом.

Реальная цена забываемых npm-скриптов и устаревающей документации

Самая дорогостоящая часть устаревшего процесса настройки — не сломанная команда: это то, что человек или агент заново выводит рецепт каждый раз. В package.json накапливаются загадочные записи (predev:seed, db:reset:ci, start:tunnel), порядок выполнения и предусловия которых существуют лишь в голове одного инженера. Раздел «Getting Started» в README выходит из синхронизации в тот момент, когда кто-то добавляет переменную окружения и забывает её задокументировать. Новые участники команды угадывают; AI-агент тоже угадывает, и оба угадывают по-разному.

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

В чём разница между скриптом и навыком?

Используйте скрипт для шагов, которые никогда не должны меняться, и навык — для шагов, требующих интерпретации. npm-скрипт выполняет фиксированные команды в заранее определённой последовательности; навык использует модель для чтения контекста, обработки вариативности и принятия решений о следующем шаге, после чего передаёт детерминированные части обратно коду. Это взаимодополняющие инструменты, а не конкуренты.

Инженерная команда Anthropic аргументирует в пользу сохранения детерминированной работы в коде: определённые операции лучше подходят для традиционного выполнения кода, поскольку сортировка списка через генерацию токенов медленнее и менее надёжна, чем запуск алгоритма сортировки, а многие рабочие процессы требуют воспроизводимости, которую обеспечивает только код. Принципиально важно, что встроенный скрипт остаётся дешёвым с точки зрения контекста: агентам с доступом к файловой системе и инструментами выполнения кода не нужно загружать весь навык в контекстное окно, а значит, объём ресурсов, которые можно упаковать в навык, фактически не ограничен.

Что такое навык Claude Code и где он хранится?

Навык Claude Code — это директория, содержащая файл SKILL.md, YAML-фронтматтер которого сообщает агенту, когда его использовать. Согласно обзору Agent Skills, каждый навык упаковывает инструкции, метаданные и опциональные ресурсы (скрипты, шаблоны), которые Claude автоматически использует при необходимости. Это правильная ментальная модель: навык — это директория, а не отдельный командный файл.

Расположение определяет область видимости. Навыки проекта загружаются из .claude/skills/ в вашей стартовой директории и в родительских директориях вплоть до корня репозитория, поэтому агент, работающий в любом месте внутри проекта, увидит навык как доступный, и он автоматически загружается, когда запрос соответствует его описанию. Личные навыки хранятся в ~/.claude/skills/. Для Claude Code конкретно рекомендуется указывать только description; поле name необязательно и по умолчанию совпадает с именем директории, которое вы также вводите после /.

Строительные блоки легко перепутать, поэтому выбирайте осознанно:

• Навык (Skill): директория + SKILL.md, опциональные встроенные скрипты. Автоматически обнаруживается по description и вызывается командой /skill-name. Также работает в Claude.ai и Claude Desktop, поэтому команда может использовать его за пределами терминала.
• Slash-команда: исторически — отдельный .md-файл в .claude/commands/. Кастомные команды были объединены с навыками: файл .claude/commands/deploy.md и навык .claude/skills/deploy/SKILL.md оба создают /deploy и работают одинаково. При конфликте имён приоритет отдаётся навыку.
• Субагент (Subagent): .md-файл в .claude/agents/, который работает в собственном контекстном окне и возвращает дистиллированный результат. Прибегайте к нему, когда задача достаточно объёмна по чтению, чтобы засорить основной поток.

Практический пример: фиксируем «запуск с чистого чекаута и верификацию»

Превратите ваш ритуал настройки в зафиксированный навык. Создайте .claude/skills/run-app/SKILL.md с description, достаточно конкретным для сопоставления агентом, живым выводом команд в начале и пронумерованными шагами:

---
name: run-app
description: Get this app running from a clean checkout and verify it boots. Use when setting up the project, onboarding, or checking the app still starts after a change.
allowed-tools: Bash(npm *) Bash(./scripts/verify.sh *)
---

## Environment
```!
node --version
npm --version
```

## Steps
1. Install dependencies with `npm ci`.
2. If `.env` is missing, copy `.env.example` to `.env`; ask before overwriting.
3. Start the app with `npm run dev`.
4. Run `./scripts/verify.sh` and report PASS or FAIL.

Expected output: a single PASS/FAIL line and the local URL the app serves on.

Блок с ```! использует динамическое внедрение контекста: Claude Code выполняет эти команды и встраивает вывод до того, как агент читает навык, поэтому рецепт поступает уже привязанным к вашему реальному инструментарию, а не к предположениям. Спросите «запусти приложение», и агент загрузит навык по его описанию; введите /run-app, чтобы вызвать его принудительно.

Claude Code также поставляется с этим паттерном в виде встроенного навыка. Команда /run-skill-generator поднимает ваше приложение с чистого окружения, фиксирует то, что сработало (команды установки, переменные окружения, скрипт запуска), и сохраняет это как навык уровня проекта в .claude/skills/run-<name>/. После этого /run, /verify и любой другой агент в репозитории следуют записанному рецепту вместо того, чтобы заново его выяснять. Команды /run, /verify и /run-skill-generator требуют Claude Code v2.1.145 или новее.

Сделайте навыки надёжными, затем зафиксируйте их

Делайте каждый навык атомарным и явно указывайте ожидаемый результат: один навык, одна задача, один чётко определённый результат, который можно проверить в pull request. Расплывчатые инструкции порождают дрейф; определённый формат вывода обеспечивает согласованность запусков и делает последующий парсинг надёжным.

Перенесите неизменные шаги в встроенный scripts/verify.sh, а тело SKILL.md оставьте для интерпретации: сообщения о причине сбоя верификации, обнаружения отсутствующей переменной окружения. Именно это разделение делает рабочий процесс воспроизводимым, а не вероятностным.

Честно признайте одно реальное ограничение: автоматический вызов полностью зависит от description, и он срабатывает не всегда. Первый шаг отладки в документации — проверить, содержит ли описание ключевые слова, которые пользователи естественно произносят. Когда вам нужен гарантированный ручной запуск (для всего, что имеет побочные эффекты), установите disable-model-invocation: true, чтобы навык запускался только при вводе /name.

Затем зафиксируйте .claude/skills/ в системе контроля версий. Этот единственный шаг замыкает круг: рецепт становится версионированным, проверяемым и общим, поэтому следующий участник команды и следующая сессия агента получают готовую рабочую процедуру вместо того, чтобы восстанавливать её заново. Навыки доступны в Claude.ai, Claude Code и через API, и согласно документации поддержки Anthropic они также находятся в бета-версии для пользователей Claude Code и для всех пользователей API, использующих инструмент выполнения кода, — поэтому зафиксированный навык проекта путешествует вместе с репозиторием, а не хранится в истории команд одного человека.

Начните с вашей наиболее повторяемой задачи (запуск с чистого чекаута, changelog для релиза, seed и сброс базы данных): напишите её SKILL.md, упакуйте детерминированную часть как скрипт и зафиксируйте. В следующий раз, когда кому-либо (или агенту) понадобится этот рецепт, он уже будет записан.

Часто задаваемые вопросы

Можно ли вызвать навык Claude Code вручную, или он срабатывает только автоматически?

Можно и так, и так. По умолчанию и вы, и Claude можете вызвать любой навык: введите /skill-name для прямого запуска, а Claude может загрузить его автоматически, когда его описание соответствует вашему запросу. Устаревшие руководства, утверждающие, что навыки нельзя запустить вручную, неактуальны. Если вы хотите только ручной запуск для навыка с побочными эффектами, установите disable-model-invocation в true, чтобы он срабатывал только при вводе его имени.

Что происходит, когда slash-команда и навык имеют одинаковое имя?

Приоритет отдаётся навыку. Кастомные команды были объединены с навыками: файл .claude/commands/deploy.md и навык .claude/skills/deploy/SKILL.md оба создают одну и ту же команду /deploy и работают идентично. Когда оба существуют под одним именем, Claude Code загружает навык, а не командный файл, поэтому нет необходимости поддерживать оба для одной команды.

Потребляет ли встроенный скрипт внутри навыка токены контекстного окна?

Нет. Когда инструкции навыка ссылаются на исполняемый скрипт, Claude запускает его через bash и получает только вывод; сам код скрипта никогда не попадает в контекстное окно. Именно поэтому упаковка детерминированной работы в скрипт дешевле и надёжнее, чем просьба к модели рассуждать над ней, и именно поэтому ресурсы, которые может включать навык, фактически не ограничены по размеру.

Нужно ли платить за план, чтобы использовать навыки Claude Code?

Нет. Согласно документации поддержки Anthropic, навыки доступны в планах Free, Pro, Max, Team и Enterprise, и для работы функции требуется включённое выполнение кода. В Claude Code конкретно навыки доступны в бета-версии, а также работают для всех пользователей API, использующих инструмент выполнения кода. Детали доступности часто меняются, поэтому уточняйте актуальную информацию в текущей документации поддержки Anthropic.