Генератор навыков агента из OpenAPI: обзор CLI openapi-to-skills | AiManual
AiManual Logo Ai / Manual.
24 Янв 2026 • Инструмент

OpenAPI-to-Skills: превращаем документацию в навыки агента за 5 минут

Как автоматически создавать навыки для AI-агентов из OpenAPI спецификаций. Установка, конфигурация и интеграция с локальными агентами.

Вот тебе типичная ситуация 2026 года: у тебя есть REST API, ты написал для него красивую OpenAPI спецификацию, и теперь хочешь, чтобы твой AI-агент умел с ним работать. Что делаешь? Правильно - пишешь промпты, описываешь эндпоинты, создаешь структуру skill файлов... А потом понимаешь, что на это ушло три часа, и ты еще даже не начал тестировать.

openapi-to-skills решает эту проблему одним махом. Это CLI-инструмент, который берет твою OpenAPI спецификацию и выплевывает готовую структуру навыков для агента. Никаких ручных промптов, никакого копирования JSON схем. Просто npx openapi-to-skills и готово.

Что это за зверь и как он работает

По сути, openapi-to-skills - это парсер OpenAPI 3.x, который понимает структуру навыков современных AI-агентов. Он анализирует пути, параметры, схемы ответов и генерирует:

  • SKILL.md - основной файл с описанием навыка, примерами использования и промптами
  • tools.py - готовые функции для вызова API (если используешь Python-агентов)
  • schemas/ - JSON-схемы для валидации запросов и ответов
  • examples/ - реальные примеры запросов с разными параметрами

На конец января 2026 года инструмент поддерживает последнюю стабильную версию OpenAPI 3.1.1 и интегрируется с большинством популярных фреймворков для агентов, включая Deep Agents CLI и OpenAgent.

Установка и первое использование

Если у тебя уже стоит Node.js 18+ (а в 2026 году это должен быть минимум Node 22), установка занимает секунды:

npm install -g openapi-to-skills
# или
npx openapi-to-skills@latest generate --input openapi.yaml --output ./agent_skills

Базовый вызов выглядит так:

openapi-to-skills generate \
  --input ./api/openapi.json \
  --output ./skills \
  --agent-type deep-agent \
  --group-by tags

Флаг --group-by tags особенно крут. Если твоя OpenAPI спецификация хорошо структурирована по тегам (например, users, products, orders), инструмент создаст отдельные папки навыков для каждой группы эндпоинтов. Получается чистая модульная архитектура из коробки.

1 Что получаем на выходе

Допустим, у тебя есть API для управления задачами. После запуска генератора в папке ./skills появится структура:

skills/
├── tasks/
│   ├── SKILL.md
│   ├── tools.py
│   ├── schemas/
│   │   ├── Task.json
│   │   └── TaskList.json
│   └── examples/
│       ├── create_task.json
│       └── update_task.json
└── users/
    ├── SKILL.md
    └── ...

SKILL.md - это сердце каждого навыка. openapi-to-skills не просто копирует описание из OpenAPI, а генерирует осмысленный промпт, который агент действительно будет использовать. Вот как выглядит фрагмент:

# Tasks API Skill

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

## Доступные операции

### Создание задачи
POST /api/v1/tasks
Создает новую задачу в системе.

**Параметры тела запроса:**
- title (string, required): Название задачи
- description (string, optional): Подробное описание
- assignee_id (string, optional): ID назначенного пользователя

**Пример использования:**
```json
{
  "title": "Завершить проект",
  "description": "Нужно закончить все задачи до пятницы",
  "assignee_id": "user_123"
}
```

## Ограничения и предупреждения
- Максимальная длина title: 100 символов
- Для создания задачи требуется аутентификация
- Ответы кэшируются на 60 секунд

Видишь разницу? Это не сухой технический документ, а готовое руководство для агента. Инструмент вытаскивает constraints, примеры, обязательные параметры и форматирует их так, чтобы LLM могла это легко понять.

Интеграция с локальными агентами

Здесь начинается самое интересное. Сгенерированные навыки - это всего лишь сырой материал. Нужно их интегрировать в работающего агента.

💡
Если ты еще не знаком с концепцией динамических навыков для агентов, рекомендую сначала прочитать статью Skills для AI-агентов. Там объясняется, почему файловая система умнее любой оркестрации.

2 С Deep Agents CLI

Deep Agents CLI (актуальная версия на январь 2026 - 3.2.1) использует именно ту структуру навыков, которую генерирует openapi-to-skills. Просто копируешь папку с навыками в директорию агента:

# Предположим, твой агент живет здесь
AGENT_PATH="~/projects/my_agent"

# Копируем сгенерированные навыки
cp -r ./skills/* "$AGENT_PATH/agent_skills/"

# Перезапускаем агента
cd "$AGENT_PATH"
dagent reload-skills

Команда dagent reload-skills сканирует директорию agent_skills и автоматически загружает новые навыки в память агента. Никакой перекомпиляции, никаких перезапусков сервера.

3 С OpenAgent

OpenAgent (версия 2.4 на начало 2026) требует небольшой дополнительной конфигурации. Нужно указать путь к навыкам в конфигурационном файле:

# config/agent.yaml
skills:
  paths:
    - ./skills/tasks
    - ./skills/users
    
  auto_discover: true
  refresh_interval: 30s

OpenAgent поддерживает горячую перезагрузку навыков - если ты обновишь SKILL.md или добавишь новый файл в папку, агент подхватит изменения через 30 секунд (значение refresh_interval).

Альтернативы? Их почти нет

Когда я начал искать аналоги openapi-to-skills, то обнаружил удивительную вещь - в 2026 году это практически единственный инструмент, который делает именно конвертацию OpenAPI в навыки для агентов.

Инструмент Что делает Проблема
Swagger Codegen Генерирует клиентские библиотеки Не создает промпты для агентов
OpenAPI Generator Генерирует SDK и документацию Нет поддержки структур навыков
Ручное создание Полный контроль Занимает часы, подвержено ошибкам

Есть несколько инструментов для генерации промптов из OpenAPI (например, openapi-prompt-generator), но они создают единый монолитный промпт, а не модульную структуру навыков. А как мы уже знаем из статьи про файловую систему и оркестрацию, монолитные промпты - это путь в никуда.

Реальные кейсы использования

Зачем вообще это нужно? Вот несколько ситуаций, где openapi-to-skills спасает жизнь:

Микросервисная архитектура

У тебя 15 микросервисов, у каждого своя OpenAPI спецификация. Вместо того чтобы вручную создавать навыки для каждого сервиса, ты запускаешь скрипт:

#!/bin/bash
# generate_all_skills.sh

for spec in ./specs/*.yaml; do
  service_name=$(basename "$spec" .yaml)
  openapi-to-skills generate \
    --input "$spec" \
    --output "./skills/$service_name" \
    --prefix "$service_name"

done

Через 10 минут у тебя готовые навыки для всего стека. Агент теперь может работать с платежами, пользователями, заказами, аналитикой - всем сразу.

Быстрое прототипирование

Ты разрабатываешь новое API. Каждый день меняется спецификация. Вместо постоянного обновления промптов в агенте, ты просто регенерируешь навыки после каждого изменения OpenAPI файла. Интеграция с Git хуками делает это автоматически:

# .git/hooks/post-merge
#!/bin/bash

if [[ -f "openapi.yaml" ]]; then
  openapi-to-skills generate \
    --input openapi.yaml \
    --output ./skills \
    --force
fi

Документация, которая не врет

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

Важный нюанс: openapi-to-skills не валидирует само API, только его спецификацию. Если твое API возвращает не то, что описано в OpenAPI, агент будет работать с некорректными данными.

Ограничения и подводные камни

Как и любой автоматизированный инструмент, openapi-to-skills не идеален. Вот что нужно учитывать:

  • Качество спецификации = качество навыков. Если твоя OpenAPI спецификация написана кое-как (нет описаний параметров, непонятные названия операций), навыки получатся такими же. Мусор на входе - мусор на выходе.
  • Сложные схемы аутентификации. Инструмент хорошо обрабатывает базовые auth (Bearer token, API Key), но со сложными OAuth flows могут быть проблемы. Придется допиливать вручную.
  • Кастомные middleware. Если твое API имеет специфичную логику (ретраи, кэширование, rate limiting), openapi-to-skills этого не знает. Нужно добавлять в SKILL.md вручную.

Мой совет: используй openapi-to-skills как основу, а потом дорабатывай сгенерированные навыки под свои нужды. Особенно это касается примеров использования - инструмент генерирует базовые примеры, но реальные use cases часто сложнее.

Кому это нужно прямо сейчас

Если ты:

  • Разрабатываешь AI-агентов, которые работают с внешними API
  • Имеешь микросервисную архитектуру и хочешь дать агенту доступ ко всем сервисам
  • Устал вручную обновлять промпты при каждом изменении API
  • Ищешь способ автоматизировать onboarding новых разработчиков в проект с агентами

...то openapi-to-skills тебе пригодится. Особенно если ты уже работаешь с такими фреймворками как Deep Agents CLI или OpenAgent.

Если же твой агент работает только с локальными файлами или простыми HTTP запросами без сложной логики, возможно, инструмент будет избыточным. Но учитывая, как быстро развивается экосистема AI-агентов в 2026 году, рано или поздно интеграция с внешними API понадобится всем.

И последнее: не делай ошибку, пытаясь использовать openapi-to-skills для генерации навыков из внутренних, плохо документированных API. Сначала приведи спецификации в порядок. Потом уже автоматизируй. Иначе потратишь больше времени на исправление сгенерированного кода, чем сэкономил бы на его написании.

Инструмент доступен на GitHub и npm. На январь 2026 года актуальная версия - 1.3.2, с поддержкой OpenAPI 3.1.1 и улучшенной обработкой nested schemas.

←
На главную