Що таке skills агентів і як вони працюють

Що насправді таке skill агента

Skill агента — це каталог на диску з файлом SKILL.md усередині. Цей файл містить назву, короткий опис та інструкції у форматі звичайного markdown. Агент завантажує опис під час запуску, а інструкції читає лише тоді, коли ваш запит відповідає цьому опису. Майже все інше у skills випливає з цих двох речень.

Каталог може містити не лише один файл. Специфікація Agent Skills визначає три необов’язкові каталоги: scripts/ для коду, який запускає агент, references/ для документів, які він читає за потреби, і assets/ для шаблонів та даних. Жоден із них не є обов’язковим. Каталог, у якому є лише файл SKILL.md, уже є повноцінним skill.

restore-drill/
  SKILL.md
  references/retention-policy.md
  scripts/verify_snapshot.sh

Опис — це частина, яку часто недооцінюють. Це єдиний текст, який агент бачить перед тим, як вирішити, чи відкривати skill взагалі. Тому в описі потрібно зазначити, що робить skill і коли його слід використовувати, словами, які люди справді вводили б у запиті.

Чому навичка майже нічого не коштує, доки її не використовують

Це аргумент, завдяки якому формат варто зрозуміти. Він стосується контексту, а не функцій. Завантаження відбувається поетапно. У специфікації це називається progressive disclosure.

Під час запуску агент завантажує name і description кожної встановленої навички, і більше нічого. У специфікації Agent Skills це оцінюється приблизно у 100 токенів на навичку (опубліковані рекомендації станом на August 2026). Якщо встановити дюжину навичок, буде витрачено приблизно стільки контексту, скільки займає один довгий абзац.

Коли запит відповідає опису, агент читає вміст лише одного SKILL.md. Специфікація рекомендує обмежити вміст 5,000 токенами, а файл — 500 рядками. Файли в references/ і scripts/ на цьому етапі все ще нічого не коштують. Файл довідкових матеріалів завантажується лише тоді, коли інструкції спрямовують до нього агента. Вбудований скрипт працює інакше: агент запускає його через shell, тому вихідний код скрипту не потрапляє у вікно контексту, а потрапляє туди лише його вивід.

Тепер порівняймо це з тим, до чого зазвичай звертаються спочатку: одним величезним промптом. За кожен рядок у system prompt або файлі інструкцій, який завжди активний, потрібно платити під час кожного запиту і в кожній сесії, незалежно від потреби завдання. Ці рядки також конкурують за увагу з фактичним запитанням. Десять тисяч токенів постійних інструкцій — це плата навіть за запитання про поточний час. Дюжина навичок у стані спокою займає приблизно 1,200 токенів і розширюється лише для завдання, якому вони потрібні. У цьому і полягає головна перевага навичок. Саме тому невелика бібліотека ефективніша за довший промпт.

Є один важливий нюанс. Після завантаження навички її вміст залишається в контексті до кінця сесії. Тому великий SKILL.md створює повторювані витрати, а не одноразові. Перенесення деталей у references/ — це не просто впорядкування. Так передбачено механізмом.

Навичка агента — це не виклик інструмента

Інструмент, який також називають викликом функції, — це те, що модель може викликати. Інфраструктура передає моделі схему: назву, опис і структуру аргументів. Модель формує виклик, ваш код його виконує, а результат повертається як повідомлення. Інструменти виконують дії.

Навичка сама нічого не виконує. Агент читає її, а потім діє за допомогою доступних йому інструментів. Модель не може передавати навичці аргументи так само, як вона передає їх інструменту. Навичка може лише вказати моделі, які інструменти використовувати, у якому порядку та що перевірити після цього.

Коротко: інструмент надає агенту нову можливість, а навичка допомагає йому правильно використовувати вже наявну можливість. Якщо певний крок щоразу має давати точний результат із перевіркою, потрібен інструмент або скрипт. Якщо для певного кроку потрібно послідовно застосовувати однаковий підхід, потрібна навичка. Навичка може складатися лише з рекомендацій щодо прийняття рішень і водночас бути тією, до якої ви звертаєтеся найчастіше, як показує Ponytail, яка спонукає агента розробки вносити найменшу працездатну зміну: вона не додає нових можливостей і лише змінює спосіб використання агентом уже доступних можливостей.

Навичка агента — це не MCP-сервер

MCP (model context protocol) — це протокол для підключення агента до зовнішньої системи. MCP-сервер — це процес, який працює, підтримує цей протокол і надає агенту інструменти. Зазвичай йому потрібні конфігурація, облікові дані та локальна команда або мережевий endpoint. Навичка — це папка з markdown-файлом. У ній немає процесу, порту чи протоколу.

Витрати контексту відрізняються так само. Кожен інструмент, який надає MCP-сервер, має назву, опис і схему аргументів. За замовчуванням вони додаються до запиту на весь сеанс незалежно від того, чи використовуються. Деякі клієнти вже почали завантажувати схеми інструментів на вимогу, але попереднє завантаження все ще є типовим варіантом. Навичка в стані спокою — це один рядок тексту.

Ці два підходи доповнюють один одного, і найнадійніші конфігурації використовують обидва. MCP-сервер надає доступ. Навичка описує процедуру: які з цих інструментів викликати для реального робочого процесу вашої команди, у якому порядку та як виглядає прийнятний результат. Якщо ви розміщуєте сервер самостійно, матеріал про запуск MCP-серверів на VPS описує цю частину.

Навичка агента — це не системний prompt і не AGENTS.md

Обидва є інструкціями у форматі markdown, тому така плутанина зрозуміла. Відмінність полягає в моменті їх завантаження. AGENTS.md, CLAUDE.md і системний prompt активні завжди. Навичка активується за потреби.

Перевірка складається з одного запитання: чи буде помилкою проігнорувати цей абзац у завданні, яке з ним не пов’язане? Правила стилю, команда збірки та правило іменування гілок застосовуються до кожного завдання, тому вони мають міститися у файлі, який завжди завантажується. Саме постійне завантаження цього файлу і є його призначенням. Контрольний список для релізу, який ви виконуєте двічі на місяць, не застосовується до кожного завдання, тому його слід розмістити в навичці. Якщо розділ файлу, який завжди завантажується, перетворився на нумеровану процедуру, це сигнал перенести його.

Для цих файлів також є власні правила, яких варто дотримуватися. Див. що має міститися в AGENTS.md, а що — у файлі для людини і design.md, який пояснює структуру кодової бази, щоб ознайомитися з двома файлами, які ми використовуємо.

Як виглядає мінімальний skill

У Claude Code персональні skills зберігаються в ~/.claude/skills/<name>/SKILL.md і застосовуються до всіх ваших проєктів. Skills проєкту зберігаються в .claude/skills/<name>/SKILL.md і додаються до git, тому вони доступні кожній людині та кожному агенту, які працюють у цьому репозиторії. GitHub Copilot і VS Code натомість читають skills робочої області з .github/skills/. Файл усередині має такий самий формат.

mkdir -p ~/.claude/skills/restore-drill

---
name: restore-drill
description: Run a restic restore drill and report what was recovered. Use when the user asks to test backups, verify a restore, or check that a snapshot is readable.
---

# Restore drill

1. Run `restic snapshots` and pick the newest snapshot for the host in question.
2. Restore it into a scratch directory under `/tmp`, never over live data.
3. Compare the restored file count and total size against the snapshot summary.
4. Report the snapshot ID and anything that failed to restore.

If `restic snapshots` prints `Fatal: unable to open config file`, the repository path or the password is wrong. Stop and report that instead of guessing.

Це повний skill. Назва каталогу стає командою, яку ви вводите, тому в цьому випадку це /restore-drill. У Claude Code меню /skills містить список установлених skills. Це найшвидший спосіб перевірити, чи файл було виявлено. Якщо skill відсутній у цьому меню, десь указано неправильне ім’я: файл має називатися SKILL.md, а назва каталогу може містити лише малі літери, цифри та одиночні дефіси. Така сама процедура, записана у формі, яку агент може повторно виконати, природно доповнює заплановані резервні копії restic на VPS, де запуск резервного копіювання не означає відновлення з резервної копії.

Коли навичку слід реалізувати як скрипт

Кожен крок, який щоразу має одну правильну відповідь, слід реалізувати як скрипт. Навичка при цьому має містити лише кілька рядків із поясненням, коли запускати скрипт і як читати його вивід. Для цього є дві практичні причини.

По-перше, вихідний код скрипту не потрапляє до контекстного вікна. Парсер на 300 рядків додає лише свій результат. Та сама логіка, описана в інструкціях Markdown, щоразу повністю збільшує обсяг навички під час її завантаження.

По-друге, скрипт двічі дає однакову відповідь. Якщо під час кожного запуску просити модель заново виводити те саме правило аналізу журналу, у невдалому випадку результат трохи відрізнятиметься. Це можна помітити лише тоді, коли два числа вже не збігаються.

Тому розділяйте роботу за типом. «Розібрати CSV і вивести кожен рядок, у якому підсумок не відповідає окремим позиціям» — це завдання для скрипту. «Переглянути рядки, виведені скриптом, і пояснити, які з них схожі на помилку під час введення даних» — це інструкція для навички. Зберігати оцінювання в Markdown, а детерміновану логіку — у коді означає дотримуватися того самого принципу, що й створення циклу, який агент може виконувати без вашого нагляду.

Чому мій skill ніколи не активується?

Тому що в його description описано, що робить skill, але не зазначено, коли його потрібно використовувати. Це єдиний рядок, з яким агент порівнює ваш запит. Фраза «Допомагає працювати з базами даних» не вказує на конкретний випадок. Натомість «Виконує міграцію схеми в staging-базі даних. Використовуйте, коли користувач просить мігрувати таблицю, додати стовпець або змінити схему» містить слова, які користувач справді вводить, тому skill активується.

Протилежна проблема — skill, який активується постійно. Опис на кшталт «Використовуйте для будь-яких змін коду в цьому репозиторії» відповідає будь-якому запиту. Тому тіло skill завантажується для кожного завдання й залишається в контексті до кінця сеансу. Звузьте опис до потрібного випадку. У Claude Code у frontmatter також можна вказати disable-model-invocation: true. Це вимикає автоматичне завантаження, але залишає skill доступним, коли ви вводите його назву.

Третя проблема — skill, який дублює інструмент. Інструкції, що вказують агенту curl API, який уже надає його MCP server, або виконувати пошук у файлах за допомогою grep, коли harness має інструмент пошуку, створюють повільніший шлях і два набори інструкцій, які можуть суперечити один одному. Видаліть дублювання й опишіть натомість потрібну дію.

Не намагайтеся вгадати, яка з цих трьох проблем виникла у вас. Двічі виконайте той самий prompt у новому сеансі: один раз із доступним skill, а другий — із вимкненим. Потім порівняйте відповіді. Новий сеанс важливий, оскільки сеанс, у якому ви написали skill, уже містить усе, що описано в skill. Це приховує прогалини в його тексті. Плагін Anthropic skill-creator автоматизує це порівняння в Claude Code. Він також генерує prompts, які мають і не мають активувати skill, і вимірює частоту кожного спрацювання.

Це формат одного постачальника чи стандарт?

Anthropic опублікувала цей формат наприкінці 2025 року, а потім випустила його як відкритий стандарт на agentskills.io. Станом на August 2026 ця специфікація визначає обов’язкові поля name і description, необов’язкові поля license, compatibility, metadata і allowed-tools, три необов’язкові каталоги та поетапне завантаження. Також опубліковано еталонний валідатор, тому skills-ref validate ./my-skill перевіряє каталог на відповідність специфікації перед тим, як ним ділитися.

Список клієнтів є головним показником. Ту саму папку читають Claude Code, Cursor, OpenAI Codex, Gemini CLI, GitHub Copilot, VS Code, Goose, OpenHands і opencode, серед інших. Microsoft публікує власні skills у цьому форматі на github.com/microsoft/skills, а також випускає десктопний інструмент Skill Recorder. Він записує виконання завдання, відтворює його як намір із впорядкованими кроками та зберігає результат як skill. Якщо постачальник створює recorder, вихідний формат якого визначається специфікацією іншої організації, це свідчить, що формат перестав бути функцією одного продукту.

Що написати спочатку

Не плануйте бібліотеку. Дочекайтеся моменту, коли втретє зловите себе на вставленні тих самих інструкцій у чат, а потім перенесіть цей текст у SKILL.md і видаліть вставку. Уже відчуте повторення — єдиний надійний сигнал, що навичку варто зберегти. Процедура пошуку добре підходить для першої навички, а навичка пошуку на базі власного екземпляра SearXNG показує, який вона має вигляд.

Дві звички допомагають підтримувати бібліотеку в належному стані. Перед установленням прочитайте кожну навичку, яку написали не ви, включно зі скриптами, оскільки навичка містить інструкції, яких дотримуватиметься ваш агент, і код, який він може запускати: ставтеся до неї як до встановлення програмного забезпечення від незнайомого розробника. Не зберігайте облікові дані в цій папці, оскільки навичка є текстовим файлом, який фіксують у репозиторії та поширюють. У матеріалі Як зберігати секрети окремо від агентів описано, де натомість мають зберігатися ці значення, а дорожня карта вивчення агентів цього року визначає місце навичок серед решти налаштувань.

FAQ

Яка різниця між навичкою агента та сервером MCP?

Сервер MCP (model context protocol) — це запущений процес, який надає агенту інструменти через протокол. Тому для нього потрібні конфігурація та облікові дані. Описи його інструментів зазвичай займають контекст протягом усього сеансу, навіть якщо ці інструменти не використовуються. Навичка агента — це каталог із файлом SKILL.md. Для неї не потрібні процес або протокол. Вона займає приблизно 100 токенів, доки агент не вирішить її прочитати. Використовуйте сервер MCP, щоб надати агенту доступ до системи. Використовуйте навичку, щоб описати агенту правильну процедуру роботи з цим доступом. У багатьох конфігураціях використовуються обидва варіанти.

Чи працюють навички агентів лише з Claude Code?

Ні. Anthropic розробила цей формат, а потім випустила його як відкритий стандарт на agentskills.io. Той самий каталог читають Cursor, OpenAI Codex, Gemini CLI, GitHub Copilot, VS Code, Goose, OpenHands та інші клієнти. Відрізняються розташування, де кожен клієнт шукає навички, і додаткові поля frontmatter, які він підтримує. Claude Code читає ~/.claude/skills/ і .claude/skills/, а GitHub Copilot та VS Code читають .github/skills/ у репозиторії. Сам файл SKILL.md переміщується між ними без змін.

Скільки навичок можна встановити, перш ніж це сповільнить роботу?

Обмеження визначається не кількістю навичок, а бюджетом запуску. Кожна встановлена навичка додає свою назву й опис. Згідно з опублікованими рекомендаціями специфікації, це приблизно 100 токенів, тому 30 навичок займають близько 3,000 токенів ще до використання будь-якої з них. Першою погіршується не швидкість, а вибір навички: якщо описи багатьох навичок перекриваються, моделі важче вибрати потрібну. Пишіть описи без перекриття та видаляйте навички, якими ви більше не користуєтеся.

Цю інструкцію слід додати до навички чи до AGENTS.md?

Визначте, чи стосується вона кожного завдання в репозиторії. Команди складання, внутрішні правила стилю та правила іменування стосуються всіх завдань. Тому їх слід зберігати у файлі, який завантажується завжди, адже саме для цього він призначений. Процедуру, яку ви виконуєте час від часу, наприклад контрольний список випуску або навчальне відновлення, слід оформити як навичку. Тоді вона не створює витрат у завданнях, де не потрібна. Якщо розділ AGENTS.md перетворився на нумеровану послідовність кроків, зазвичай це навичка, яку слід винести в окремий каталог.