Власні скіли Claude Code: SKILL.md, тригери, debugging
CC ≥ 2.x з підтримкою скілів. Перевір ~/.claude/skills/ (глобальний рівень) і .claude/skills/ у проєкті — це два місця, де CC шукає твої скіли. Якщо їх немає — створи (це звичайні директорії).
Що таке скіл — у двох реченнях
Скіл — це директорія, у якій є файл SKILL.md. Сам файл містить frontmatter (YAML-блок з метаданими) і тіло — markdown-інструкцію для моделі. CC сам читає всі скіли при старті сесії, додає їх у локальний список slash-команд (як /<назва>) і може ініціювати без явного введення на основі поля description.
Чим скіл відрізняється від CLAUDE.md: CLAUDE.md — глобальні інструкції на весь проєкт (завжди в контексті), скіл — точкова процедура, яку CC підтягує тільки коли вона потрібна. Чим від MCP-tool: tool — програма (Python/JS код), скіл — лише інструкція моделі словами.
Анатомія SKILL.md
--- name: weekly-digest-bas-updates description: Тижневий бухгалтерський дайджест BAS — збирає оновлення з форумів і пише пост у phpBB --- Збери оновлення BAS Бухгалтерія / Роздрібна торгівля / Малий бізнес за тиждень. Джерела: 1. Офіційний канал Telegram @BAS_news (через bot API) 2. Форум it-bas.com.ua, розділ "Оновлення" Алгоритм: 1. Зайди на server-1 і виконай скрипт `scripts/bas_pull.sh` 2. Прочитай результат у JSON 3. Згенеруй пост на 600-900 слів у форматі bbcode...
Ключове:
name— це slug, який стане slash-командою (/weekly-digest-bas-updates). Тільки lowercase + дефіси.description— це індекс. CC бачить його у системному промті й вирішує, чи запропонувати скіл сам. Описуй конкретно, з тригерними словами.- Тіло — це звичайний markdown, який стає інструкцією моделі. Структуруй як SOP: вхідні дані, кроки, формат виводу.
Тригери: коли CC запускає скіл сам vs коли руками
Це найчастіше плутає новачків. CC бачить description кожного скіла у системному промті — як «у мене є інструмент /foo для X, Y, Z». Залежно від твого промту, він обирає:
- Запустити сам. Якщо твоє запитання чітко мепиться на description («тижневий дайджест BAS» — точно
/weekly-digest-bas-updates) — CC викликає скіл без зайвих питань. - Запропонувати. Якщо співпадіння часткове — CC може запитати «хочеш запустити
/foo?» або просто запропонувати у відповіді. - Чекати руками. Якщо description розпливчастий, або у твоєму повідомленні немає тригерних слів — CC не побачить зв'язку. Введи
/<name>явно.
Тому description — це 50% успіху скіла. Пиши його як заголовок розділу новин: коротко, з конкретними словами.
Області видимості
| Шлях | Видимість | Коли використовувати |
|---|---|---|
~/.claude/skills/<name>/SKILL.md | Усі сесії, усі проєкти твого користувача | Особисті утиліти: /weekly-digest, /new-project, dotfiles-bootstrap |
<repo>/.claude/skills/<name>/SKILL.md | Тільки у цьому проєкті, для всіх, хто клонує репо | Командні скіли: /release, /migrate, /seed-db |
Плагінні (plugin:<name>) | З підключеного CC-плагіна | Готові набори від спільноти |
Project-level скіли — у git разом з кодом, тому treat them as code: PR-ревʼю, версіонування. User-level — особистий toolkit.
Debugging скіла
Скіл не запустився, хоча ти його ввів? Розбираємось:
- Перевір, що CC його бачить. Запусти
/help— у списку має бути/<name>. Якщо немає — frontmatter зламаний (часто причина — табуляція замість пробілів у YAML, або відсутній закриваючий---). - Перевір frontmatter. Поля
nameіdescriptionобов'язкові. Name тількиkebab-case. У description без переносів рядка (один рядок). - Перевір видимість. Якщо клав у
.claude/skills/<name>/проєкту — переконайся, що ти у тому проєкті (CC бачить project-скіли тільки в активному каталозі). - Подивись system-reminder. На початку сесії CC показує список доступних скілів у system-reminder — там видно, як description виглядає для моделі.
- Запусти руками. Введи точно
/<name>— якщо тепер працює, проблема була у тригерах (description не співпав з твоїм промтом).
Реальні кейси з офісу
1. /weekly-digest-bas-updates — щотижневий бухгалтерський дайджест
Скіл, який CC запускає за cron щопонеділка о 08:00 на офісному сервері. Збирає оновлення BAS за тиждень з кількох джерел, формує пост у форматі bbcode і публікує у phpBB-форум для бухгалтерів.
Структура SKILL.md (~70 рядків):
- Frontmatter — name, description «дайджест BAS оновлень за тиждень».
- Розділ «Джерела» — конкретні URL і скрипти.
- Розділ «Алгоритм» — кроки з посиланнями на готові tools/скрипти, що вже є на сервері.
- Розділ «Формат виводу» — приклад готового поста.
- Розділ «Edge cases» — що робити, якщо за тиждень не було жодного оновлення (заглушка-пост).
Запускається через системний cron, докладніше — у спиці «Recurring jobs».
2. /forum-traffic-report — звіт по трафіку форуму
Скіл-відповідь на питання «що з форумом цього тижня». Збирає метрики з phpBB (active users, нові теми, нові пости), фільтрує бот-трафік, рисує таблицю і відправляє у Telegram-канал. Cron-варіант — раз на тиждень; manually — будь-коли через /forum-traffic-report.
3. /new-project — bootstrap нового EDT-проекту
Інтерактивний скіл. Питає тип проєкту (керована форма / звичайна обробка / зовнішній звіт), назву, цільову конфігурацію — і генерує скелет з правильною структурою каталогів, файлами Configuration.xml, README.md, .claude/CLAUDE.md з профілем проєкту.
Економить ~20 хвилин на старті нового проекту і вбезпечує від помилок типу «забув SCM-ignore для tempdirs».
4. /create-cfe-managed — обгортка повторюваного промту
Найпростіший варіант скіла: один файл SKILL.md з інструкцією моделі «створи розширення керованої форми, тип Patch, мінімальна сумісність 8.3.10, префікс об'єктів запитай у користувача». Закріпляє у скіл те, що раніше копіювалось у промт щоразу.
Take-away: скіл не зобов'язаний робити щось хитре. Часом це просто «промт, який не хочеться писати втретє».
Підводні камені
Конфлікти по description. Якщо два скіли мають близькі описи (наприклад, обидва про «звіт по трафіку»), CC плутається — може запропонувати не той. Лікується конкретикою у description: не «звіт по трафіку», а «звіт по трафіку phpBB-форуму».
Імена з підкресленнями або camelCase. CC очікує kebab-case у name. Якщо назвав weeklyDigest — скіл не з'явиться як slash. Перейменувати у weekly-digest.
Скіли НЕ успадковують контекст основної сесії. Це і плюс (чистий старт, менше шуму), і мінус (треба в тіло SKILL.md явно вписати «прочитай CLAUDE.md цього репо», або зробити це через MCP/tool). Memory теж не успадковується — це задокументовано у спиці «Memory system».
Description у YAML на одному рядку. Якщо перенесеш description через n або folded-блок (>) — CC покаже як один рядок, але внутрішня індексація може поплисти. Тримай одним рядком до 150 символів.
Project-скіли у public-репо — потенційно витік. Якщо скіл містить URLs внутрішньої інфраструктури або інструкції з посиланнями на private-сервери — або тримай як local-only (.claude/skills.local/, додай у gitignore), або винеси sensitive-частини у CLAUDE.md.local.
Cross-refs
- Список усіх slash, включно зі скілами — «Slash-команди Claude Code».
- Запуск скіла за розкладом — «Recurring jobs».
- Permissions для tools, які викликає скіл — «Permissions і settings.json».
- Як скіл взаємодіє з memory — «Memory у Claude Code».
- Frontmatter валідний (YAML-парсер не падає), name у kebab-case.
- Description описує конкретний use-case з тригерними словами.
- Тіло має розділи «Вхід», «Алгоритм», «Вихід», «Edge cases».
- Якщо скіл звертається до зовнішніх ресурсів — в інструкції явно вказано, що зробити при помилці мережі.
- Якщо скіл працює з sensitive-даними — лежить локально (
~/.claude/skills/), не у проєкті в git. - Перевірено в чистій сесії (
/clear) — скіл працює без залежності від попереднього контексту.
Розділ «формат SKILL.md» для CC станом на травень 2026. Anthropic може розширити frontmatter (наприклад, додати args, model, permissions) — slidwidth перевіряти при оновленні CLI. Свіжий контракт — у /help skills.
