Скіли у Claude Code

Скіл — це папка з файлом SKILL.md: зверху YAML frontmatter між рядками ---, нижче — Markdown-інструкції. Поруч можуть лежати довідники, шаблони та скрипти. Claude сам вирішує, коли скіл доречний, або ви запускаєте його вручну командою /назва-скілу.

Головна ідея — прогресивне розкриття (progressive disclosure). У контекст сесії завжди потрапляє лише назва й опис скілу. Тіло SKILL.md підвантажується в момент використання, а допоміжні файли — тільки якщо інструкція на них посилається і вони справді потрібні. Тому можна мати десятки скілів і великі довідники, не платячи за них токенами в кожному запиті.

Скіли — відкритий формат Agent Skills: той самий SKILL.md працює в Claude Code, у claude.ai (завантаження zip у Settings → Features) та через Claude API (/v1/skills). Але між цими поверхнями скіли не синхронізуються — див. розділ «Обмеження».

Кожен раз, коли ви вдруге пояснюєте Claude одне й те саме — як у вас пишуться міграції, який формат комітів, як релізити, — це кандидат у скіл. Скіл перетворює «знання в голові сеньйора» на процедуру, яку Claude виконує однаково для всієї команди.

• Повторювані процедури — реліз, коміт, code review, онбординг нового сервісу
• Командні конвенції — API-стиль DRF, структура Vue-компонентів, правила міграцій
• Довідкові знання — схема БД, внутрішні API, бізнес-правила, які Claude не може знати сам
• Детерміновані кроки — скрипти валідації, генерації, перевірки, які надійніше запустити, ніж генерувати щоразу
• Економія контексту — довгі інструкції не висять у кожній сесії, як у CLAUDE.md

Скіл чи щось інше?

Скільки це економить

Приблизна оцінка для середнього Django/Vue-проєкту; реальні числа покаже /context.

Що відбувається з контекстом далі

• Відрендерений скіл лишається в розмові на наступних ходах; повторний виклик того самого тексту додає лише коротку позначку «вже завантажено»
• Зміни у файлі скілу підхоплюються «на льоту» для нових викликів — вже завантажений текст не оновлюється
• При компактизації останній виклик кожного скілу повертається в контекст, але лише перші 5 000 токенів; усі повернуті скіли ділять спільний бюджет 25 000 токенів
• Тому найважливіші правила пишіть на початку SKILL.md, а формулюйте їх як постійні («після кожної зміни запускай тести»), а не одноразові кроки

• Конфлікт назв: enterprise > особистий > проєкт. Скіл перекриває однойменну вбудовану команду і файл у .claude/commands/. Скіли плагінів не конфліктують — вони з префіксом
• Монорепо: проєктні скіли збираються від стартової папки до кореня репозиторію; вкладені — коли Claude вперше читає чи редагує файл у тій підпапці. Однакові назви розводяться як /deploy і /apps/web:deploy
• Worktree: пошук зупиняється на корені worktree; якщо там скілів немає — беруться скіли основного checkout
• Зміни на льоту: правки в наявних папках скілів підхоплюються одразу; для нового каталогу skills/ виконайте /reload-skills
• Cowork і cloud-сесії не читають ~/.claude/skills/ — лише скіли, увімкнені в акаунті claude.ai, і проєктні скіли з репозиторію
• Папку скілу можна зробити симлінком — зручно для спільної бібліотеки скілів між проєктами

Мінімум — один файл з описом. Збережіть як ~/.claude/skills/summarize-changes/SKILL.md:

---
name: summarize-changes
description: Summarizes uncommitted changes and flags risks. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---

## Поточні зміни

!`git diff HEAD`

## Інструкція

Підсумуй зміни вище в 2–3 пунктах українською, потім перелічи ризики:
відсутня обробка помилок, захардкоджені значення, тести, які треба оновити.
Якщо diff порожній — так і скажи.

Тепер скіл спрацює і на /summarize-changes, і на звичайне «що я змінив?». Анатомія файлу:

1. Frontmatter — YAML між ---, обов’язково з першого рядка файлу. Інакше весь файл вважається тілом, а метадані — порожніми
2. Тіло — Markdown-інструкції. Пишіть як для досвідченого колеги: що зробити, в якому порядку, який результат. Не пояснюйте те, що Claude і так знає
3. Динамічні вставки — !`команда` виконується до того, як Claude побачить текст
4. Посилання на файли — [reference.md](reference.md), щоб Claude знав, що і коли дочитати

---
name: release
description: Prepares a release - bumps version, writes CHANGELOG, tags. Use when the user asks to cut, prepare or publish a release.
argument-hint: "[version]"
disable-model-invocation: true     # реліз — лише за явною командою
allowed-tools: Bash(git tag *) Bash(git log *) Bash(npm version *)
model: sonnet
effort: medium
---

Булеві поля приймають true/false, а також yes/no, on/off, 1/0. Якщо YAML не парситься, скіл завантажиться з порожніми метаданими: /name працюватиме, але автоматично Claude його не знайде. Перевірка — claude plugin validate .claude/skills або запуск з --debug.

Підстановки

---
name: release-notes
description: Writes release notes between two git tags. Use when the user asks for release notes or a changelog between versions.
arguments: [from, to]
argument-hint: "<from-tag> <to-tag>"
---

## Коміти між $from і $to

!`git log --oneline --no-merges $from..$to`

Згрупуй коміти за типом Conventional Commits (feat / fix / chore) і напиши
release notes українською для менеджерів: без хешів, людською мовою.

Виклик /release-notes v2.4.0 v2.5.0: спочатку підставляються аргументи, потім виконується git log, і Claude отримує вже готовий список комітів. Аргументи з пробілами беріть у лапки: /my-skill "hello world" second. Знак долара екрануйте: \$1.00.

Динамічні вставки

• !`команда` — на початку рядка або після пробілу; KEY=!`cmd` лишається як є
• Багаторядковий варіант — fenced-блок, що відкривається ```!
• Вивід підставляється як є і повторно не сканується на плейсхолдери
• Ненульовий код виходу скасовує весь виклик скілу (виняток — код 1 у пошукових/порівняльних командах). Для очікуваних збоїв додайте || true
• Кожна команда має таймаут Bash — 2 хвилини
• Команди проходять перевірку дозволів: deny-правило скасовує виклик; не дозволену команду треба передозволити через allowed-tools

---
name: render-chart
description: Render a chart from a CSV file
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/render.sh *)
---

Запусти `${CLAUDE_SKILL_DIR}/scripts/render.sh <csv-file>` і покажи шлях до PNG.

django-migrations/
├── SKILL.md              # огляд і навігація — до 500 рядків
├── checklist.md          # читається, коли треба перевірити міграцію
├── reference/
│   ├── zero-downtime.md  # патерни без простою
│   └── data-migrations.md
└── scripts/
    └── check_migrations.sh   # виконується, код у контекст не потрапляє

• SKILL.md — це зміст, а не енциклопедія. Тримайте до ~500 рядків, решту виносьте у файли
• Посилання на один рівень: усі файли — прямо з SKILL.md. Ланцюжки «A → B → C» Claude може дочитати лише частково
• Файли довші за ~100 рядків починайте зі змісту: навіть при частковому читанні Claude побачить, що в них є
• Явно кажіть, що робити з файлом: «запусти scripts/check.sh» (виконати) чи «див. scripts/check.sh, як рахується…» (прочитати)
• Скрипт надійніший за згенерований код: він детермінований, не витрачає токени на код, дає однаковий результат усім
• Скрипти мають самі обробляти помилки і писати зрозумілі повідомлення («поле X не знайдено, доступні: …») — Claude виправить вхід за ними
• Лише прямі слеші у шляхах (scripts/run.sh), описові назви файлів (zero-downtime.md, не doc2.md)

## Перевірка міграції

1. Запусти `${CLAUDE_SKILL_DIR}/scripts/check_migrations.sh` — він покаже
   незастосовані та конфліктні міграції.
2. Якщо міграція змінює велику таблицю (> 1 млн рядків) — прочитай
   [reference/zero-downtime.md](reference/zero-downtime.md).
3. Для міграцій з даними — [reference/data-migrations.md](reference/data-migrations.md).
4. Перед завершенням пройди [checklist.md](checklist.md).

• Ручний: повідомлення має починатися з /name. Фраза «зроби /deploy» посеред тексту лише дозволяє Claude запустити скіл, але не запускає його напряму
• Ланцюжок: /write-tests /fix-issue 123 — розгортається до шести скілів підряд (зупиняється на першому fork-скілі)
• disable-model-invocation — для дій з наслідками: деплой, реліз, міграції на проді, розсилки
• user-invocable: false — для фонових знань (конвенції API, схема БД), які не мають сенсу як команда

Дозволи на скіли

{
  "permissions": {
    "allow": ["Skill(commit)", "Skill(review-pr *)"],
    "deny":  ["Skill(deploy *)"]          // "Skill" без дужок — заборонити всі
  },
  "skillOverrides": {
    "legacy-context": "name-only",        // у списку без опису — економить бюджет
    "deploy": "off"                       // повністю сховати
  }
}

skillOverrides зручний для скілів у спільному репозиторії: можна приглушити чужий скіл локально, не редагуючи SKILL.md. Меню /skills записує ці значення в .claude/settings.local.json.

З context: fork текст скілу стає промптом нового субагента. Субагент не бачить історії розмови, працює у власному контексті й повертає лише підсумок. Ідеально для «брудних» задач: дослідження коду, аудиту, масового читання логів.

---
name: deep-research
description: Researches a topic in the codebase thoroughly and reports findings with file references. Use when the user asks how something works across many files.
context: fork
agent: Explore          # read-only субагент
model: haiku            # дешево для масового читання
background: false       # чекати результат, а не працювати у фоні
---

Дослідж $ARGUMENTS:
1. Знайди релевантні файли через Glob і Grep
2. Прочитай і проаналізуй код
3. Поверни підсумок до 300 слів з посиланнями файл:рядок

• За замовчуванням fork працює у фоні; background: false — чекати результат. У -p, SDK і запланованих задачах завжди чекає
• Фоновий fork має вужчий набір інструментів; якщо їх бракує — background: false
• Зміни файлів з фонового fork не відкочуються через /rewind
• Потрібна конкретна задача: скіл з самими «правилами» без завдання у fork-режимі нічого не поверне

Claude обирає скіл лише за описом — тіло він ще не бачив. Поганий опис = скіл, який ніколи не спрацює, або спрацьовує невчасно.

1. Що робить + коли вживати. Перше речення — дія, друге — «Use when …» з тригерами
2. Третя особа: «Generates…», а не «I can help…» чи «You can use…» — опис вбудовується в системний промпт
3. Ключові слова, якими ви реально говорите: «міграція», «migration», «makemigrations», «models.py»
4. Головне — на початку: при великій кількості скілів опис може обрізатися
5. Конкретика замість загальників: не «Helps with documents», а «Fills PDF forms from JSON data»

# ✗ занадто загально — Claude не зрозуміє, коли це потрібно
description: Helps with Django

# ✗ перша особа, без тригерів
description: I can review your code

# ✓ дія + тригери + ключові слова
description: >
  Reviews Django migrations for data loss, locking and zero-downtime issues.
  Use when creating or editing files in */migrations/*, running makemigrations,
  or when the user asks whether a migration is safe to deploy.

Назва скілу

Коротка, конкретна, у дієслівній формі або як іменникова фраза: reviewing-migrations, release-notes, fix-bug. Уникайте helper, utils, tools, docs — і однакового стилю дотримуйтеся в усій бібліотеці скілів.

1. /commit — ручний скіл з динамічним контекстом

---
name: commit
description: Creates a Conventional Commit from staged changes. Use when the user asks to commit.
disable-model-invocation: true
allowed-tools: Bash(git commit *) Bash(git status *)
model: haiku
effort: low
---

## Staged зміни

!`git diff --staged --stat`

!`git diff --staged`

## Правила

- Формат: `type(scope): опис` англійською, до 72 символів
- type: feat | fix | refactor | chore | docs | test
- scope — Django-апка або Vue-модуль (orders, billing, ui)
- Тіло коміту — що і навіщо, не як
- Якщо staged порожній — скажи про це і нічого не роби
- Ніколи не додавай файли самостійно і не пуш

> /commit
  1. Claude Code бачить /commit на початку → запускає скіл напряму
  2. Виконує git diff --staged --stat і git diff --staged → вивід у текст скілу
  3. Хід переходить на haiku з effort low — дешево для механічної задачі
  4. Claude пише повідомлення і викликає Bash(git commit -m "feat(orders): add discount field")
     → без запиту дозволу, бо команда в allowed-tools
  5. На вашому наступному повідомленні дозвіл знімається

2. Конвенції API — фонові знання, які Claude підтягує сам

---
name: drf-api-conventions
description: Team conventions for Django REST Framework APIs - URL naming, serializers, pagination, error format, permissions. Use when creating or changing DRF views, serializers, urls or API tests.
user-invocable: false
paths: ["**/api/**", "**/serializers.py", "**/views.py", "**/urls.py"]
---

## URL
- Множина, kebab-case: `/api/v1/order-items/`
- Вкладеність не глибше одного рівня

## Серіалізатори
- Окремі `*ReadSerializer` і `*WriteSerializer`, якщо поля відрізняються
- Ніколи `fields = "__all__"`

## Помилки
Формат: `{"error": {"code": "...", "message": "...", "fields": {...}}}`
Див. [errors.md](errors.md) для повного списку кодів.

Цей скіл не з’являється в меню /, але коли ви просите «додай ендпоінт для знижок», Claude працює з views.py, бачить відповідний опис і завантажує конвенції до того, як напише код. Поле paths не дає йому спрацьовувати на задачах у фронтенді.

3. Міграції — скіл зі скриптом і чеклистом

---
name: django-migrations
description: Creates and reviews Django migrations safely - zero-downtime patterns, data migrations, lock risks. Use when models.py changes, when running makemigrations, or when the user asks if a migration is safe.
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/check_migrations.sh *) Bash(python manage.py makemigrations *)
---

## Порядок

1. `python manage.py makemigrations <app>` — ніколи без назви апки
2. Запусти `${CLAUDE_SKILL_DIR}/scripts/check_migrations.sh <app>`
3. Якщо скрипт показує `LARGE_TABLE` — прочитай [reference/zero-downtime.md](reference/zero-downtime.md)
   і розбий міграцію на кроки (nullable → backfill → constraint)
4. Пройди [checklist.md](checklist.md) і відпиши результат по кожному пункту

## Заборонено
- `RunSQL` без `reverse_sql`
- Перейменування колонки однією міграцією на таблицях > 1 млн рядків

1. Claude редагує orders/models.py
2. Запит і файл збігаються з описом → Skill(django-migrations)
3. makemigrations orders → check_migrations.sh orders
     вивід скрипта: LARGE_TABLE orders_order (4.2M rows)
4. Читає лише reference/zero-downtime.md (data-migrations.md не потрібен — 0 токенів)
5. Розбиває на 3 міграції, проходить checklist.md, звітує по кожному пункту

4. Vue-компоненти — скіл з власним hook

---
name: vue-component
description: Creates Vue 3 components following team structure - script setup, TypeScript props, Pinia, tests. Use when creating or refactoring .vue files.
hooks:
  PostToolUse:
    - matcher: "Edit|Write"
      hooks:
        - type: command
          command: "jq -r '.tool_input.file_path' | grep -E '[.]vue$' | xargs -r npx eslint --fix"
---

- `<script setup lang="ts">`, props через `defineProps<{...}>()`
- Стан між сторінками — лише Pinia store, не provide/inject
- Поруч з компонентом — `ComponentName.spec.ts` (Vitest + Testing Library)
- Шаблон структури — [template.vue](template.vue)

Інструкції про стиль Claude застосовує з розсудом, а от eslint --fix після кожного редагування .vue виконує hook — гарантовано, з моменту виклику скілу до кінця сесії.

5. Дослідження у форку — /deep-research

Скіл з розділу context: fork: /deep-research як рахується знижка в checkout запускає read-only субагента на Haiku. Він може прочитати 40 файлів, а в основну розмову повернеться лише стислий звіт з посиланнями — ваш контекст лишається чистим.

Розробка від оцінок (eval-first)

1. Виконайте задачу без скілу і запишіть, де Claude помилився або чого не знав
2. Складіть 3+ сценарії, що перевіряють саме ці прогалини
3. Напишіть мінімальний скіл, який закриває прогалини, — не більше
4. Порівняйте з базою і доопрацюйте. Тестуйте в свіжій сесії — залишковий контекст маскує дірки в інструкціях
5. Перевірте на всіх моделях, які використовуєте: що достатньо для Opus, може бути замало для Haiku

Найпростіший спосіб — «Claude A пише, Claude B тестує»: в одній сесії разом з Claude формулюєте скіл, у новій сесії даєте реальну задачу і спостерігаєте, що B пропустив; повертаєтесь до A з конкретикою.

Інструменти

Типові проблеми

Поведінкові обмеження

• Скіл не гарантує виконання. Це інструкція для моделі: Claude може не обрати скіл або відійти від нього в довгій сесії. Для обов’язкових правил — hooks і permissions
• allowed-tools не обмежує інструменти — лише знімає запит дозволу, і лише до вашого наступного повідомлення. Обмежує — disallowed-tools
• Файл не перечитується: зміна SKILL.md посеред сесії не впливає на вже завантажений текст
• Fork не бачить розмову: усе потрібне треба передати через аргументи або вставки
• Фоновий fork: вужчий набір інструментів, і його зміни не відкочуються через /rewind
• Без синхронізації між поверхнями: скіли Claude Code, claude.ai і API живуть окремо; у claude.ai кастомні скіли — особисті, без централізованого керування
• Cowork і cloud-сесії не бачать ~/.claude/skills/
• Середовище: у Claude Code скіл має повний доступ до мережі та системи; в API — без мережі і без встановлення пакетів. Глобально ставити пакети зі скілу не варто
• Не пишіть дати-«терміни придатності» («до серпня використовуй старий API») — скіл застаріє непомітно. Застарілі способи — в окремий розділ «Old patterns»

Скіл може наказати Claude запускати команди, читати файли й ходити в мережу. Шкідливий або просто неакуратний скіл — це ризик витоку даних і небажаних змін. Ставтеся до скілів як до залежностей.

Керування на рівні компанії

Корисні посилання