Набор навыков для AI-агентов: разбор репозитория skills

Разбираем репозиторий mattpocock/skills. Как структурировать инструкции для AI-агентов, чтобы они работали предсказуемо и решали инженерные задачи.

Что такое навыки для AI-агентов

Когда мы говорим об AI-агентах, часто возникает иллюзия, что достаточно просто «хорошо попросить» модель что-то сделать. Но если вы пробовали заставить LLM (Large Language Model) стабильно выполнять сложные инженерные задачи — например, анализировать логи или писать конфигурации для Nginx — вы знаете, что результат часто бывает непредсказуемым. Модель может галлюцинировать, забывать контекст или просто отклоняться от заданной логики.

Проблема здесь в том, что обычный промпт — это попытка передать и инструкцию, и контекст, и правила поведения в одном текстовом блоке. Это не масштабируется. Репозиторий mattpocock/skills предлагает другой подход: разделение логики поведения агента и его конкретных умений.

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

Концепция .agents directory

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

Структура проекта с использованием этого подхода выглядит примерно так:

text
my-ai-project/
├── .agents/
│   ├── analyzer.md       # Навык анализа логов
│   ├── k8s-deployer.md   # Навык деплоя в Kubernetes
│   └── sql-optimizer.md  # Навык оптимизации запросов
├── data/
│   └── logs/
└── main_agent.py         # Основной цикл управления агентом

Каждый файл в директории .agents представляет собой структурированную инструкцию. Это не просто текст, а набор правил, которые определяют:

Когда использовать этот навык (триггеры).
Какие данные нужны на вход (input schema).
Как должен выглядеть идеальный результат (output format).

С практической точки зрения это повышает предсказуемость. Когда агент понимает, что для задачи «проверить статус пода» ему нужно обратиться к конкретному файлу k8s-deployer.md, он не тратит токены на рассуждения о том, как это сделать вообще, а сразу переходит к выполнению алгоритма.

Почему стандартных промптов недостаточно

Главная проблема стандартных промптов — это «размытие» внимания модели. В теории это называется Lost in the Middle: когда контекстное окно перегружено разнородной информацией, модель начинает игнорировать инструкции, находящиеся в середине текста.

Если мы попытаемся уместить все знания инженера в один промпт, мы столкнемся с тремя проблемами:

Конфликт инструкций. Вы просите агента быть «кратким», но тут же даёте ему подробный гайд по отладке PostgreSQL. В итоге агент либо пишет слишком коротко, упуская детали, либо игнорирует требование краткости.
Сложность отладки. Если агент ошибся, в огромном промпте крайне трудно понять, какая именно часть инструкции сработала неверно. В подходе с навыками вы просто проверяете конкретный файл в .agents/.
Избыточность (Token Overhead). Постоянно передавать в каждом запросе 5000 токенов с описанием всех возможных действий — это дорого и медленно.

Сравните два подхода на примере задачи по проверке конфигурации Nginx.

Обычный промпт:

«Ты — эксперт по Nginx. Ты должен уметь проверять синтаксис, искать ошибки в директивах, проверять наличие SSL-сертификатов и советовать по оптимизации кэширования. Вот правила для каждого случая... [еще 2000 слов]»

Подход с навыками: Агент получает базовую роль. Когда он видит файл конфигурации, он подгружает только навык nginx-validator.md:

markdown
# Skill: Nginx Validator

## Context
Use this skill when the user provides an nginx.conf file or a snippet.

## Steps
1. Check syntax using `nginx -t` logic.
2. Verify that all `ssl_certificate` paths exist.
3. Ensure `client_max_body_size` is explicitly set.

## Output Format
Return a JSON object with:
- `status`: "valid" | "invalid"
- `errors`: list of strings
- `suggestions`: list of strings

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

Структура и применение навыков

Когда мы говорим об использовании AI-агентов в инженерных задачах, главная проблема — это не отсутствие «ума» у модели, а отсутствие чёткого контекста и границ ответственности. Если вы просто попросите агента «настроить Nginx», вы получите гадание на кофейной гуще. Репозиторий mattpocock/skills предлагает системный подход: вместо одного огромного промпта, перегруженного инструкциями, мы используем набор атомарных навыков.

Модульность инструкций

С практической точки зрения, модульность — это способ обеспечить предсказуемость. В системном администрировании мы не пишем один скрипт на 5000 строк, который делает всё: от установки ОС до настройки бэкапов. Мы создаем набор небольших, тестируемых скриптов или Ansible-ролей. С навыками для AI работает тот же принцип.

Вместо того чтобы скармливать агенту гигантский системный промпт, мы разбиваем его на специализированные модули. Каждый навык (skill) — это изолированная инструкция, которая описывает:

Что агент может делать.
Какие инструменты (tools) ему доступны.
В каком формате он должен отдавать результат.

Например, вместо общего навыка «DevOps-инженер», мы создаем отдельные модули: skill-docker-compose-validator, skill-systemd-unit-generator и skill-nginx-config-auditor.

Если мы посмотрим на структуру типичного навыка, он должен выглядеть не как поток сознания, а как спецификация. Пример того, как может быть описан навык для проверки конфигурации Docker Compose:

yaml
# Пример описания навыка (skill definition)
name: docker_compose_validator
description: Проверяет docker-compose.yml на наличие критических ошибок и соответствие best practices.
capabilities:
  - syntax_check: Проверка валидности YAML и структуры Compose.
  - security_audit: Поиск запуска контейнеров от root или использования привилегированных режимов.
  - network_check: Проверка корректности описания сетей.
output_format:
  type: json
  schema:
    errors: array
    suggestions: array
    status: string

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

Интеграция в рабочий процесс инженера

Навыки не должны существовать в вакууме — они должны встраиваться в существующий пайплайн. Для инженера ценность AI-агента не в том, что он «пишет код за вас», а в том, что он выступает в роли дополнительного звена контроля или автоматизации рутины.

Я рассматриваю интеграцию навыков через три сценария:

Pre-commit проверка. Агент с навыком аудита конфигов проверяет изменения перед тем, как они попадут в репозиторий. Это похоже на работу линтера, но с пониманием семантики.
Автоматизация отработки алертов. Если ваш мониторинг (например, Prometheus) сигнализирует о нехватке места на диске, агент с навыком disk-usage-analyzer может проанализировать логи, найти «виновника» и предложить конкретную команду для очистки.
Генерация документации и манифестов. Вместо написания systemd юнитов с нуля, вы даете агенту описание сервиса, и он, используя навык systemd-generator, выдает готовый файл.

Чтобы интеграция была предсказуемой, важно ограничить область действия агента. Если вы используете агента для управления инфраструктурой, он не должен иметь возможности выполнять произвольные команды rm -rf /. Его доступ должен быть ограничен через инструменты, которые он вызывает.

Пример интеграции в рабочий процесс через CLI-обертку:

bash
# Пример вызова агента с конкретным навыком для проверки конфигурации
ai-agent run --skill docker_compose_validator --file ./docker-compose.yml

В результате вы получаете не просто «совет», а структурированный отчет, который можно либо прогнать через grep, либо использовать в автоматизированном CI/CD пайплайне. Это превращает AI из «черного ящика» в предсказуемый инженерный инструмент.

Практическое использование репозитория

Примеры готовых навыков

Репозиторий mattpocock/skills ценен тем, что в нём нет абстрактных рассуждений — там лежат конкретные инструкции, которые можно сразу пробовать «в бою». Если рассматривать работу агента как работу младшего системного инженера, то навыки из этого репозитория — это своего рода должностные инструкции.

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

Во-первых, обратите внимание на навыки для работы с кодом. Вместо того чтобы просить агента «исправить ошибку», вы даёте ему структурированный навык, который заставляет его сначала провести диагностику. Например, если мы работаем с Docker-контейнерами, агент может использовать навык «Log Investigator», чтобы проанализировать вывод journald или логи конкретного сервиса.

Пример того, как может выглядеть запрос к агенту, у которого подключен навык анализа системных логов:

bash
# Сначала мы просим агента проверить состояние конкретного сервиса через systemd
systemctl status nginx.service

# Затем, если сервис упал, агент использует навык для чтения последних 50 строк лога
journalctl -u nginx.service -n 50 --no-pager

Во-вторых, полезны навыки, ориентированные на создание конфигураций. Вместо генерации «просто рабочего» конфига, агент, использующий навыки из репозитория, стремится к предсказуемости. Он проверяет синтаксис и структуру согласно стандартам. Если вы настраиваете Nginx, агент не просто выдаст блок server, а применит правила валидации, которые заложены в его инструкции.

Адаптация под собственные задачи

Копировать готовые файлы из репозитория — это только половина дела. Чтобы агент действительно приносил пользу в вашей среде, навыки нужно адаптировать под конкретный стек. Если у вас вся инфраструктура крутится на Proxmox и управляется через Ansible, стандартные навыки для работы с чистым Linux могут оказаться слишком поверхностными.

Чтобы внедрить собственный навык, я рекомендую следовать системному подходу. Не пытайтесь написать одну гигантскую инструкцию «Делай всё правильно». Разбейте её на атомарные действия.

Если вы хотите научить агента управлять вашим домашним сервером, создайте файл skills/manage_proxmox.md со следующей логикой:

markdown
# Skill: Proxmox VM Management

## Context
You are an expert in Proxmox VE administration. You have access to the `qm` command line tool.

## Instructions
1. Before any destructive action (stop, destroy), always check the current status of the VM:
   `qm status <vmid>`
2. When creating a new VM, ensure the storage backend is set to 'local-zfs' to maintain data integrity.
3. Always verify the network configuration after changing bridge settings.

## Constraints
- Never use 'qm destroy' without explicit confirmation of the VMID.
- Do not modify any VM that is part of the 'production' cluster tag without checking the backup status.

С точки зрения эксплуатации, такая структура даёт два преимущества:

Предсказуемость: Агент знает границы дозволенного. Он не удалит виртуальную машину просто потому, что «так быстрее починить проблему».
Отладка: Если агент совершил ошибку, вы точно знаете, в какой части инструкции (Context, Instructions или Constraints) допущена неточность.

Если вы планируете использовать агентов для автоматизации бэкапов или мониторинга, всегда добавляйте в раздел Constraints запрет на выполнение команд без предварительной проверки свободного места на диске. Это избавляет от классических сценариев, когда скрипт автоматизации «забивает» раздел /var/log или хранилище ZFS, вызывая каскадный отказ всей системы.

Ограничения и предсказуемость

Когда мы переходим от простых чат-ботов к полноценным AI-агентам, которые должны выполнять инженерные задачи, главная проблема смещается из плоскости «насколько умная модель» в плоскость «насколько предсказуемо она следует инструкциям». В репозитории mattpocock/skills подход к структурированию навыков как раз и направлен на то, чтобы минимизировать хаос.

Риски галлюцинаций при сложных инструкциях

Основная ловушка при проектировании агентов — попытка впихнуть в один системный промпт слишком много логики. Если вы дадите агенту список из двадцати взаимосвязанных правил, он неизбежно начнет «срезать углы». В системном администрировании это эквивалентно попытке написать один скрипт на 5000 строк, который делает всё: от бэкапа до развертывания кластера. Такой скрипт невозможно отлаживать, и он начинает вести себя непредсказуемо при малейшем изменении среды.

Галлюцинации в контексте навыков (skills) проявляются не только в выдуманных фактах, но и в нарушении логики выполнения. Например, агент может решить, что после выполнения команды docker compose up -d ему не нужно проверять статус контейнеров, потому что «он же уверен, что всё прошло успешно».

С практической точки зрения, проблема усугубляется, когда инструкции противоречат друг другу или слишком размыты. Если в навыке написано «настрой Nginx оптимально», агент выдаст конфигурацию, которая будет зависеть от его весов, а не от ваших требований к безопасности или производительности.

Как обеспечить стабильный результат

Чтобы добиться предсказуемости, нужно следовать принципу атомарности. Один навык — одна узкая задача. Вместо огромного промпта лучше создать набор маленьких, проверяемых модулей.

Во-первых, используйте жесткую структуру вывода. Если агент должен вернуть конфигурацию, он не должен добавлять к ней вводные фразы вроде «Вот ваш конфиг:». Для этого в описании навыка стоит явно указать формат, например, JSON или чистый YAML.

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

yaml
skill: manage_service
description: Запуск и проверка статуса системной службы
steps:
  - action: "systemctl start <service_name>"
    description: "Запуск службы через systemctl"
  - action: "systemctl is-active <service_name>"
    description: "Проверка, что служба действительно перешла в состояние active"
    expected_output: "active"

В этом примере мы не просто просим «запусти сервис», мы заставляем агента выполнить проверку состояния. Если is-active вернет inactive, агент должен зафиксировать ошибку, а не продолжать работу, как будто всё в порядке.

В-третьих, ограничивайте область видимости. Если агент работает с файловой системой, дайте ему четкие границы. Вместо «работай с конфигами» используйте «редактируй только файлы в директории /etc/nginx/conf.d/».

Для автоматизации контроля за такими навыками можно использовать подход с unit-тестами для промптов. Вы подаете на вход агенту конкретный сценарий и проверяете, соответствует ли его вывод заданному шаблону. Это позволяет отловить деградацию логики при обновлении версии модели или изменении описания навыка.

Заключение

Итоговые мысли по структуре навыков

Если подводить итог, репозиторий mattpocock/skills — это не просто набор текстовых файлов, а попытка перенести инженерный подход к управлению конфигурациями на почву промпт-инжиниринга. Вместо того чтобы пытаться впихнуть в один системный промпт все знания мира, мы разделяем их на атомарные, переиспользуемые модули.

С практической точки зрения, такой подход даёт две вещи: предсказуемость и масштабируемость. Когда вы даёте агенту навык «настройка Nginx», вы не надеетесь на его «интуицию», а передаёте чёткий алгоритм действий. Если агент ошибается, вы правите не гигантский промпт, а конкретный файл навыка.

Когда этот подход работает, а когда — нет

Разделение на навыки идеально подходит для задач, где есть чёткая последовательность действий или строгие стандарты. Например, если вы строите пайплайн для автоматизации развёртывания инфраструктуры через Ansible или Terraform.

Когда стоит внедрять skills:

Стандартизация: когда нужно, чтобы разные агенты (или один агент в разное время) генерировали конфиги в одном стиле.
Сложные цепочки: когда задача состоит из нескольких этапов (сначала аудит, потом исправление, затем проверка).
Ограничение контекста: вместо того чтобы скармливать модели всю документацию Kubernetes, вы подключаете только нужный навык k8s-kubectl-usage.

Где подход буксует:

Творческие задачи: если от агента требуется генерация нестандартного контента, избыточная структурированность навыков только ограничит его «фантазию».
Слишком мелкая гранулярность: если вы разобьёте навыки на слишком мелкие части (например, отдельный навык на каждую команду ls), вы получите огромные накладные расходы на управление контекстом.

Как внедрять это в свою лабораторию

Если вы решите протестировать эту методологию на своих проектах, не пытайтесь сразу переписать всё. Начните с малого. Возьмите одну повторяющуюся задачу — например, создание Docker Compose файлов для ваших сервисов — и опишите её как навык.

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

bash
# Пример структуры каталога навыков для домашнего сервера
skills/
├── networking/
│   ├── nginx-proxy-manager.md
│   └── tailscale-setup.md
├── storage/
│   ├── zfs-dataset-creation.md
│   └── nfs-export-rules.md
└── monitoring/
    └── prometheus-alertmanager.md

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

FAQ

Как добавить свой навык в систему?

Чтобы внедрить новый навык, нужно следовать структуре, заложенной в репозитории mattpocock/skills. Навык — это не просто текст, а атомарная единица действия, которая должна иметь чёткое описание, чтобы агент мог понять, когда именно его стоит вызвать.

С практической точки зрения процесс выглядит так:

Определите конкретную задачу, которую агент должен выполнять (например, «анализ логов Nginx»).
Создайте файл в формате YAML или JSON, где опишите description (для планировщика агента) и instructions (сама логика выполнения).

Пример структуры нового навыка для работы с системными метриками:

yaml
name: system_metrics_analyzer
description: Анализирует показатели загрузки CPU и RAM, выявляя аномалии.
instructions: |
  1. Получи текущие метрики через команду `top -b -n 1`.
  2. Сравни значения с пороговыми (CPU > 80%, RAM > 90%).
  3. Если порог превышен, сформируй отчет с указанием процесса-виновника.

Нужно ли использовать этот репозиторий для простых чат-ботов?

Если ваша задача — создать бота, который просто отвечает на вопросы по базе знаний или поддерживает беседу в стиле «помощника», этот подход будет избыточным. Вы только усложните архитектуру и увеличите количество токенов в контексте.

Подход с навыками нужен там, где требуется предсказуемость выполнения инженерных задач. Если бот должен не «рассуждать» о коде, а, например, проверять статус контейнеров в Docker или выполнять миграции базы данных, то разделение на навыки обеспечит контроль. Для простых чат-ботов достаточно системного промпта, а для агентов-исполнителей необходима модульная структура.

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

Разница заключается в области ответственности и способе управления контекстом.

Промпт (System Prompt) — это общие правила поведения, «личность» агента и его глобальные ограничения. Он задаёт тон общения и общие принципы (например, «отвечай только на технические вопросы»).
Навык (Skill) — это специализированный инструмент для решения узкой задачи.

Если мы посмотрим на это через призму системного администрирования, то промпт — это как конфигурация sshd_config, определяющая общие правила доступа к серверу, а навык — это конкретный скрипт в /usr/local/bin/, который выполняет определённое действие по запросу. Навыки позволяют не перегружать основной промпт лишней информацией, вызывая только нужные инструкции в момент необходимости.

Поддерживает ли этот подход мультиагентные системы?

Да, и это, пожалуй, главное преимущество. В мультиагентных системах (MAS) навыки становятся общим интерфейсом взаимодействия между разными сущностями.

Вы можете построить архитектуру, где:

Агент-диспетчер (Orchestrator) получает запрос от пользователя.
Он анализирует доступный набор навыков из репозитория.
Делегирует задачу Агенту-исполнителю (Worker), передавая ему конкретный навык.

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

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

Чем подход с навыками отличается от обычного системного промпта?

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

Можно ли использовать этот подход для автоматизации инфраструктурных задач?

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

Как масштабировать библиотеку навыков при росте проекта?

С практической точки зрения, масштабирование происходит через модульность, аналогичную управлению конфигурациями в Ansible. Вы создаёте новые файлы в директории .agents для каждой новой атомарной задачи, не перегружая основной цикл управления. Это позволяет добавлять новые возможности агенту, не рискуя сломать уже работающие инструкции.

Нужно ли переписывать весь промпт агента под каждый новый навык?

Нет, в этом и заключается преимущество архитектуры. Основной промпт отвечает за высокоуровневую логику и принятие решений, а навыки подключаются динамически в зависимости от контекста задачи. Если агенту нужно выполнить деплой в Kubernetes, он обращается к соответствующему файлу в .agents, не отвлекаясь на инструкции по оптимизации SQL-запросов.