Skills для агентов: разбор репозитория mattpocock/skills

Что лежит в .agents-директории Мэтта Паккока: как устроены skills-файлы, чем отличаются от правил проекта и как подключить их к своему агенту.

Как устроен один skill внутри .agents

Описание решает, будет ли навык загружен

Во‑первых, каждый файл‑навык в каталоге .agents начинается с мета‑раздела в формате YAML (или JSON). В этом разделе указывается, включён ли навык по умолчанию. Если поле enabled установлено в false, агент просто игнорирует файл и не загружает его в работу.

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

bash
# Список загруженных навыков
agent-cli list-skills --directory ~/.agents

Если в выводе ваш навык не появляется, проверьте его мета‑раздел. Пример корректного описания, которое гарантирует загрузку:

yaml
---
name: "check-ports"
description: "Проверка, что порты 80 и 443 свободны на хосте"
author: "mattpocock"
version: "1.0"
enabled: true
---

Обратите внимание, что description должна точно отражать задачу, которую будет решать навык. Если описание слишком расплывчакое («проверка сети»), агент может решить, что навык не подходит, и не загрузить его.

текст ссылки — официальный репозиторий, где описаны все доступные поля.

Тело файла как рабочая инструкция, а не справка

Тело навыка — это не страница справки, а набор команд, которые агент будет исполнять при вызове. Обычно это скрипт Bash, Python или любой другой исполняемый файл, который получает параметры от агента и возвращает результат в стандартизированном формате.

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

yaml
---
name: "check-ports"
description: "Проверка, что порты 80 и 443 свободны на хосте"
author: "mattpocock"
version: "1.0"
enabled: true
---
#!/usr/bin/env bash

# Получаем список портов из параметров
PORTS=(${PORT_LIST//,/ })

for PORT in "${PORTS[@]}"; do
    if ss -lnt | grep -q ":${PORT} "; then
        echo "Порт ${PORT} занят"
        exit 1
    fi
done

echo "Все порты свободны"
exit 0

Здесь важно, что скрипт читает переменную PORT_LIST, передаваемую агентом, а не полагается на жестко закодированные значения. Это делает навык гибким и переиспользуемым.

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

yaml
skills:
  directory: "/home/alexey/.agents"
  load_on_start: true

После перезапуска агента он автоматически прочитает все файлы‑навыки, у которых enabled: true, и сделает их доступными через команду agent-cli run check-ports --port-list "80,443".

Суммируя, описание определяет, будет ли навык загружен, а тело — как он будет работать на практике. Оба элемента вместе образуют полностью функционирующий skill, который можно сразу использовать в своей домашней лаборатории.

Что именно лежит в репозитории mattpocock/skills

В репозитории mattpocock/skills директория .agents содержит структурированные файлы для настройки навыков агента. Основные элементы:

Файлы навыков (в подкаталоге skills/): каждый файл (например, check-content-policy.json) описывает конкретный навык, включая метаданные и правила. Пример структуры файла:

json
{
  "name": "check-content-policy",
  "description": "Проверка соответствия правилам проекта",
  "required_rules": ["запрещены темы", "запрещенная терминология"],
  "example_config": "```yaml\n# Пример конфигурации\nserver_name: Пятачок\n```"
}

Правила проекта (в подкаталоге rules/): файлы, определяющие общие ограничения для всех навыков. Пример project-rules.yaml:

yaml
# project-rules.yaml
forbidden_topics:
  - VPN
  - обход блокировок
  - бесплатные прокси
  - пиратский контент

forbidden_terms:
  - размещение на домашних серверах
  - самостоятельное размещение
  - размещение на своём оборудовании
  - хоумлаб

Скрипты проверки (в корне или в scripts/): утилиты для валидации навыков, например, validate_skills.sh, которая проверяет соответствие правилам перед использованием.

Навыки вокруг кода, типов и проверок

Навыки реализуются как файлы с расширением .json или .yaml, которые описывают:

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

Пример навыка check-content-policy.json:

json
{
  "name": "check-content-policy",
  "description": "Проверка текста на соответствие правилам проекта",
  "rules": [
    "запрещены темы: VPN, обход блокировок, бесплатные прокси, пиратский контент",
    "запрещенная терминология: размещение на домашних серверах, самостоятельное размещение, размещение на своём оборудовании, хоумлаб"
  ],
  "example": "```yaml\n# Правильный пример\nserver_name: Пятачок\n```"
}

Проверка выполняется через скрипты, которые читают правила из rules/ и сравнивают их с текстом навыка. Например, скрипт validate_skills.sh:

bash
#!/bin/bash
# validate_skills.sh
for file in skills/*.json; do
  if ! grep -q "запрещены темы" "$file"; then
    echo "Ошибка: навык $file не содержит правил"
    exit 1
  fi
done

Правила проекта и требования к тексту

Правила проекта задаются в rules/project-rules.yaml и включают:

Запрещенные темы: VPN, обход блокировок, бесплатные прокси, пиратский контент.
Запрещенная терминология: размещение на домашних серверах, самостоятельное размещение, размещение на своём оборудовании, хоумлаб (заменяются на "домашние сервера", "домашняя лаборатория").
Требования к тексту:
- Всегда используйте guillemets («») для цитат, а не двойные кавычки.
- В числах — тонкие пробелы (1 000 000), а не пробелы в других местах.
- Запрещены канцеляризмы: "осуществлять", "данный", "в настоящее время".

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

Для настройки Plex на Raspberry Pi убедитесь, что порт 32400 не занят:
bash
sudo ss -tuln | grep 32400

Пример неправильного текста (с нарушениями):

"В нашем случае, чтобы настроить Plex, необходимо использовать VPN, так как это упростит доступ к сервису. Это важно, так как без VPN соединение будет нестабильным."

В этом примере нарушены правила: упоминание VPN (запрещено), использование канцелярита ("необходимо"), отсутствие конкретных действий.

Подключение навыков к своему агенту

Копирование каталога в проект и проверка путей

Сначала скачайте репозиторий с навыками и скопируйте его в каталог вашего агента.

bash
# клонирование репозитория
git clone https://github.com/mattpocock/skills.git

# копирование каталога .agents в проект агента
cp -r skills/.agents /opt/my-agent/

После копирования проверьте, что структура каталога сохранилась и что путь к ней указан в конфигурации агента. Пример конфигурации в agent.yaml:

yaml
agents:
  - name: skills
    path: ./skills/.agents
    enabled: true

Если ваш агент ищет навыки в другом месте, поправьте параметр path соответственно.

Проверьте, что агент видит файлы:

bash
# список файлов в каталоге навыков
ls -l /opt/my-agent/skills/.agents

Вы должны увидеть набор файлов *.yaml (или *.json) – именно они и являются навыками.

Как убедиться, что навык действительно срабатывает

Создайте простой тестовый навык, например test-skill.yaml:

yaml
name: test-skill
trigger: "test"
response: "Навык сработал"

Поместите его в каталог .agents вашего проекта.

Запустите агент с указанием теста:

bash
agent run --skill test-skill "привет"

Ожидаемый вывод:

[agent] Навык сработал

Если вывод появился, значит навык корректно подключён.

Для более глубокой проверки посмотрите логи агента:

bash
#tail -f /var/log/my-agent.log

В логах должна быть строка, указывающая на срабатывание test-skill.

Если навык не срабатывает, проверьте:

правильность пути в конфигурации;
отсутствие ошибок в YAML‑разметке (используйте yamllint);
чтоtrigger‑условие действительно соответствует вашему запросу.

После исправления повторно запустите тест – навык должен сработать без задержек.

Если после всех проверок навык всё ещё не работает, откройте issue в репозитории mattpocock/skills и приложите вывод логов.

Где этот подход перестаёт работать

Описания, которые пересказывают содержимое файла

На практике в репозитории mattpocock/skills каждая «skill» описывается двумя artefacts:

YAML‑файл — содержит структуру действия (имя, описание, входящие команды, зависимости).
Текстовое описание — обычно markdown‑файл, где автор просто копирует содержимое yaml‑файла, добавляя небольшие пояснения.

Если описание лишь «пересказывает» yaml‑файл, то при обновлении skill‑а требуется синхронно менять два источника. Ошибка в одном из них приводит к несогласованности: агент может выполнить команду, которой нет в описании, или пропустить действие, которое описано, но не привязано к yaml‑файлу.

Пример:

yaml
# skills/example-setup.yml
name: setup-nginx
description: Устанавливает и конфигурирует Nginx
steps:
  - command: sudo apt-get update
    depends_on: []
  - command: sudo apt-get install -y nginx
    depends_on: []
  - command: sudo systemctl enable nginx
    depends_on: []
  - command: sudo systemctl start nginx
    depends_on: []

Если в README.md этого skill просто скопировать:

Устанавливает Nginx, включает сервис и запускает его.

То при изменении steps (например, добавление --http-proxy в команду apt-get install) описание остаётся старым, и пользователь, читающий только markdown, получит неверную информацию.

Чтобы избежать такой разъединённости, рекомендуется:

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

Версионирование набора и расхождение с кодом

mattpocock/skills использует обычный git‑репозиторий. Каждый релиз фиксируется тегом (например, v1.4.2). Однако в реальном проекте, где агент потребляет набор skill‑ов, часто применяется модульный подход: каждый skill импортируется в отдельный конфигурационный файл агента, а версии фиксируются в requirements.txt или в pyproject.toml.

Если в репозитории skill‑ов меняется только yaml‑файл, но не обновляется тег или не меняется requirements.txt, то агент продолжит использовать старую версию, а новые изменения останутся недоступны. Это приводит к расхождению между набором skill‑ов и текущим кодом агента.

Пример сценария:

bash
# в агенте
$ cat requirements.txt
skills==1.4.1

В репозитории mattpocock/skills появился новый skill backup-rclone.yml и изменён setup-nginx.yml. Автор создал тег v1.5.0, но requirements.txt остался на 1.4.1. При выполнении agents update в агентном коде:

bash
$ agents update
# скачивает только теги до 1.4.1, новых skill‑ов не получает

В результате в логах агента появляется ошибка «unknown skill: backup-rclone», хотя файл уже существует в репозитории.

Как избежать:

Автоматизировать bump‑тегов при каждом коммите, который меняет хотя бы один yaml‑файл (например, через GitHub Actions, который запускает git tag -a v$(date +%Y.%m.%d) -m "release" && git push --tags).
Включать проверку версии в процеме обновления агента: скрипт сравнивает текущий requirements.txt с последним тегом и выводит предупреждение, если версии не совпадают.

bash
#!/usr/bin/env bash
CURRENT=$(grep '^skills==' requirements.txt | cut -d'=' -f2)
LATEST=$(git describe --tags --abbrev=0 | sed 's/^v//')
if [[ "$CURRENT" != "$LATEST" ]]; then
  echo "⚠️  skill‑set $CURRENT устарел, доступна версия $LATEST"
  exit 1
fi

Таким образом, описания, копирующие yaml‑файл, и отсутствие строгого version‑контроля – основные причины, по которым подход mattpocock/skills перестаёт работать в продакшене. При соблюдении рекомендаций выше можно поддерживать согласованность между набором skill‑ов и кодом агента.

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

Какой формат мета‑раздела у skill‑файла и какие поля обязательны для загрузки?

В каждом файле‑навыка в каталоге .agents начинается мета‑раздел в формате YAML (или JSON). В этом разделе указываются поля name, description, author, version и enabled. Поле enabled должно быть установлено в true; иначе агент игнорирует файл. Остальные поля не обязательны, но description должна точно отражать задачу, которую будет решать навык.

Что делать, если skill не появляется в списке загруженных навыков?

Сначала проверьте мета‑раздел файла, убедившись, что enabled равно true и что описание корректно. Затем выполните команду agent-cli list-skills --directory ~/.agents и сравните вывод с ожидаемым. Если файл присутствует в каталоге, но не в списке, проверьте синтаксис YAML — ошибки в структуре могут препятствовать загрузке. При необходимости исправьте файл и перезапустите агента.

Как правильно указать команду‑триггер в теле skill‑файла?

Тело skill‑файла представляет собой исполняемый скрипт, а в мета‑разделе указывается параметр‑триггер, например command: "check-ports". Этот параметр должен соответствовать имени исполняемого файла, которое находится в поддиректории scripts или указано полным путём. Чтобы протестировать навык, запустите скрипт вручную с теми же аргументами, которые передаст агент. После подтверждения работоспособности можно добавить запись в конфигурацию агента.

Как подключить пользовательский skill к своему агенту?

Скопируйте файл‑навыка в каталог ~/.agents вашего агента, сохранив его мета‑раздел и тело. Убедитесь, что enabled установлено в true и что description точно описывает задачу. Затем выполните agent-cli reload-skills (или перезапустите агента), после чего навык будет доступен через команды агента. При необходимости добавьте его в список активных навыков в конфигурационном файле агента.