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

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

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

Когда мы говорим об использовании AI-агентов в инженерных задачах, возникает соблазн дать модели одну огромную инструкцию: «Ты — опытный DevOps-инженер, настрой мне CI/CD и следи за мониторингом». С практической точки зрения это тупиковый путь. Чем больше контекста мы пытаемся впихнуть в один промпт, тем ниже предсказуемость результата. Модель начинает путаться в приоритетах, игнорировать мелкие, но критичные детали и, в конечном счёте, выдаёт галлюцинации вместо рабочего кода.

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

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

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

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

text
Ты — эксперт по Docker. Пиши конфиги, которые работают быстро, 
безопасно и соответствуют лучшим практикам. 
Используй только актуальные версии образов.

Здесь заложено слишком много абстракций. Что такое «быстро»? Что такое «безопасно»? Для одного инженера это использование multi-stage builds, для другого — минимизация слоев, для третьего — запуск от non-root пользователя. Из-за размытости формулировок агент будет каждый раз выдавать разный результат, что недопустимо, если вы строите автоматизированный пайплайн.

Когда инструкции размыты, вы теряете контроль над состоянием системы. Вы не можете гарантировать, что агент не добавит лишний privileged: true в docker-compose.yml просто потому, что в его «широком» понимании безопасности это допустимо для отладки.

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

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

Если мы возьмём тот же Docker, то вместо одного промпта мы разделим его на компоненты:

Skill: Dockerfile Optimization (фокус только на количестве слоев и размере образа).
Skill: Security Hardening (фокус на user, capabilities и read-only файловых системах).
Skill: Compose Syntax (фокус на корректности YAML и связях между сервисами).

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

Модульность позволяет также легко тестировать каждый навык в отдельности. Вы можете подать на вход навыку Security Hardening конкретный конфиг и проверить, заметит ли он отсутствие ограничения прав. Это превращает работу с AI из лотереи в инженерный процесс с понятными входными и выходными данными.

Архитектура репозитория mattpocock/skills

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

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

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

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

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

text
.agents/
├── core/                # Базовые инструкции (системный промпт)
├── skills/              # Набор специализированных навыков
│   ├── coding/          # Навыки написания и ревью кода
│   ├── research/        # Навыки поиска и анализа информации
│   └── devops/          # Навыки работы с инфраструктурой
└── personas/            # Описания ролей (например, Senior SRE)

Если мы посмотрим на то, как это работает в инженерных задачах, становится понятно: когда агент должен проанализировать логи Nginx, мы не подгружаем ему навыки написания стихов или планирования путешествий. Мы подключаем core и skills/devops. Это обеспечивает предсказуемость: чем меньше лишних инструкций в контексте, тем точнее модель следует заданному алгоритму.

Форматы описания компетенций

Самое важное в этом репозитории — это то, как именно описан каждый навык. Автор уходит от свободного повествования в пользу структурированных форматов. Это позволяет превратить абстрактное «умение кодить» в четкий набор правил и ограничений.

Каждая компетенция (skill) обычно описывается через комбинацию нескольких элементов:

Role/Identity: Кто этот агент в рамках данной задачи.
Capabilities: Что именно он может делать.
Constraints: Чего ему делать категорически нельзя (самый важный пункт для стабильной работы).
Workflow: Пошаговый алгоритм выполнения задачи.

Пример того, как может выглядеть описание навыка для работы с конфигурациями (в упрощенном виде), если бы мы описывали его для агента:

yaml
skill:
  name: configuration_auditor
  description: Проверка конфигурационных файлов на соответствие стандартам безопасности.
  capabilities:
    - анализ синтаксиса YAML/JSON
    - поиск открытых портов и небезопасных протоколов
    - проверка прав доступа к файлам
  constraints:
    - никогда не предлагать изменения, которые требуют перезагрузки системы без предупреждения
    - не использовать устаревшие параметры (deprecated)
    - не изменять существующие комментарии в конфигах
  workflow:
    - 1. Прочитать файл.
    - 2. Сравнить параметры с эталонным списком.
    - 3. Сформировать отчет об отклонениях.

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

Практическое применение навыков в разработке

Автоматизация рутинных инженерных задач

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

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

Во-первых, это касается работы с конфигурациями. Вместо того чтобы просить агента «исправить конфиг Nginx», мы даём ему навык validate_nginx_config. В этом случае агент сначала выполняет проверку синтаксиса, анализирует ошибки и только потом предлагает правки.

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

yaml
skill:
  name: validate_nginx_config
  description: Проверяет синтаксис конфигурации Nginx и наличие файлов
  input:
    config_path: string # Путь к файлу конфигурации
  steps:
    - action: run_command
      command: "nginx -t -c {{config_path}}"
    - action: parse_output
      condition: "if output contains 'syntax is ok'"
  output:
    status: boolean
    error_log: string | null

Во-вторых, это автоматизация мониторинга и первичного реагирования. Если у вас настроен Prometheus и Alertmanager, агент с навыком analyze_prometheus_metric может не просто сообщить об алерте, а выполнить запрос к API, чтобы понять динамику.

Например, при получении алерта о росте нагрузки на CPU, агент может выполнить команду:

bash
# Запрос к API Prometheus для получения среднего значения CPU за последние 15 минут
curl -G 'http://prometheus:9090/api/v1/query' \
    --data-urlencode 'query=avg(rate(node_cpu_seconds_total{mode="idle"}[15m]))'

Такой подход превращает агента из чат-бота в полноценного участника процесса эксплуатации, который действует в рамках заданных границ.

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

Интеграция навыков в существующий CI/CD или workflow — это вопрос предсказуемости. Если агент работает в изоляции, он бесполезен. Если он встроен в цепочку команд, он становится инструментом.

С точки зрения системного инженера, наиболее эффективный способ внедрения — это использование агентов в качестве «умного прослойки» между Git и сервером. Рассмотрим сценарий, когда агент проверяет Pull Request с изменениями в Ansible-плейбуках.

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

Разработчик отправляет изменения в репозиторий.
CI-пайплайн запускает агента, которому передаются навыки lint_ansible и check_dry_run.
Агент не просто запускает ansible-lint, а интерпретирует результат. Если ошибка касается безопасности (например, использование shell вместо специализированных модулей), агент пишет подробный комментарий к PR.

Пример конфигурации задачи для агента в рамках GitHub Actions:

yaml
jobs:
  ai_review:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: AI Skill Execution
        run: |
          # Вызов агента с указанием конкретного набора навыков
          agent-cli run --skills "lint_ansible,security_audit" \
            --context "./playbooks/web_server.yml" \
            --output "review_report.md"

Если мы посмотрим на структуру рабочего процесса, то увидим, что навыки позволяют избежать «галлюцинаций» модели. Когда агент ограничен набором инструментов (tools) и инструкций (skills), его область поиска сужается до конкретных технических параметров.

Для обеспечения стабильности в домашней лаборатории или в продакшн-среде, интеграция должна следовать правилу: агент никогда не применяет изменения напрямую без подтверждения человеком (Human-in-the-loop), если только это не предусмотрено специфическим навыком auto_remediate_low_risk.

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

Оценка эффективности и риски

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

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

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

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

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

Агент получает задачу и выбирает навык.
Агент генерирует артефакт (конфиг, скрипт, команду).
Система запускает проверку синтаксиса.

Для проверки конфигураций можно использовать стандартные утилиты. Например, если агент настраивает Nginx, добавьте шаг проверки через nginx -t:

bash
# Пример автоматизированной проверки сгенерированного конфига
# Мы передаем временный файл, чтобы не повредить рабочий сервер
nginx -t -c /tmp/agent_generated_nginx.conf

Во-вторых, стоит использовать метод «LLM-as-a-judge». Вы берете более мощную модель (например, GPT-4o или Claude 3.5 Sonnet) и просите её оценить выполнение задачи более слабой моделью, которая использует навыки из репозитория mattpocock/skills.

Пример промпта для оценки (eval):

text
Сравни исходную задачу и выполненный результат. 
Оцени по шкале от 1 до 5:
1. Соответствие синтаксису (отсутствие ошибок).
2. Безопасность (не открыты ли лишние порты, нет ли hardcoded паролей).
3. Полнота (выполнена ли задача целиком).

Ограничения текущего подхода

Несмотря на системный подход, у использования библиотек навыков есть свои «подводные камни».

Первое — это риск деградации контекста. Чем больше навыков вы описываете, тем больше токенов тратится на их описание. Если вы попытаетесь «скормить» агенту сразу все навыки из репозитория, вы столкнётесь с тем, что модель начнет путать инструкции или игнорировать часть из них. Это классическая проблема перегрузки контекстного окна.

Решение здесь одно: динамическая подгрузка. Не давайте агенту знать о всех навыках сразу. Используйте векторный поиск (RAG), чтобы находить только те инструкции, которые релевантны текущей задаче.

Второе — это проблема «скрытых зависимостей». В репозитории навыки описаны как изолированные блоки, но в реальности они часто зависят друг от друга. Например, навык «Настройка базы данных PostgreSQL» может предполагать, что у агента уже есть навык «Создание Docker-сети». Если цепочка разорвется, агент выдаст ошибку, которую будет сложно отладить, так как он будет уверен, что выполнил инструкцию по навыку верно.

Если мы посмотрим на структуру типичного навыка, мы увидим, что он описывает что делать, но не всегда учитывает состояние системы. Для минимизации рисков каждый навык должен сопровождаться блоком pre-conditions (предварительные условия) и post-conditions (проверка результата).

Пример правильной структуры описания навыка в JSON-подобном виде:

json
{
  "skill_name": "setup_systemd_service",
  "pre_conditions": [
    "file_exists(/etc/systemd/system/)",
    "user_has_sudo_access"
  ],
  "action": "create_service_unit_file",
  "post_conditions": [
    "service_status_active",
    "journald_logs_contain_success"
  ]
}

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

Заключение

Итоговые рекомендации по внедрению

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

Когда мы работаем с AI-агентами в инженерных задачах, основная проблема — это «галлюцинации» или отклонение от заданного алгоритма. Использование навыков (skills) позволяет минимизировать этот шум. Вместо того чтобы пытаться впихнуть все требования в один гигантский системный промпт, мы разделяем компетенции. Это похоже на то, как я настраиваю сервисы в Docker Compose: один контейнер отвечает за базу данных, другой — за веб-сервер, и они взаимодействуют через четко определённые интерфейсы.

Для достижения предсказуемости придерживайтесь трёх правил:

Атомарность. Один навык — одна конкретная задача. Не пытайтесь смешать инструкции по написанию кода на Python и правила оформления документации в одном файле.
Версионность. Если вы правите инструкции, фиксируйте это. Если агент начал ошибаться после обновления навыка, вы должны иметь возможность быстро откатиться к предыдущему состоянию.
Тестирование. Любой новый навык нужно проверять на граничных условиях.

Как оценить эффективность подхода

Чтобы понять, помогает ли вам структурирование навыков, нужно смотреть на метрики качества выполнения задач. Если вы используете агентов для автоматизации инфраструктурных задач (например, написания Ansible-плейбуков), отслеживайте процент ошибок в синтаксисе и отклонений от ваших стандартов.

Если вы решили интегрировать эти навыки в свой рабочий процесс через CLI или API, структура запроса может выглядеть примерно так:

yaml
# Пример логической структуры запроса к агенту с использованием навыков
agent_config:
  name: infra-engineer-bot
  skills:
    - skills/linux/systemd-unit-creation.md
    - skills/docker/compose-best-practices.md
    - skills/security/nginx-hardening.md
  context:
    target_os: Debian 12
    environment: production

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

Когда этот метод не сработает

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

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

FAQ

Можно ли использовать эти навыки в сторонних LLM?

Да, формат репозитория skills не привязан к конкретному API или провайдеру. Суть метода заключается в структурировании знаний и инструкций в виде атомарных, логически завершенных блоков. Если вы используете OpenAI, Anthropic или модели через Ollama, вы можете просто передавать содержимое нужного навыка в системный промпт или в контекст текущей сессии.

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

Нужно ли переписывать свои промпты под этот формат?

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

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

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

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

Например, если вы хотите научить агента проверять логи systemd, ваш файл check_logs.md может выглядеть примерно так:

markdown
# Skill: Systemd Log Analyzer

## Description
Analyzes systemd journal logs to identify errors in specific services.

## Instructions
1. Use `journalctl -u <service_name> -n 50` to fetch recent logs.
2. Look for keywords: "Error", "Failed", "Critical", or "Panic".
3. If an error is found, extract the timestamp and the error message.
4. Provide a summary of the last 5 critical events.

## Constraints
- Do not suggest restarting the service unless explicitly asked.
- Only analyze logs from the last 24 hours.

Подходит ли этот подход для локальных моделей?

Для локальных моделей, работающих на домашнем сервере, этот подход даже более актуален, чем для облачных решений. У моделей с меньшим количеством параметров (например, Llama 3 8B или Mistral) ограниченное «окно внимания» и меньшая способность удерживать в памяти сложные многоуровневые инструкции.

Разбиение задач на мелкие, чёткие навыки помогает локальным моделям:

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


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

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

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

### Как правильно определить границы одного навыка?

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

### Можно ли использовать навыки из репозитория skills в своих проектах?

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

### Поможет ли использование навыков решить проблему галлюцинаций модели?

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