Средний

Набор навыков для работы с AI-агентами

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

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

Набор навыков для работы с AI-агентами

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

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

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

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

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

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

Один из наиболее здравых способов организовать работу агента — это использование специализированной директории, например .agents. Это напоминает то, как мы организуем конфигурационные файлы в Linux или модули в Python: вместо одного файла config.conf на 10 000 строк у нас есть структурированная иерархия.

В репозитории mattpocock/skills предлагается концепция, где каждый навык представлен отдельным файлом. Это позволяет агенту работать по принципу «just-in-time»: он не держит в памяти всё сразу, а подгружает нужный инструмент только при возникновении конкретной задачи.

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

text
my-project/
├── .agents/
│   ├── code-reviewer.md      # Навык анализа качества кода
│   ├── sql-optimizer.md      # Навык оптимизации запросов
│   └── documentation-gen.md  # Навык написания документации
├── src/
├── docker-compose.yml
└── README.md

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

Отличие навыка от обычного промпта

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

С точки зрения системного инженера, разницу можно свести к трем параметрам:

  1. Гранулярность. Промпт описывает личность (Persona), навык описывает действие (Action).
  2. Контекстная изоляция. Навык содержит в себе не только инструкцию, но и правила обработки ошибок, специфичные для этой задачи.
  3. Структура данных. Навык часто включает в себя описание того, в каком формате агент должен вернуть результат.

Рассмотрим пример. Обычный промпт для написания документации может быть коротким и неэффективным. Навык же, оформленный в виде файла .agents/doc-generator.md, будет выглядеть примерно так:

markdown
# Skill: Documentation Generator

## Objective
Generate technical documentation for Python functions following Google Style Guide.

## Input Format
- Function source code
- Type hints (if available)

## Process
1. Analyze function arguments and return types.
2. Identify side effects (e.g., database writes, file I/O).
3. Compose docstring.

## Output Requirements
- Use triple double quotes `"""`.
- Include 'Args', 'Returns', and 'Raises' sections.
- Output ONLY the code block with the updated function.

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

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

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

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

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

Структура и классификация навыков

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

  1. Базовые когнитивные навыки. Это инструкции по логике, планированию и самопроверке. Они помогают агенту не просто выдать ответ, а сначала составить план действий.
  2. Специализированные инженерные навыки. Инструкции для работы с кодом, отладки и анализа логов.
  3. Интерфейсные навыки. Правила взаимодействия с внешними инструментами (API, терминал, браузер).

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

Примеры прикладных инструкций

Чтобы понять, как это работает «в железе», разберём типичный пример. Допустим, вы строите агента, который должен помогать в управлении инфраструктурой через терминал. Вместо того чтобы просить его «помоги с Docker», вы внедряете в системный промпт (system prompt) конкретный навык.

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

yaml
# Пример интеграции навыка в конфигурацию агента
agent_skills:
  - name: docker_troubleshooter
    description: "Анализ причин остановки контейнеров"
    instruction: |
      При получении ошибки выполнения команды в Docker:
      1. Выполни `docker ps -a` для поиска статуса контейнера.
      2. Используй `docker logs --tail 50 [container_id]` для сбора последних записей.
      3. Проверь наличие ошибок в системном журнале через `journalctl -u docker`.
      4. Сформируй отчет: текущее состояние, найденная причина, предлагаемое исправление.
    constraints:
      - "Никогда не выполняй `docker rm -f` без явного подтверждения пользователя."
      - "Не пытайся перезапускать контейнер более двух раз подряд."

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

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

Практическое применение в инженерной работе

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

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

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

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

yaml
agent_skills:
  - name: docker_troubleshooter
    description: "Анализ логов и состояния контейнеров Docker"
    instructions: |
      При возникновении ошибки в контейнере:
      1. Выполни 'docker ps' для проверки статуса.
      2. Выполни 'docker logs --tail 50 <container_id>' для сбора контекста.
      3. Проверь использование ресурсов через 'docker stats'.
      4. Сформулируй гипотезу на основе полученных данных.
    tools:
      - docker_cli_access

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

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

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

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

Чтобы добиться стабильности, я рекомендую использовать технику «Few-shot prompting» внутри самих навыков. Это когда в инструкции к навыку вы приводите пример: «Входные данные $\to$ Логика $\to$ Ожидаемый вывод».

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

markdown
# Skill: Nginx Config Validator

## Context
Ты — эксперт по конфигурации Nginx. Твоя задача — проверять синтаксис и логическую целостность файлов.

## Procedure
1. Получи содержимое файла конфигурации.
2. Проверь наличие всех закрывающих точек с запятой (;) и фигурных скобок ({}).
3. Убедись, что директивы `listen` и `server_name` указаны корректно.
4. Если найдены ошибки, выведи их в формате: [Line X]: [Error Type] - [Suggestion].

## Example
Input: 
server {
    listen 80
    server_name example.com;
}

Output:
[Line 2]: Syntax Error - Missing semicolon after 'listen 80'.
Suggestion: Add ';' at the end of the line.

Если мы посмотрим на этот подход, то увидим, что мы не просто просим проверить файл, а задаём жесткий формат ответа. Это критически важно, если вы планируете парсить ответы агента программно (например, чтобы автоматически отправлять отчеты в Slack или Jira).

Предсказуемость — это не когда агент всегда прав, а когда вы точно знаете, в каком формате он выдаст ошибку и какие шаги предпримет для её поиска. Только так AI-агент превращается из игрушки в полезный инструмент в вашей домашней лаборатории или производственной среде.

Как внедрить эти инструкции в свои проекты

Как внедрить эти инструкции в свои проекты

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

Подготовка контекста для агента

Чтобы агент эффективно использовал конкретный навык, ему нужно не только описание самого действия, но и понимание границ его применимости. Я рекомендую использовать подход, при котором каждый навык подаётся как отдельный блок в контексте, снабжённый метаданными.

Если вы строите агента на базе LangChain или используете кастомные решения через API, не пытайтесь запихнуть все навыки в один запрос. Лучше создайте систему динамической подгрузки. Во-первых, определите «инвентарь» доступных навыков. Во-вторых, подавайте только те, которые релевантны текущей задаче.

Пример структуры системного промпта, где навык выделен как отдельный модуль:

yaml
# Пример логической структуры контекста для агента
agent_context:
  role: "Senior DevOps Engineer"
  available_skills:
    - skill_id: "log_analysis_expert"
      description: "Анализ системных логов на предмет ошибок в stack trace"
      instruction: |
        При получении лога:
        1. Идентифицируй уровень ошибки (ERROR, CRITICAL).
        2. Найди связанный с ошибкой компонент системы.
        3. Сформируй гипотезу о причине, основываясь на контексте.
      constraints: "Не предлагай перезагрузку сервиса, пока не проанализирован stack trace"
    
    - skill_id: "docker_config_validator"
      description: "Проверка Docker Compose файлов на соответствие best practices"
      instruction: |
        Проверь файл на наличие:
        - Ограничений ресурсов (memory, cpu).
        - Использования конкретных версий образов (не latest).
        - Настроенных healthcheck.

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

Тестирование и отладка навыков

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

Для отладки я использую метод «золотого набора» (Golden Dataset). Вы создаёте набор из 5–10 типичных сценариев (входные данные + ожидаемый результат) и прогоняете их через агента после каждого изменения в инструкциях.

Процесс отладки стоит разделить на три этапа:

  1. Проверка на следование ограничениям (Constraint Testing). Если в навыке указано «не использовать команду rm -rf /», вы должны подать запрос, провоцирующий агента на это действие. Если он выполнил команду — навык не работает.
  2. Проверка на точность (Precision Testing). Если навык предназначен для парсинга JSON, подайте на вход «битый» JSON. Агент должен корректно обработать ошибку, а не пытаться угадать структуру.
  3. Проверка на избыточность (Verbosity Testing). Часто агенты начинают писать слишком много лишнего текста. Если ваша цель — получить только команду, а агент выдаёт три абзаца рассуждений, нужно ужесточить секцию constraints в инструкции.

Для автоматизации этого процесса можно использовать простой скрипт на Python, который сравнивает ответ агента с эталоном (используя LLM-as-a-judge для оценки семантической близости):

python
import openai

def evaluate_skill(agent_response, expected_behavior):
    """
    Сравнивает ответ агента с ожидаемым поведением.
    Использует отдельную модель для оценки качества.
    """
    eval_prompt = f"""
    Оцени, насколько ответ агента соответствует инструкции.
    Инструкция: {expected_behavior}
    Ответ агента: {agent_response}
    
    Ответь только одним словом: PASS или FAIL.
    """
    
    # Здесь вызывается API для оценки
    response = openai.ChatCompletion.create(
        model="gpt-4",
        messages=[{"role": "user", "content": eval_prompt}]
    )
    return response.choices[0].message.content

# Пример использования
test_input = "Проверь мой docker-compose.yml, там нет лимитов."
agent_output = "В вашем файле отсутствуют секции deploy.resources.limits..." 
expected = "Агент должен указать на отсутствие лимитов и привести пример конфигурации."

result = evaluate_skill(agent_output, expected)
print(f"Результат теста: {result}")

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

Заключение

Практические выводы

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

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

  1. Предсказуемость. Вы точно знаете, какой набор инструментов и логических шагов применит агент, если вы подключите навык code-reviewer.
  2. Масштабируемость. Вы можете обновлять описание навыка в одном месте, и это изменение автоматически подтянется во все ваши рабочие процессы.

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

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

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

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

yaml
agent_profile:
  name: "infra-assistant"
  capabilities:
    - skill: "linux-troubleshooter"
      version: "1.2.0"
      context: "debian-based-systems"
    - skill: "docker-compose-expert"
      version: "2.0.1"
      strict_mode: true
  memory_limit: 8192

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

Когда использование навыков может не сработать

Важно понимать ограничения. Готовые инструкции из репозитория Matt Pocock отлично работают для типовых задач, но они могут буксовать в следующих случаях:

  • Слишком специфичный стек. Если ваш домашний сервер работает на нестандартной сборке ядра или самописном софте, стандартный навык systemd-expert может предлагать решения, которые не применимы в вашем случае.
  • Конфликт инструкций. Если вы даёте агенту два взаимоисключающих навыка (например, один требует максимальной безопасности, а другой — максимальной скорости развёртывания), предсказуемость результата падает до нуля.
  • Перегрузка контекста. Каждый навык занимает место в «памяти» (context window) модели. Если навыков слишком много, агент начнет забывать начало вашего диалога или важные детали текущей задачи.

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

FAQ

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

С практической точки зрения работа с репозиторием mattpocock/skills строится по принципу внедрения готовых инструкций в системный промпт (system prompt) вашего агента или в контекст текущей сессии. Если вы используете фреймворки вроде LangChain или AutoGPT, эти навыки можно подавать как специализированные инструменты.

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

bash
# Пример логики: передача навыка через переменную окружения или файл
export AGENT_SKILL_CONTEXT=$(cat skills/code-review.md)
python agent_run.py --system-prompt "$AGENT_SKILL_CONTEXT"

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

Нужно ли дорабатывать готовые инструкции?

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

Я рекомендую дорабатывать инструкции в трёх направлениях:

  1. Специфика стека. Если навык предназначен для общего написания кода, добавьте в него требования к использованию конкретных библиотек, например, FastAPI вместо абстрактного Python.
  2. Формат вывода. Если ваш агент является частью CI/CD конвейера, пропишите в навыке требование отдавать ответ строго в формате JSON.
  3. Ограничения (Guardrails). Чётко укажите, чего агент делать не должен.

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

markdown
## Constraints
- Не предлагать использование root-прав для запуска сервисов.
- Всегда проверять наличие синтаксических ошибок в YAML-конфигах перед выводом.
- Использовать только проверенные образы из официальных репозиториев.

Подходят ли эти навыки для всех LLM?

Навыки из репозитория универсальны по своей сути, так как они опираются на семантику языка, а не на специфические API. Однако качество их исполнения сильно зависит от «интеллекта» модели.

  • Мощные модели (GPT-4o, Claude 3.5 Sonnet): Хорошо справляются со сложными, многоступенчатыми навыками, где требуется глубокое рассуждение и соблюдение строгих форматов.
  • Легкие модели (Llama 3 8B, Mistral): Могут терять нить инструкции, если навык слишком объёмный. Для таких моделей лучше разбивать один большой навык на несколько маленьких и узкоспециализированных.

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

В чем преимущество использования структурированных навыков?

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

Это даёт три важных результата:

  1. Воспроизводимость. Вы точно знаете, что при подключении навыка sql-optimizer агент будет вести себя одинаково в разных сессиях.
  2. Экономия токенов. Вместо длинных и неэффективных промптов вы используете сжатые, проверенные инструкции.
  3. Упрощение отладки. Если агент начал ошибаться, вам не нужно переписывать весь системный промпт — достаточно заменить или подправить один конкретный навык.

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

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

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

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

Чем использование файлов навыков лучше обычного промпт-инжиниринга?

Обычный промпт-инжиниринг часто превращается в попытку создать «швейцарский нож» из одного куска стали, что неизбежно ведёт к потере точности. Разделение на файлы в директории .agents позволяет работать с агентом по принципу разделения ответственности, как в микросервисной архитектуре. Это упрощает тестирование: вы можете проверить работу конкретного навыка sql-optimizer.md отдельно от остальных, не затрагивая общую логику.

Как агент понимает, какой именно файл из директории .agents нужно использовать?

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

Можно ли комбинировать несколько навыков для решения одной сложной задачи?

Да, это один из главных сценариев использования такой структуры. Если задача комплексная, агент может последовательно или параллельно задействовать несколько модулей, например, сначала использовать code-reviewer.md для анализа, а затем documentation-gen.md для описания исправлений. Главное здесь — следить за тем, чтобы навыки были достаточно атомарными и не дублировали функции друг друга.

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