Agent skill Jev: как дать ИИ-агенту (Claude Code, Cursor и др.) знания о Jev

Зачем агенту скилл

Модели, на которых работают Claude Code, Codex и Cursor, в большинстве своём обучались до выхода Jev. Без подсказки агент может принять её за обычную LLM и попробовать вызвать через чат-эндпоинт или написать запрос с полями, которых в API нет. TypeSafe упоминает эту проблему в разделе частых ошибок: агент придумывает поля запроса и ответа. Причину компания называет там же — устаревший скилл, а решение — обновить его и повторить задачу.

Скилл — это набор инструкций, который агент подгружает, когда задача подходит под описание. Скилл TypeSafe даёт агенту три вещи: устройство трёх типов вопросов, архитектурные паттерны и правила проектирования запросов. Сами типы вопросов подробно разобраны в статье о примитивах Jev.

Что внутри скилла

Репозиторий typesafe-ai/skills небольшой: один скилл typesafe-ai с файлом SKILL.md под лицензией MIT. Справочник API в него не вшит. Скилл работает как указатель: он требует считать живую документацию источником истины и читать её в ходе задачи.

Что скилл предписывает агенту:

• Начинать с индекса. Сначала открыть https://docs.typesafe.ai/llms.txt, затем читать нужные страницы в Markdown: к адресу страницы добавляется .md.
• Сверяться перед кодом. Перед интеграцией прочитать актуальную страницу API или SDK, а для нового сценария найти ближайший рецепт из раздела cookbooks.
• Не выдумывать. Если документация недоступна, опереться на локальные типы SDK, прямо сказать об этом ограничении и не придумывать детали, которые зависят от версии.

Кроме того, в скилле есть правила проектирования. Приведём главные.

Правило	Что это меняет в коде
Один вопрос — одно узкое суждение	Сложную оценку агент разбивает на несколько вопросов и собирает итог в коде
Имена вопросов модель не видит	Весь смысл должен быть в тексте instructions и criteria
Нужен вариант «ничего не подходит»	В choice появляется запасной вариант вроде other
Независимые вопросы — в один запрос	Вопросы к одному state уходят вместе, второй запрос нужен, только если он зависит от первого ответа
Пороги проверяются на данных	Агент не переносит пороги из примеров как готовые
Ключи API — только на сервере	В веб-приложении вызов Jev уходит в серверный код

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

Установка в Claude Code

Скилл распространяется как плагин. Выполните в терминале две команды:

claude plugin marketplace add typesafe-ai/skills
claude plugin install typesafe@typesafe-ai

Явно вызвать скилл можно командой /typesafe:typesafe-ai.

Установка в Cursor, Codex и другие агенты

Для остальных агентов TypeSafe предлагает установщик skills.sh:

npx skills add typesafe-ai/skills --skill typesafe-ai

Установщик спросит, для какого агента ставить скилл. По умолчанию скилл ставится в текущий проект, флаг -g ставит его глобально. Агента можно указать сразу флагом -a, например -a cursor.

По данным репозитория установщика, он поддерживает Claude Code, Codex, Cursor, OpenCode, Windsurf, GitHub Copilot, Gemini CLI и ещё несколько десятков агентов. Куда ложатся файлы:

Агент	Флаг -a	В проекте	Глобально
Cursor	cursor	.agents/skills/	~/.cursor/skills/
Codex	codex	.agents/skills/	~/.codex/skills/
Claude Code	claude-code	.claude/skills/	~/.claude/skills/
Windsurf	windsurf	.windsurf/skills/	~/.codeium/windsurf/skills/

Если установщик не подходит, скопируйте папку skills/typesafe-ai из репозитория в каталог скиллов вашего агента. Есть и третий путь: вставить агенту промпт-инструкцию со страницы документации, и он установит скилл сам. Выберите один способ, иначе появятся дубликаты.

Как обновлять

По словам TypeSafe, устаревшая версия скилла снова приводит к выдуманным полям, поэтому обновляйте его.

• Claude Code: claude plugin marketplace update typesafe-ai, затем claude plugin update typesafe@typesafe-ai. После этого перезапустите агента или выполните /reload-plugins. Автообновление включается в /plugin: Marketplaces → typesafe-ai → Enable auto-update.
• skills.sh: npx skills update.
• Ручная копия: замените папку скилла целиком свежей версией с GitHub.

С чего начать: три промпта

TypeSafe советует прямо называть скилл в промпте: фраза «используй скилл TypeSafe» работает в любом агенте. Промпты из документации в пересказе:

1. Поиск применений. «Используя скилл TypeSafe, изучи проект и найди места, где хрупкий парсинг или сложные правила можно заменить суждением модели».
2. Эксперименты на API. «Используя скилл TypeSafe, проведи эксперименты с API, ключ лежит в переменной TYPESAFE_API_KEY. Предложи изменения по самым удачным результатам». Агент будет сам гонять дешёвые тестовые запросы. Дайте ему отдельный ключ, который не жалко отозвать.
3. Рецепты. «Используя скилл TypeSafe, проверь, какие рецепты из документации подходят к моему коду и помогут сделать его проще и надёжнее».

Если вы работаете через Polza.AI или другой шлюз

Скилл и примеры в документации рассчитаны на API TypeSafe по адресу https://api.typesafe.ai. Если ключ получен у агрегатора, агент об этом не знает и может вписать в код адрес TypeSafe. Проще всего вынести настройки в переменные окружения, которые читают официальные SDK:

export TYPESAFE_BASE_URL="https://polza.ai/api"
export TYPESAFE_API_KEY="ключ_polza"
export TYPESAFE_DEFAULT_MODEL="typesafe/jev"

Добавьте строку об этом в файл инструкций проекта (CLAUDE.md для Claude Code, AGENTS.md для Codex). Тогда агент не будет вписывать адрес и модель в код. Пошаговое подключение агрегатора описано в статье о Jev через Polza.AI.

Как проверять код агента

У TypeSafe есть короткий список правил для такой работы. Суть:

• Обсудите план. Сначала поговорите с агентом о задаче и проверьте план, потом разрешайте писать код.
• Держите вопросы в одном месте. Формулировки вопросов и пороги должны лежать в одном файле. TypeSafe признаёт, что агенты пока плохо пишут вопросы, поэтому формулировки придётся доводить вместе. На ревью человек смотрит прежде всего на них.
• Не верьте на слово. Просите агента проверять свои допущения, например тестовыми запросами.

И три типичные ошибки:

• Маршрутизация срабатывает не так. Скорее всего, пороги слишком высоки (пропуски) или слишком низки (ложные срабатывания), либо вопрос сформулирован размыто.
• Пороги по confidence повсюду. Если нужно просто выбрать лучший вариант, порог не нужен: берите вариант, который вернула модель в поле choice. Для своих статистических расчётов берите вероятности, а не confidence. Разница объяснена в статье об уверенности Jev.
• Агент не использует скилл. В Claude Code вызовите /typesafe:typesafe-ai, в других агентах напишите «используй скилл TypeSafe». Если не помогло, проверьте, что установщик ставил скилл для нужного агента, и перезапустите его.

Если агент написал запрос руками, сверьте его со справочником API Jev: поля model, state и questions, типы noul, choice и score.