Средний

Набор навыков для AI-агентов от Matt Pocock

Алексей Кузнецов
Алексей Кузнецов
Системный администратор25 октября 2026 г.12 мин чтения

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

Набор навыков для AI-агентов от Matt Pocock

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

Зачем агентам нужны специализированные навыки

Зачем агентам нужны специализированные навыки

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

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

Проблема размытых промптов

Главная беда длинных инструкций — потеря фокуса. LLM (Large Language Models) имеют свойство «забывать» или игнорировать детали, которые находятся в середине длинного контекстного окна. Если вы просите агента «быть экспертом по DevOps, писать тесты на Go и при этом следить за безопасностью Docker-контейнеров», вы получаете посредственный результат по всем трем направлениям.

Размытый промпт создаёт неопределённость. Вместо чёткого алгоритма действий агент начинает гадать, какой приоритет у задачи в данный момент. Это убивает предсказуемость — ключевой параметр любой инженерной системы.

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

text
// Плохой промпт (размытый контекст)
Ты — опытный системный администратор. 
Проверь этот конфиг Nginx на ошибки. 
Убедись, что там настроены SSL, заголовки безопасности и всё работает быстро. 
Выдай результат в удобном виде.

В таком случае агент может сосредоточиться на синтаксисе, но забыть про заголовки безопасности, или наоборот — расписать теорию SSL, не указав на конкретную ошибку в директиве ssl_protocols.

Принцип модульности в управлении AI

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

Если мы перенесём это на язык инфраструктуры, то вместо одного огромного конфига мы используем принцип разделения ответственности. В контексте AI-агентов это выглядит так:

  1. Skill: Syntax Checker — проверяет только валидность синтаксиса.
  2. Skill: Security Auditor — ищет уязвимости в конфигурации.
  3. Skill: Performance Optimizer — анализирует настройки кэширования и буферов.

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

С точки зрения реализации, это можно представить как набор системных инструкций, которые подгружаются в контекст только тогда, когда они необходимы. Например, если мы автоматизируем проверку конфигураций через CLI-инструмент, логика выбора навыка может выглядеть так:

bash
# Пример логики выбора навыка (псевдокод)
if [[ "$config_file" == *.conf ]]; then
  # Вызываем специализированный навык проверки синтаксиса
  ai-agent execute --skill nginx-syntax-check --file "$config_file"
fi

if [[ "$task_type" == "security" ]]; then
  # Подключаем модуль аудита безопасности
  ai-agent execute --skill security-audit --file "$config_file"
fi

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

Обзор репозитория mattpocock/skills

Обзор репозитория mattpocock/skills

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

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

Структура директории .agents

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

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

text
.agents/
├── skills/           # Атомарные инструкции и наборы правил
│   ├── coding/       # Навыки написания и рефакторинга кода
│   ├── testing/      # Инструкции по написанию тестов
│   └── debugging/    # Методологии поиска ошибок
├── tools/            # Описания внешних инструментов (CLI, API)
└── prompts/          # Шаблоны высокоуровневых системных промптов

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

Типы предоставляемых навыков

Мэтт классифицирует навыки по их функциональному назначению. В контексте инженерных задач их можно разделить на три основные категории.

Во-первых, это процедурные навыки. Они описывают конкретный алгоритм действий. Например, как именно агент должен анализировать логи или как проводить проверку синтаксиса. Это не просто «будь внимательным», а четкая последовательность шагов: «1. Прочитай лог, 2. Найди stack trace, 3. Сопоставь с кодом».

Во-вторых, это контекстные правила. Это набор ограничений и стандартов, которые агент должен соблюдать всегда. Если мы настраиваем агента для работы в проекте на TypeScript, в его навыки будет включен модуль, запрещающий использование типа any.

В-третьих, это инструментальные навыки. Они связывают логику агента с реальным миром через CLI-утилиты. В репозитории это реализовано через описание того, как агент должен вызывать команды. Пример того, как может выглядеть описание навыка для работы с файловой системой в формате, близком к используемому в проекте:

json
{
  "skill_name": "file_analysis",
  "description": "Анализ структуры проекта для поиска зависимостей",
  "steps": [
    "Выполни команду `ls -R` для построения дерева файлов",
    "Найди файлы конфигурации (package.json, go.mod, requirements.txt)",
    "Прочитай содержимое найденных файлов для определения версий библиотек"
  ],
  "constraints": [
    "Не изменяй файлы без явного подтверждения",
    "Используй только существующие пути"
  ]
}

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

Применение навыков в инженерной практике

Применение навыков в инженерной практике

Когда мы переходим от простых чатов с LLM к полноценным AI-агентам, которые должны выполнять инженерные задачи — например, писать Terraform-манифесты или настраивать CI/CD пайплайны — на первый план выходит предсказуемость. Если агент получает слишком размытую инструкцию, он начинает «галлюцинировать» или предлагать решения, которые в нашей инфраструктуре просто не заведутся.

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

Повышение предсказуемости ответов

В инженерной среде ошибка в конфигурации может привести к простою сервиса. Чтобы минимизировать риски, навыки должны ограничивать область поиска модели. Если мы обучаем агента работать с Docker Compose, навык должен содержать не только общие правила, но и жесткие ограничения, специфичные для вашей среды.

С практической точки зрения, это работает через атомарность. Один навык — одна узкая задача. Например, вместо огромного системного промпта «Ты опытный DevOps-инженер», лучше использовать набор микро-инструкций.

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

yaml
# Пример структуры навыка для работы с systemd
skill:
  name: systemd-unit-generator
  description: Создание файлов .service для пользовательских приложений
  constraints:
    - "Всегда использовать Restart=on-failure"
    - "Запрещено использовать User=root; всегда указывать конкретного пользователя"
    - "Обязательно наличие секции [Install] с WantedBy=multi-user.target"
  validation_rules:
    - "Проверить наличие директивы ExecStart"
    - "Убедиться, что пути к бинарным файлам являются абсолютными"

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

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

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

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

Сначала убедитесь, что у вас установлен инструмент для работы с LLM через терминал (например, llm или аналогичный):

bash
# Пример использования агента с навыком для проверки конфига Nginx
llm chat -m gpt-4o --skill nginx-config-validator "Проверь этот конфиг на соответствие нашим стандартам безопасности: $(cat /etc/nginx/sites-available/default)"

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

  1. Определение контекста: Агент получает задачу и выбирает нужный навык из библиотеки.
  2. Генерация: Модель создает решение, опираясь на жесткие правила навыка.
  3. Валидация: Сгенерированный результат проверяется не только моделью, но и стандартными инженерными инструментами (например, nginx -t или terraform validate).

Если мы рассматриваем использование навыков в рамках домашней лаборатории или небольшого продакшена, этот подход позволяет делегировать рутину, сохраняя контроль. Вы не просто просите «сделай мне бэкап», вы даете агенту навык zfs-snapshot-manager, который знает, какие датасеты на вашем TrueNAS нужно защищать и куда отправлять снапшоты. Это превращает AI из «собеседника» в полноценный элемент инфраструктуры.

Как адаптировать эти подходы под свои задачи

Как адаптировать эти подходы под свои задачи

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

Создание собственных модульных инструкций

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

Если вы настраиваете агента для помощи в управлении домашней лабораторией, не стоит смешивать в одном файле правила написания Python-скриптов и специфику настройки ZFS. Лучше создать структуру, где инструкции подгружаются в зависимости от текущей задачи.

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

text
/agent-skills
├── core/
│   └── identity.md       # Кто агент, его тон, общие ограничения
├── domain/
│   ├── docker.md         # Правила работы с Docker Compose
│   └── networking.md     # Специфика настройки Nginx и маршрутизации
└── tools/
    └── shell.md          # Правила формирования команд для терминала

При сборке контекста для агента (например, через API или в интерфейсе системы управления агентами) вы собираете нужный «стек» инструкций. Если задача — развернуть сервис, вы подаёте core/identity.md + domain/docker.md + tools/shell.md. Это минимизирует шум и удерживает внимание модели на главном.

Внутри каждого модуля используйте строгую структуру. Вместо расплывчатых описаний применяйте формат «Контекст — Правило — Пример».

Пример содержимого domain/docker.md:

markdown
## Docker Compose Best Practices

### Контекст
Вы помогаете пользователю описывать инфраструктуру в Docker Compose.

### Правила
1. Всегда используй версии образов с конкретными тегами (например, `postgres:15-alpine`), избегай `latest`.
2. Сети (networks) должны быть явно определены для каждого сервиса.
3. Все чувствительные данные должны передаваться через переменные окружения, а не прописываться в `yaml`.

### Пример
Правильно:
services:
  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}

Тестирование и отладка поведения агента

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

Я рекомендую использовать метод «золотых ответов» (Golden Answers). Подготовьте набор из 5–10 пар «задача — идеальный ответ». Это поможет вам понять, когда изменения в одной инструкции ломают логику в другой.

Для автоматизации этого процесса можно использовать простой скрипт на Python, который отправляет запросы к API модели и сравнивает полученный результат с эталоном (используя семантическую близость или просто проверяя наличие ключевых технических параметров).

Пример сценария для проверки агента:

  1. Ввод: «Напиши сервис для Redis в Docker Compose».
  2. Ожидаемый результат (чек-лист):
    • Наличие тега версии (не latest).
    • Использование restart: unless-stopped.
    • Отсутствие пароля в открытом виде.

Если агент выдал image: redis:latest, значит, модуль domain/docker.md работает некорректно или его вес в контексте слишком мал.

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

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

Как внедрить систему навыков в уже существующий проект

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

Можно ли использовать навыки для разных моделей одновременно

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

Не станет ли слишком много мелких навыков проблемой для управления

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

Как проверить, что новый навык действительно работает эффективно

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

Поделиться:TelegramX / TwitterVK