Як Supabase перетворює «скіли» з іграшки на основу для агентів
У спільноті AI-інженерів слово «skill» уже встигло стати майже мемом: усі про нього чули, багато хто щось пробував, але небагато реально використовують це в бойових продуктах. На конференції AI Engineer інженер з AI-інструментів Supabase Педру Родрігеш показує протилежний підхід: у Supabase скіли стали «секретним соусом» для того, щоб агенти впевнено працювали з реальними робочими процесами в екосистемі Supabase, а не залишалися демонстраційною іграшкою.
Supabase, як відкритий backend-as-a-service на основі Postgres, має кілька продуктів і складні робочі процеси — від керування базою до міграцій і інтеграцій. Завдання Родрігеша як AI tooling engineer — зробити цю платформу «agent-friendly», тобто такою, де агенти не губляться в документації й інструментах, а послідовно виконують корисну роботу. Центральний елемент цієї стратегії — грамотно спроєктовані скіли.
Скіл як папка, а не як prompt: базова модель Supabase
У багатьох розробників «skill» асоціюється з одним markdown-файлом із інструкціями. У Supabase цю модель розширили до повноцінної файлової структури, яка ближче до невеликого пакета знань і сценаріїв, ніж до одного системного промпта.
Скіл у цьому підході — це завжди папка на диску. Усередині неї обов’язково є один головний файл skill.md, а поруч можуть лежати додаткові довідкові файли та скрипти. Така структура дозволяє мислити скілом як модулем: він містить опис, деталізовані інструкції, приклади, допоміжні матеріали й навіть виконувані дії.
skill.md — це не просто довільний markdown. У Supabase він починається з front matter-блоку, подібного до того, що використовують у статичних генераторах сайтів. У цьому блоці є щонайменше два обов’язкові поля: name і description. Назва і опис — це те, що агент бачить першим і на основі чого взагалі вирішує, чи варто звертатися до цього скіла.
Ці два поля виконують роль візитівки: вони ідентифікують скіл і коротко пояснюють, що він уміє і коли його доречно застосувати. Усе інше — розгорнуті інструкції, приклади, посилання на додаткові файли — може бути присутнім, але не потрапляє в контекст моделі автоматично.
Така дисципліна структурування потрібна не заради краси. Вона закладає основу для того, що в Supabase вважають головною перевагою скілів над класичними інструментами: прогресивного розкриття інформації.
Прогресивне розкриття: як не «забити» контекст і не заплутати агента
Класична проблема роботи з великими мовними моделями — обмежений контекст і «інформаційний шум». Якщо завантажити в промпт усе, що може знадобитися агенту, модель починає губитися в інструкціях, а токени витрачаються на текст, який у більшості запитів не потрібен.
Скіли в Supabase спроєктовані так, щоб уникнути цієї пастки. skill.md працює як «конверт» із коротким описом можливостей, а не як розгорнута інструкція, яка завжди опиняється в контексті. На старті в модель підвантажується лише front matter — тобто назва й опис. Усе інше залишається «закритим» доти, доки агент сам не вирішить, що йому потрібні деталі.
Це і є прогресивне розкриття: замість того, щоб одразу вивалювати на модель повну документацію, система дає їй каталог можливостей. Агент бачить, що існує, умовно, скіл «Supabase migrations workflow» із описом, що він допомагає безпечно застосовувати міграції. Якщо поточне завдання пов’язане з міграціями, агент може явно запросити вміст цього скіла, прочитати детальні інструкції, а вже потім — за потреби — дістатися до додаткових файлів і скриптів.
Такий підхід знімає одразу кілька обмежень. По-перше, розробник може вкладати в скіл значно більше знань, не боячись, що вони постійно «з’їдатимуть» контекст. По-друге, агент отримує можливість самостійно керувати глибиною занурення: для простих запитів йому вистачає опису, для складних — він поступово розкриває все більше шарів інформації.
Скіл як книга: посилання, граф файлів і роль reference-матеріалів
Щойно агент вирішує «розкрити» скіл, у гру вступає друга частина структури — довідкові файли. У Supabase їх зазвичай кладуть у окрему папку, умовно references, але з точки зору агента це просто додаткові ресурси, на які посилається skill.md.
Ці файли найчастіше теж markdown-документи або скрипти. Markdown використовується для розширених інструкцій, прикладів, покрокових гайдів, специфічних нюансів продукту. Скрипти — для автоматизації повторюваних дій. Важливий момент: сам skill.md може містити посилання на ці файли, а вони, у свою чергу, можуть посилатися на інші. У результаті скіл перетворюється на невеликий граф пов’язаних ресурсів.
Родрігеш пропонує мислити скілом як книжкою. skill.md у цій метафорі — це «зміст на стероїдах»: він не лише перераховує розділи, а й дає коротке резюме, навіщо кожен із них потрібен, і в яких ситуаціях до нього варто звертатися. Reference-файли — це розділи й підрозділи цієї книги, де зберігається детальна інформація.
Те, що reference-файли не мають жодної «магічної» структури, теж важливо. Це звичайні markdown-документи, які можна редагувати, версіонувати, рецензувати так само, як будь-яку технічну документацію. Єдина відмінність — вони вбудовані в навігаційну логіку скіла й доступні агенту через посилання, а не через ручний пошук.
Можливість будувати граф посилань усередині скіла відкриває шлях до складніших сценаріїв. Наприклад, один reference-файл може описувати загальний workflow роботи з Supabase-проєктом, інший — специфіку роботи з аутентифікацією, третій — edge-кейси при міграціях. Агент, рухаючись за посиланнями, може поступово уточнювати контекст, не завантажуючи все одразу.
Скрипти в скілах проти MCP-інструментів: локальне проти серверного
Окремий пласт — це скрипти, які можуть лежати поруч із skill.md або в reference-папці. На перший погляд вони схожі на інструменти MCP (Model Context Protocol): і там, і там агент може викликати якусь дію, а не лише читати текст. Саме це й породило хвилю дискусій після появи скілів: якщо можна покласти скрипти в скіл, навіщо взагалі потрібні MCP-сервери?
Родрігеш пропонує дивитися на це як на порівняння «яблук з апельсинами». Головна відмінність — де і як виконуються ці дії.
Скрипти в скілах завжди запускаються в локальному середовищі користувача. Це означає, що вони прив’язані до операційної системи й оточення, у якому працює агент. Якщо користувач на Linux — скрипти мають бути сумісні з Linux. Якщо на macOS — відповідно, з macOS. Для Windows, як жартує доповідач, ситуація ще складніша, але принцип той самий: скіл-скрипт — це локальний інструмент, який живе поруч із проєктом і працює в тій самій системі.
MCP-інструменти, навпаки, не потребують локального середовища. Агент викликає їх через MCP-сервер, і виконання відбувається на стороні сервера, часто віддаленого. Це робить їх природним вибором для інтеграцій із зовнішніми сервісами, бекендами, API, де немає сенсу або можливості покладатися на локальний shell користувача.
Звідси й практична рекомендація, яку просуває Supabase: не обирати між скілами й MCP, а комбінувати їх. MCP — для інтеграцій, мережевих викликів, операцій із побічними ефектами, які мають виконуватися на сервері. Скіли — для контексту, знань про продукт, описів workflow і локальних сценаріїв, де агенту потрібно не стільки «піти в інтернет», скільки правильно поводитися з уже наявним проєктом.
Це розділення ролей знімає й ще одну напругу: опис workflow. Описувати складні послідовності дій у полі «description» MCP-інструменту незручно й обмежено. У скілі ж можна розкласти workflow на кілька reference-файлів, додати приклади, попередження, типові помилки — і дати агенту можливість крок за кроком слідувати цій «книзі».
Скіли як основа «досвіду агента» в екосистемі Supabase
У Supabase цю архітектуру не залишили на рівні теорії. За словами Родрігеша, останні місяці команда системно писала власні скіли для різних продуктів компанії, а потім виводила їх у продакшн. Мета — не просто додати агенту ще один спосіб взаємодії, а побудувати новий тип «досвіду агента» (AX, agent experience), аналогічний тому, як розробники говорять про developer experience (DX).
У цьому підході скіл — це не «доважок» до агента, а основний носій знань про те, як правильно працювати з Supabase-проєктами. Самі MCP-інструменти, CLI й інші засоби стають «м’язами», які виконують дії, тоді як скіли — це «інструкція до тіла», що пояснює, коли й як ці м’язи задіяти.
Прогресивне розкриття дозволяє масштабувати цю інструкцію без страху перевантажити модель. Граф reference-файлів дає можливість моделювати складні доменні знання, не перетворюючи їх на монолітний prompt. Локальні скрипти в скілах дають агенту доступ до реальних робочих процесів на машині розробника, а MCP-інструменти — до зовнішніх сервісів.
Усе це разом формує більш керовану, передбачувану поведінку агентів у реальних робочих середовищах Supabase. Замість того, щоб сподіватися, що модель «сама здогадається», як правильно працювати з міграціями, таблицями чи конфігураціями, команда явно кодує ці знання в скіли, а потім навчає агентів користуватися ними.
Висновок: скіли як інженерний артефакт, а не як prompt-хак
Підхід Supabase до скілів показує, як змінюється культура роботи з агентами. Замість чергового «prompt engineering» на льоту, скіли перетворюються на повноцінний інженерний артефакт: з чіткою файловою структурою, front matter, графом посилань, локальними скриптами й продуманою взаємодією з MCP-інструментами.
Ключові ідеї цього підходу можна звести до кількох принципів. Скіл — це завжди папка, а не один файл. Головний skill.md містить мінімально необхідний front matter із назвою й описом, які служать «анонсом» можливостей для агента. Уся інша інформація розкривається прогресивно, лише коли агенту це потрібно. Reference-файли утворюють граф знань, яким агент може навігувати, а скрипти дають змогу виконувати дії в локальному середовищі, доповнюючи серверні MCP-інструменти.
У результаті скіли перестають бути демонстраційною «фішкою» і стають основою того, як агенти поводяться в складних продуктах на кшталт Supabase. Для інженерів, які будують власні агентні системи, це сигнал: час перестати сприймати skills як ще один формат prompt’ів і почати проєктувати їх як модульну, керовану інфраструктуру знань і workflow.
Джерело
Skill Issue: How We Used AI to Make Agents Actually Good at Supabase — Pedro Rodrigues, Supabase