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

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

Что такое Skills и зачем они инженеру

Когда мы говорим об использовании больших языковых моделей (LLM) в инженерных задачах, часто возникает ложное ощущение, что достаточно просто дать модели доступ к терминалу и написать в промпте: «Исправь ошибку в конфигурации Nginx». На практике это превращается в лотерею. Модель может попытаться переписать весь конфиг, нарушить синтаксис или, что ещё хуже, применить решение, которое решит локальную проблему, но сломает всю цепочку зависимостей.

Проект mattpocock/skills предлагает системный подход к этой проблеме. Вместо того чтобы полагаться на общие знания модели, концепция Skills (навыков) предполагает создание атомарных, строго описанных инструментов, которые агент может вызывать для выполнения конкретных действий.

Концепция навыков для автономных агентов

Если проводить аналогию с системным администрированием, то использование LLM без структурированных навыков — это как попытка управлять сервером через чат-бота, который просто «знает Linux». Это непредсказуемо. Концепция Skills переводит работу агента в плоскость вызова конкретных функций с чётко заданными параметрами.

Навык в данном контексте — это не просто текстовая инструкция, а связка из трёх элементов:

Описания (Description): что именно делает навык и в каких ситуациях его стоит применять.
Интерфейса (Schema): какие аргументы принимает навык (например, путь к файлу или IP-адрес).
Реализации (Implementation): конкретный код или последовательность команд, которые выполняются «под капотом».

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

Пример того, как может выглядеть описание навыка в формате JSON для агента:

json
{
  "skill_name": "validate_nginx_config",
  "description": "Проверяет синтаксическую корректность конфигурационных файлов Nginx без перезагрузки сервиса.",
  "parameters": {
    "config_path": {
      "type": "string",
      "description": "Полный путь к файлу конфигурации или директории"
    }
  },
  "expected_outcome": "Возвращает true, если синтаксис верен, и сообщение об ошибке, если есть нарушения."
}

Проблема непредсказуемости LLM в сложных задачах

Основная сложность при работе с автономными агентами в инфраструктурных задачах — это галлюцинации и нарушение логики выполнения. В инженерной среде цена ошибки слишком высока. Если агент решит, что для «оптимизации базы данных» нужно просто выполнить rm -rf /var/lib/postgresql/data, это станет катастрофой.

Проблема непредсказуемости проявляется в нескольких аспектах:

Дрейф контекста: В длинных сессиях агент может «забыть» о предыдущих ограничениях или установленных правилах безопасности.
Избыточность действий: Модель может пытаться выполнить одно и то же действие несколько раз, если не получает мгновенного подтверждения успеха.
Некорректный синтаксис: При генерации сложных команд (например, сложных конвейеров awk или sed) модель часто допускает ошибки в экранировании символов.

Использование Skills позволяет ограничить область «творчества» модели. Мы не даём ей право генерировать произвольный код для управления системой. Мы даём ей набор инструментов, каждый из которых прошел проверку.

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

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

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

Анализ содержимого директории .agents

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

Структура типичного навыка в этой директории строится на трёх столпах:

Контекст (Context): что именно этот навык умеет и в каких ситуациях его применять.
Инструментарий (Tools): какие команды или API-вызовы доступны в рамках этого навыка.
Ограничения (Constraints): что агенту делать категорически нельзя.

С практической точки зрения это напоминает создание интерфейсов в программировании. Мы не просто просим агента «быть системным администратором», мы определяем набор методов, которые он может вызвать. Например, если мы создаём навык для работы с Docker, мы не пишем «управляй контейнерами», мы описываем конкретные сценарии: проверку статуса, чтение логов и перезапуск сервиса.

Как превратить общие инструкции в конкретные инструменты

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

Представим, что нам нужно научить агента работать с системными логами через journald. Вместо того чтобы давать ему доступ ко всей системе, мы создаём специализированный навык. В файле конфигурации навыка (в формате Markdown или JSON, в зависимости от используемого фреймворка) это будет выглядеть примерно так:

markdown
# Skill: Journald Log Analyzer

## Description
Анализирует системные логи через journalctl для поиска ошибок в конкретных юнитах systemd.

## Capabilities
- Вывод последних 50 строк логов для указанного сервиса.
- Поиск ошибок (priority level err или выше) за последние 15 минут.

## Constraints
- Запрещено использовать команду `journalctl --vacuum-time`, так как это удаляет логи.
- Запрещено анализировать логи ядра (dmesg) без явного запроса пользователя.

## Execution Command
При поиске ошибок используй:
`journalctl -u {{service_name}} --since "15 min ago" -p err`

Обратите внимание на использование плейсхолдера {{service_name}}. Это превращает инструкцию в шаблон. Теперь агент не просто «читает логи», он выполняет функцию с чётко заданными параметрами.

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

Для достижения предсказуемости в инженерных задачах я рекомендую придерживаться правила: один навык — одна зона ответственности. Если агент должен уметь и настраивать Nginx, и проверять доступность портов, это должны быть два разных файла в директории .agents. Это упрощает отладку: если агент ошибается в проверке портов, вы правите только навык network-check, не рискуя сломать логику конфигурации веб-сервера.

Практическое внедрение в рабочий процесс

Интеграция навыков в существующие пайплайны

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

С практической точки зрения, интеграция навыков лучше всего работает через CLI-интерфейсы или API-вызовы внутри ваших CI/CD пайплайнов. Вместо того чтобы просить LLM «проверь конфигурацию Nginx», вы должны передать ей конкретный навык (skill), который умеет парсить конфиг и сопоставлять его с правилами безопасности.

Если вы используете GitHub Actions или GitLab CI, навык агента можно обернуть в небольшой скрипт, который будет запускаться на этапе линтинга или тестирования. Например, при изменении инфраструктурного кода (Terraform или Ansible) агент может использовать навык для проверки соответствия политике безопасности вашей домашней лаборатории.

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

bash
# Запуск агента с передачей контекста навыка для проверки Docker-конфигурации
ai-agent run --skill "docker-security-audit" \
  --input "./docker-compose.yml" \
  --output "./audit-report.md"

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

Обеспечение повторяемости результатов

Главная проблема при работе с AI-агентами — это непредсказуемость. Сегодня агент выдал правильный конфиг для PostgreSQL, а завтра, из-за обновления весов модели или изменения промпта, предложил решение, которое уронит базу. Для системного инженера такая нестабильность неприемлема.

Чтобы добиться предсказуемости, нужно разделять «интеллект» модели и «логику» навыка. Навык в концепции Matt Pocock — это, по сути, жестко структурированная инструкция. Чтобы результат был повторяемым, я рекомендую придерживаться трёх правил:

Версионирование навыков. Никогда не используйте «последнюю версию» промпта из интернета. Если вы нашли полезный набор инструкций в репозитории, скопируйте его в свой внутренний Git-репозиторий. Так вы будете точно знать, какой именно набор правил применил агент к вашему серверу.
Использование JSON-схем для вывода. Агент не должен писать «простыню» текста. Навык должен требовать от модели ответ строго в определённом формате. Это позволяет автоматизировать проверку результата.
Тестирование навыков (Skill Testing). Перед тем как пустить агента в продакшн (или на основной сервер), прогоните его через набор тестовых кейсов.

Если вы настраиваете агента для автоматизации бэкапов на вашем TrueNAS, ваш конфиг взаимодействия с навыком должен выглядеть примерно так (в формате системного промпта):

json
{
  "skill_name": "backup-validation",
  "version": "1.2.0",
  "output_format": "json",
  "constraints": {
    "required_fields": ["status", "storage_path", "checksum_verified"],
    "allowed_values": {
      "status": ["success", "failed", "warning"]
    }
  },
  "instructions": "Проверь целостность бэкапа по пути {{input_path}}. Сравни контрольную сумму с {{expected_checksum}}."
}

Такой подход превращает работу с AI из лотереи в контролируемый процесс. Если агент вернёт статус failed в поле status, ваш пайплайн просто остановится и отправит алерт в мониторинг, вместо того чтобы пытаться «договориться» с моделью о том, что всё в порядке. Предсказуемость достигается не за счёт того, что модель становится умнее, а за счёт того, что мы ограничиваем пространство её маневров чёткими рамками навыка.

Ограничения и риски использования готовых наборов

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

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

Когда стандартные навыки не работают

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

Во-первых, если ваш домашний сервер использует кастомную сеть в Docker (например, через отдельный bridge с фиксированными подсетями), агент с общим навыком «управления контейнерами» будет пытаться пробросить порты или подключать сети, которые не существуют в вашем окружении.

Во-вторых, версии софта. Если навык заточен под современный docker compose (V2), а вы по привычке или из-за ограничений ОС используете старый docker-compose (V1), агент будет генерировать синтаксис, который вызовет ошибку парсинга.

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

yaml
# Агент пытается использовать feature, которая не поддерживается старой версией compose
services:
  db:
    image: postgres:15
    deploy:
      resources:
        limits:
          cpus: '0.50'
          memory: 512M

Если ваша среда не поддерживает секцию deploy (например, вы запускаете это просто через docker-compose up без Swarm), вы получите ошибку. Без контекста о конкретной версии инструмента агент не сможет скорректировать свои действия.

Необходимость кастомизации под конкретный стек

Чтобы агент перестал быть «теоретиком» и стал полезным инструментом, навыки нужно адаптировать под ваш конкретный стек. Это не значит, что нужно переписывать всё с нуля. Это значит, что нужно добавить в системный промпт или в описание навыка жесткие ограничения и правила вашего окружения.

С практической точки зрения, кастомизация должна включать:

Версионность инструментов. Чётко укажите: «Используй только синтаксис Docker Compose V2».
Пути и файловую структуру. Если у вас все конфиги лежат в /opt/infrastructure/, агент не должен предлагать создавать их в домашней директории пользователя.
Методы проверки. Вместо того чтобы просто просить «настрой Nginx», добавьте в навык обязательный шаг проверки конфигурации.

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

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

bash
# Вместо абстрактного "проверь, что всё работает"
# Инструктируем агента использовать конкретные проверки:

# 1. Проверка синтаксиса конфигурации Nginx
nginx -t

# 2. Проверка доступности порта внутри сети Docker
docker exec <container_name> nc -zv localhost 80

# 3. Проверка статуса сервиса через systemd (если агент работает на хосте)
systemctl is-active nginx

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

FAQ

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

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

С практической точки зрения, универсальная инструкция часто страдает от избыточности. Если ваш агент работает только с инфраструктурой на базе Debian, нет смысла заставлять его учитывать нюансы управления пакетами в Red Hat. Переписывание под контекст позволяет:

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

Если вы используете навыки для автоматизации CI/CD, адаптируйте их под конкретные инструменты. Например, вместо общего навыка «написание скриптов» лучше создать узкоспециализированный навык для генерации Makefile или Taskfile, который учитывает специфику вашей файловой структуры.

Какие модели лучше всего работают с этими инструкциями?

Эффективность навыков напрямую зависит от способности модели следовать сложным системным промптам и соблюдать заданную структуру. На текущий момент наиболее предсказуемые результаты показывают модели семейства Claude 3.5 Sonnet и GPT-4o.

Claude особенно хорош в работе с длинными контекстами и нюансами инструкций, которые заложены в методологии Skills. Если вы планируете использовать локальные модели через Ollama, ориентируйтесь на Llama 3 (70B) или специализированные кодинг-модели вроде DeepSeek-Coder. Маленькие модели (7B–8B параметров) часто «забывают» часть инструкций навыка или начинают игнорировать формат вывода, что сводит на нет всю идею структурированного подхода.

Можно ли использовать эти навыки без использования Claude?

Безусловно. Методология построена на разделении логики (что нужно сделать) и формата (как это должно выглядеть). Это универсальный инженерный подход к промпт-инжинирингу.

Вы можете внедрить эти навыки в любой инструмент, который поддерживает системные инструкции (System Prompt). Например, если вы строите своего агента через LangChain или используете OpenAI Assistants API, вы просто передаёте содержимое навыка в поле instructions.

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

python
import openai

# Пример передачи навыка как системной инструкции
system_skill = """
You are a Linux Sysadmin Skill. 
When asked to analyze logs, always output in JSON format:
{
  "error_level": "string",
  "service": "string",
  "root_cause": "string"
}
"""

response = openai.ChatCompletion.create(
  model="gpt-4",
  messages=[
    {"role": "system", "content": system_skill},
    {"role": "user", "content": "Analyze: journalctl -u nginx | tail -n 5"}
  ]
)

print(response.choices[0].message.content)

Как проверить эффективность добавленного навыка?

Я сторонник подхода, при котором любое изменение должно быть измеримым. Недостаточно просто сказать: «Кажется, теперь он пишет лучше». Нужно внедрить процесс оценки.

Во-первых, создайте набор «золотых тестов» (Golden Dataset) — это список из 5–10 типичных задач, которые вы планируете поручать агенту. Во-вторых, используйте метрики соответствия формату. Если ваш навык требует вывода в формате JSON, проверьте, проходит ли ответ через валидатор.

Простой способ автоматизации проверки в вашей локальной лаборатории — написать bash-скрипт, который прогоняет промпт через API и проверяет результат:

bash
#!/bin/bash

# Простая проверка: содержит ли ответ ожидаемый тег или формат
PROMPT="Analyze the following error: [error message]"
SKILL_FILE="./skills/log_analyzer.md"

RESPONSE=$(curl -s https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"gpt-4\",
    \"messages\": [
      {\"role\": \"system\", \"content\": \"$(cat $SKILL_FILE)\"},
      {\"role\": \"user\", \"content\": \"$PROMPT\"}
    ]
  }" | jq -r '.choices[0].message.content')

if echo "$RESPONSE" | grep -q "{"; then
  echo "Success: Valid JSON structure found."
else
  echo "Failure: Skill did not follow the JSON format requirement."
  exit 1
fi

Если после обновления навыка процент успешных прогонов падает — значит, вы внесли слишком много неопределённости или перегрузили инструкцию лишними деталями.