Scalar API Reference — скилл для агентов
Scalar API Reference skill
Скилл подключает справочник Scalar к приложению по описанию OpenAPI: интеграции, аутентификация, темы и миграция со Swagger UI
- 16 337 ★ репозитория
- Последний коммит
- MIT
Минимальный доступ
Почему такой уровень
- Скилл только описывает порядок работы, но по нему агент ставит пакеты и правит маршруты вашего приложения
- Минимальный пример загружает отрисовщик с cdn.jsdelivr.net, а страница с включенным `persistAuth` хранит учетные данные в браузере
Установка
- Работает в
В терминале, через SkillFoxx CLI
npx skillfoxx add skills/scalar-api-reference-skillОпределит агенты на машине, покажет уровень доступа и зафиксирует версию.
Другие способы установки
Доступ и проверки
Как мы проверяемМинимальный доступИнструмент ничего не запускает и не ходит в сеть.
- Скилл только описывает порядок работы, но по нему агент ставит пакеты и правит маршруты вашего приложения
- Минимальный пример загружает отрисовщик с cdn.jsdelivr.net, а страница с включенным `persistAuth` хранит учетные данные в браузере
Это чужой код. Посмотрите файлы в репозитории перед установкой.
Что делает
Скилл `scalar-api-reference` лежит в папке `.agents/skills` репозитория Scalar, открытой платформы для работы с API. Он учит агента встроить в существующее приложение интерактивную документацию Scalar по описанию OpenAPI. Агент смотрит на фреймворк, версии пакетов, маршруты и адрес, по которому приложение уже отдает описание API, и выбирает подходящую интеграцию. В таблице скилла есть HTML и JavaScript, Vue, React, Next.js, Nuxt, Express, Fastify, Hono, NestJS, FastAPI и ASP.NET Core, и для каждой указаны пакет и точка входа. Описание API агент подключает через `url`, `content` или `sources`. Последний вариант позволяет показать несколько API с названием, `slug` и выбором по умолчанию. Скилл проверяет, что `url` указывает на адрес, доступный из браузера и отдающий JSON или YAML, а не на файл на диске или страницу документации. Отдельный раздел про аутентификацию различает доступ к странице документации, доступ к описанию и аутентификацию запросов к самому API: настройка клиента запросов страницу и описание не защищает. Внешний вид задается параметрами `theme`, `layout`, `showSidebar`, `darkMode` и переменными тем, а не правкой внутренних селекторов. Когда документацию Swagger UI или Redoc нужно заменить, агент сохраняет адрес описания и генератор, меняет только отрисовку на нужном маршруте и переносит лишь нужные настройки. В конце скилл требует проверить маршрут и точку описания по отдельности, убедиться в отображении операций и поиска и сообщить, что проверено, а что нет.
Для кого. Для бэкенд- и фуллстек-разработчиков, у которых уже есть описание OpenAPI и которым нужна страница справочника API на Scalar вместо Swagger UI или Redoc.
Подходит, если
- К приложению на FastAPI, NestJS, Hono или ASP.NET Core нужно добавить страницу справочника API по уже существующему описанию OpenAPI
- Swagger UI или Redoc надо заменить на Scalar, сохранив генератор описания и маршруты
- Страница документации открывается пустой, без стилей, или не находит описание из-за адреса, CORS или политики CSP
- Нужно показать на одной странице несколько API, например публичный и административный
- Нужно подогнать тему, вариант макета или пример кода по умолчанию под бренд проекта
Не подходит, если
- Нужно настроить размещенный сайт документации Scalar Docs или разработать отдельный клиент API: скилл относит эти задачи за пределы своей темы
- У приложения нет описания OpenAPI и не из чего его получить: скилл ничего не генерирует, он подключает отрисовку к готовому описанию
- Нужно писать код сервера на FastAPI под установленную версию пакета: для этого в каталоге есть официальный скилл FastAPI
- Нужны скиллы для разработки самого Scalar: другие скиллы папки `.agents/skills`, например для тестов, TypeScript и Vue-компонентов, написаны для участников репозитория
Пример запроса к агенту
Замени Swagger UI в моем FastAPI-приложении на Scalar по тому же описанию OpenAPI, тему сделай темную и оставь маршрут как естьОграничения
- Скилл подключает отрисовку и не создает описание API: без готового описания OpenAPI, доступного из браузера, ему нечего показывать.
- Таблица интеграций содержит минимальные точки входа. Названия параметров агент должен сверять с установленной версией пакета: у оберток для Python и .NET они отличаются от JavaScript.
- Параметр `persistAuth` хранит учетные данные в локальном хранилище браузера, поэтому скилл включает его только по просьбе. Секреты для продакшена в публичную конфигурацию не кладут.
- Параметр `proxyUrl` пропускает запросы и учетные данные через прокси, и скилл запрещает молча добавлять публичный прокси в существующее приложение.
- Страница при подключении через CDN может грузить отрисовщик другой версии, чем пакет-обертка, и тогда версию закрепляют параметром `bundle` или `cdn`, как описано в руководстве интеграции.
- Лицензия MIT.
Как отключить. Удалите папку `scalar-api-reference` из каталога скиллов вашего агента. Уже установленные пакеты Scalar и маршрут справочника остаются в проекте, их убирают вручную вместе с зависимостью `@scalar/api-reference` или пакетом интеграции.
Частые вопросы
Как установить скилл Scalar API Reference?
Выполните `npx skills add scalar/scalar --skill scalar-api-reference`. В README также есть готовый промпт для агента: он осматривает проект, выбирает интеграцию под фреймворк, публикует справочник по адресу `/scalar` и проверяет, что страница открывается.
Какие фреймворки поддерживает скилл?
В таблице скилла указаны HTML и JavaScript, Vue, React, Next.js, Nuxt, Express, Fastify, Hono, NestJS, FastAPI и ASP.NET Core. Для остальных скилл отсылает к каталогу интеграций и просит не подставлять пакет с похожим названием без проверки поддержки фреймворка.
Чем `url` отличается от `content` и `sources`?
Параметр `url` задает адрес, по которому браузер получает JSON или YAML. Параметр `content` передает описание объектом или строкой, и тогда оно попадает в браузер вместе со страницей. Параметр `sources` объединяет несколько описаний с названием, `slug` и выбором по умолчанию.
Защищает ли настройка аутентификации страницу документации?
Нет. Скилл различает три вещи: доступ к странице, доступ к описанию и аутентификацию запросов к API. Настройка клиента запросов защищает только последнее, а страницу и точку описания закрывают средствами приложения.
Как перейти со Swagger UI или Redoc?
Оставьте адрес описания или генератор как есть и замените отрисовку на нужном маршруте. Из настроек переносите только те, что нужны, потому что названия параметров Swagger UI и Redoc не совпадают с параметрами Scalar. Старую зависимость удаляют после проверки, что ее больше нигде не используют.
Обсуждение
Вопросов и отзывов пока нет.
Похожие
СкиллыСкилл FastAPI
FastAPI skill
Официальный скилл FastAPI, который поставляется вместе с пакетом и учит агента писать код под установленную версию
Скилл Payload
Payload agent skill
Официальный скилл Payload CMS, который приходит вместе с пакетом: коллекции, поля, хуки, доступы, запросы и адаптеры баз данных
Скилл Wildberries Seller API
Wildberries Seller API - Agent Skill
Скилл-справочник по Wildberries Seller API на локальных Swagger-файлах с поиском на русском и английском
builder-skills — скиллы для приложений на Convex
builder-skills
17 скиллов учат агента писать приложения на Convex по документации и вести проект через PRD, task.md и журнал изменений
tRPC — скиллы для агентов
tRPC skills
24 скилла в пакетах tRPC: сервер, адаптеры, клиент, Next.js, TanStack React Query и OpenAPI подгружаются агенту по теме задачи через TanStack Intent
Архитектура Laravel API
Laravel API Production-Ready Architecture Skill
Скилл, который удерживает агента в слоистой архитектуре Laravel API: JSON:API v1.1, строгие типы, PHPStan level 8 и тесты
Коротко о README
Описание Scalar представляет платформу из справочника API, клиента запросов, пакетов и интеграций. В разделе быстрого старта есть команда установки скилла, готовый промпт для агента, пример на чистом HTML и список поддерживаемых фреймворков и сред. Рядом приведена таблица продуктов Scalar со ссылками на документацию. В репозитории есть файлы AGENTS.md для пакетов и несколько скиллов, из которых в быстром старте назван один.
Бейдж для README
Исходный SKILL.md
--- name: scalar-api-reference description: Install, configure, and troubleshoot Scalar API Reference in an application, including framework integrations, API description loading, authentication, themes, and migration from Swagger UI or Redoc. Use for the embedded or self-hosted reference, rather than hosted Scalar Docs site configuration or standalone API Client development. --- # Scalar API Reference Add interactive API documentation to an existing application with the integration that matches its framework. Scalar renders an API description; preserve the application's existing description generator and API routes. ## Choose the integration Inspect the application's framework, package versions, routing conventions, and existing API description endpoint. Determine whether the user needs a standalone documentation route or a component embedded in the application layout.