api-designer - API Designer, проектирование REST и OpenAPI

Что понадобится: Node.js, если запускать проверку спецификации и пробный сервер.

Когда звать

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

Что это

Скилл для проектирования API: REST и GraphQL. Он нужен, когда ты строишь свой сервис или бота с внешним интерфейсом и хочешь, чтобы эндпоинты были единообразны. Набор ведёт разработчик под ником Jeffallan из компании Synergetic Solutions. Лицензия у набора MIT.

Идея скилла: перед тем как писать код, агент проходит шесть шагов из SKILL.md. Разберёт предметную область, смоделирует ресурсы (рисует схему до спецификации), опишет эндпоинты, выпустит спецификацию OpenAPI 3.1 и проверит её, поднимет пробный сервер и спланирует версии и устаревание.

Что обязательно и что запрещено

Скилл жёстко задаёт рамки. Обязательно: единый стиль имён, полная спецификация OpenAPI 3.1, ошибки в формате RFC 7807, постраничная выдача для всех списков, описание входа и прав, примеры запросов и ответов. Запрещено: глаголы в адресах (пиши /users/{id}, не /getUser/{id}), разные формы ответов, API без стратегии версий, поломка совместимости без плана перехода.

Внутри лежит готовый стартовый шаблон спецификации на YAML с курсорной пагинацией, ответами 400, 401, 404 и 429 и схемой ошибки. Его агент использует как исходный образец.

Как поставить

Команды из README и QUICKSTART автора.

В Claude Code (ставится весь набор):

/plugin marketplace add jeffallan/claude-skills
/plugin install fullstack-dev-skills@fullstack-dev-skills

В Codex у автора отдельной инструкции нет. В QUICKSTART описана универсальная установка только скиллов через skills.sh, она тоже кладёт весь набор:

npx skills add jeffallan/claude-skills

Мы эту команду для Codex не запускали. Чтобы взять только этот скилл, скопируй вручную папку skills/api-designer из репозитория в каталог скиллов своего агента. Для Claude Code это ~/.claude/skills, как в QUICKSTART автора. Подробнее про установку - в статье как установить скилл в Claude Code.

Проверка: попроси «спроектируй API для заказов в интернет-магазине». Агент должен сначала описать ресурсы и связи, и только потом писать код.

На что смотреть

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

Второе: набор большой, и это не только этот скилл. Если ставить плагином, у агента появятся ещё 66 скиллов с похожими описаниями, и агент может подбирать не тот, что ты хочешь. Для спокойной работы установи нужную папку вручную.

Мы прочитали SKILL.md целиком и список справочных файлов, проверили лицензию и номер версии на 22 октября 2026 года. Сам скилл на этой странице не запускали. Для соседних задач есть Secure Code Guardian про безопасность и SQL Pro про базу данных.