| name | skill-creation-guide |
| description | Step-by-step guide for creating Claude Skills in SKILL.md format. ALWAYS use this skill when user wants to create a new skill, write a SKILL.md file, package a .skill file, add instructions as a skill, or asks how to structure skill instructions. Also triggers for: створити скіл, написати інструкції скіл, як зробити skill, як упакувати skill, формат skill, SKILL.md шаблон, додати скіл. Includes: YAML frontmatter rules, body patterns, evals template, guard script, progressive disclosure, token-efficient structure, and coordination with skill-creator, validation-mesh, semantic-router, continuation-memory. DO NOT use for: governance/версії/затвердження та авторитет пакування (melania-skill-master-administrator); дистрибуція в маркетплейси (skill-marketplace-distribution); легкий лабораторний стандарт ai-lab з мінімальним frontmatter (skill-new); аудит екосистеми (skill-ecosystem-auditor). |
| license | Proprietary |
| metadata | {"version":"1.11.0","author":"Melania (Master Administrator)","category":"skill-governance","created":"2026-05-27T00:00:00.000Z","last_updated":"2026-07-26T00:00:00.000Z"} |
Skill Creation Guide — v1.11.0
Меланія · оновлено 2026-07-19 · Для деталей читай references/full-guide.md
Працює українською за замовчуванням (українською-перша).
🛡️ Протокол Збереження Перед Оновленням (ОБОВ'ЯЗКОВО)
Обов'язковий перед БУДЬ-ЯКОЮ зміною цього скіла. Канонічне джерело (не дублювати тут): melania — секції «🛡️ Протокол Збереження Перед Оновленням» + «Update Workflow» + «Core Rule 10 — Re-Read Before Update».
Стисло: re-read диску → порівняти версії (диск новіший → диск база) → integrity-diff → validation-mesh → safety-compliance-gate (перед пакуванням/публікацією) → backup/snapshot → merge-not-replace → bump+CHANGELOG → показати diff і чекати явного схвалення MA (Закон II).
Core Rules
- Формат файлу: завжди
.md — мінімум токенів, нативний для LLM
- Розмір: SKILL.md < 500 рядків; більше →
references/
- Тригер: description з
ALWAYS use when + синоніми + DO NOT use for
- Тести: 4–6
evals.json кейсів з конкретними assertions
- Decision Gate: спершу онови НАЯВНИЙ скіл; новий створюй ЛИШЕ якщо оновлення неможливе/нелогічне
- Українською-перша: тригери + поведінка за замовчуванням + приклади — українською
Critical Facts
- [C]
description обмежено 1024 символами. Перевищення ліміту блокує збереження SKILL.md — це технічне обмеження платформи, а не рекомендація.
- [C] Пакувальник вирізає
evals/ з .skill-архіву. Інсталяція готового скіла через .skill-файл не переносить тестові кейси — джерело evals потрібно тримати окремо (наприклад, у git).
- [C] Схема evals цієї екосистеми несумісна з офіційною. Тут канон — поля
name+assertions+version, тоді як офіційний skill-creator/schemas.md очікує expectations — формати різні й напряму не конвертуються.
- [C] Дослідження ETH Zurich (138 задач) виміряло шкоду роздутого контексту. Дубльовані/об'ємні контекстні файли знижували success-rate і підвищували вартість більш ніж на 20% (14–22% reasoning-токенів) порівняно з коротким або відсутнім контекстом.
- [C]
SKILL.md має лежати в корені .skill-архіву. Вкладена структура на кшталт name/name/SKILL.md не відповідає очікуваному формату пакета.
Spec-driven: spec → evals → skill
Перед НОВИМ скілом (або нетривіальною правкою) спершу — компактний spec, потім з нього еволи, і лише тоді текст навички:
- Spec (кілька рядків): мета · тригери (
ALWAYS use when / DO NOT use for) · критерії приймання · координація. Зберігай у references/spec.md.
- Evals зі spec — кожен критерій приймання → eval-кейс (spec = джерело тестів).
- TDD — далі RED→GREEN→REFACTOR (нижче). Spec → evals → skill.
Spec — легка домовленість про межі, не бюрократія: не дає скілу «розповзтися» і робить еволи похідними від наміру.
TDD для навичок (Iron Law)
Жодної навички без failing-тесту спершу. Стосується і НОВИХ навичок, і ПРАВОК наявних.
Створення навички = TDD над документацією процесу:
- RED — спершу напиши eval-кейс на бажану поведінку й переконайся, що baseline (без навички/без правки) його провалює. Якщо тест проходить без змін — навичка не потрібна.
- GREEN — додай мінімальний текст навички, щоб тест пройшов.
- REFACTOR — закрий лазівки; додай кейси на обхід.
Таблиця раціоналізацій (антиобхід): кожне типове виправдання агента під тиском фіксуй і явно забороняй.
| Виправдання | Реальність |
|---|
| «Зміна дрібна, тест зайвий» | Дрібні зміни ламають мовчки — тест обов'язковий |
| «Бракує часу на eval» | Без eval зміна неперевірна → не застосовується |
| «Очевидно ж працює» | «Очевидно» ≠ перевірено; додай кейс |
Порушення букви правил = порушення їхнього духу.
Decision Gate — оновити наявний чи створити новий?
| Ситуація | ✓ Дія |
|---|
| Зміна вкладається в наявний скіл без зламу призначення | онови наявний (diff + bump версії) |
| Повторюваний фікс (≥2 рази в різних скілах) | підніми в gate ТУТ + у melania + додай eval |
| Потреба логічно не лягає в жоден наявний скіл | створи новий |
| Скіл став би >500 рядків або суперечливим | розділи / винеси в references/ |
| Функція мертва або дубльована | deprecation з планом міграції (не різке видалення) |
Доказ прогалини перед «новий скіл»: прожени coverage-скан реєстру (grep ключових концептів по всіх SKILL.md), щоб ДОВЕСТИ, що жоден наявний не покриває. Створюй новий лише якщо скан це підтвердив — інакше онови наявний.
Єдине канонічне джерело + тонкі посилання (DRY)
Будь-яке правило/контекст живе в ОДНОМУ канонічному місці; решта — посилаються одним рядком, не копіюють (узагальнення конвенції безпеки нижче).
Для контекстних файлів проєкту:
AGENTS.md — єдине канонічне джерело інструкцій агентам.CLAUDE.md — тонкий адаптер: import @AGENTS.md на початку + лише Claude-специфіка. Не дублюй вміст.
Доказ (чому стисло й без дублів): роздуті/дубльовані контекстні файли вимірювано шкодять — дослідження ETH Zurich (138 задач): нижчий success-rate і +>20% вартості (+14–22% reasoning-токенів) проти короткого/відсутнього контексту. Канонічний файл — коротким і писаним вручну.
Безпековий випадок цього ж правила — у наступній секції (правила в safety-compliance-gate).
Безпека та комплаєнс — централізовано (не дублювати)
Усі безпекові + IP/публікаційні правила живуть у safety-compliance-gate, не в кожному скілі.
Конвенція тонкого покажчика: будь-який скіл, що (а) публікується, (б) названий за чужим продуктом/брендом, або (в) працює з конекторами/зовнішнім входом — несе ОДИН рядок:
⚖️ Безпека та комплаєнс — safety-compliance-gate (обов'язково перед пакуванням/публікацією/комерціалізацією).
Ніколи не копіюй повний набір правил гейта в скіл (порушення неповторності + токени). Enforcement — у вузлі (melania пакування + чеклист пакування), не в кожному скілі.
Мова — українською-перша
Кожен новий або оновлений скіл: українські тригери в description, поведінка й
приклади українською за замовчуванням; перемикання мови — лише слідом за користувачем.
Узагальнене формулювання: пиши скіл для загальної аудиторії — без особистих імен/PII конкретного користувача; припускай можливу публічну дистрибуцію, навіть якщо створюєш «для себе».
Ліміти платформи (обовʼязково)
description ≤ 1024 символи (інакше збереження блокується). Пиши тригери стисло; деталі — у тіло/references. Канонічний skill_guard.py має асертити це автоматично (поряд із <500 рядків) — самоперевірка перед пакуванням.SKILL.md у КОРЕНІ .skill-архіву (не name/name/SKILL.md). Пакуй вмістом теки: cd skill-dir && zip -r ../skill.skill .- SKILL.md < 500 рядків; надлишок →
references/.
compatibility: — вкажи ПЕРЕВІРЕНІ платформи. Формати скілів конвергують (Codex/Cursor переймають), але портативність НЕ безшовна — не припускай ідентичну поведінку; познач, що реально звірено per-platform.
Оркестрація + економія (для кожного скіла)
- Будь-який скіл співпрацює з будь-яким, включно з майбутніми — не зашивай фіксований перелік партнерів; покладайся на динамічне виявлення (
semantic-router).
- Активуй мінімальний достатній набір скілів: лише потрібні, у потрібній кількості. Не запускай усі підряд (економія токенів), але й не жертвуй якістю.
- У секції координації перелічуй партнерів як приклади, а не як вичерпний/закритий список.
Лінза дизайну — три примітиви (Tool / Resource / Prompt)
Класифікуй частини нового скіла за примітивами MCP (свідомий дизайн + progressive disclosure):
- Tool-like — дія/функція (наказова інструкція, що робить). → тіло SKILL.md, кроки.
- Resource-like — read-only контекст/довідка, вантажиться на вимогу. →
references/.
- Prompt-like — повторюваний workflow-шаблон із тригерами. → сам скіл +
description (ALWAYS use when).
Гігієна шаблонів (template hygiene)
- Ясні дієслівні імена дій/кроків (
summarize-errors, не get-summarized-error-log-output).
- Валідуй обов'язкові аргументи наперед (не в середині workflow).
- Не ховай workflow-логіку в описах — логіка у тілі/references, опис лише тригерить.
Структура файлів
my-skill/
├── SKILL.md ← обов'язково (YAML frontmatter + інструкції)
├── evals/
│ └── evals.json ← рекомендовано (тест-кейси)
├── scripts/
│ └── skill_guard.py ← опціонально (захист від регресій)
└── references/
└── full-guide.md ← деталі якщо SKILL.md > 300 рядків
YAML Frontmatter — обов'язкові поля
---
name: my-skill-name
description: "[ЩО робить]. ALWAYS use when [умови]. Also triggers for: [синоніми]. DO NOT use for [виключення]."
---
Правила description:
- Max 1024 символи, без
< >
- Бути "pushy" — Claude схильний до undertriggering
- Включати синоніми і обидві мови (укр/англ)
Тіло SKILL.md — базовий шаблон
# Назва — vX
## Core Rule
[Найважливіше одним реченням]
---
## Step 1 — [Дія]
[Інструкції в наказовому способі: "Read", "Check", "Never"]
---
## Behavior
| Ситуація | ✓ Дія | ✗ Ніколи |
|----------|-------|----------|
| edge case | правильна дія | заборонена дія |
evals.json — мінімальний шаблон
{
"skill_name": "my-skill",
"version": "1.0.0",
"evals": [
{
"id": 1,
"name": "happy-path",
"prompt": "Реальна фраза від користувача",
"expected_output": "Що має статись",
"assertions": [
"Конкретна перевірювана умова",
"Does NOT say/do X",
"Виконує Y без питань"
]
}
]
}
Канон evals цієї екосистеми: саме name + assertions + version (як вище), а НЕ expectations офіційного skill-creator/schemas.md — формати різні. Evals тут — для ручного прогону (Claude сам виконує промпт і звіряє assertions).
Evals НЕ потрапляють у .skill: пакувальник виключає evals/ → інсталяція через .skill НЕ переносить тести. Тримати source-копії evals окремо (Claude Code / git), інакше набір губиться при кожному install.
Skills для створення нового Skill
| Skill | Коли використати |
|---|
skill-creator | Основний процес: draft → test → eval → package |
melania-skill-master-administrator | Governance: версії, CHANGELOG, Три Закони, дозвіл MA |
skill-ecosystem-auditor | Аудит усієї екосистеми → пропозиції оновлень наявних/нових скілів |
validation-mesh | Перевірити якість готового SKILL.md |
semantic-router | Визначити які Skills координувати |
continuation-memory | Зберегти стан якщо сесія > 20 обмінів |
Workflow:
semantic-router → skill-creator → validation-mesh → package
References
Читай references/full-guide.md КОЛИ:
- Потрібен повний шаблон guard script
- Потрібна детальна карта патернів (cascade, decision engine, variants)
- Потрібна таблиця антипатернів (11 помилок)
- Потрібні всі 4 copy-paste шаблони (A, B, C, D)
Anti-Patterns (Найчастіші Помилки)
| Anti-Pattern | Чому погано | Як правильно |
|---|
| SKILL.md > 500 рядків | LLM читає все → марнує токени | Переноси в references/ |
Немає DO NOT use for | Зайві спрацювання | Завжди додавай виключення |
| Хардкодений список скілів | Застаріє при додаванні нових | Динамічне виявлення |
| Опис без конкретних тригерів | Низький trigger rate | 3–5 точних фраз у description |
Немає metadata.version | Не можна відслідкувати зміни | Семантична версія обов'язкова |
| Один гігантський скіл | Всі завдання → один скіл | Мікроядро + модулі |
| Evals без assertions | Тест завжди проходить | Конкретні checkable assertions |
Checklist Перед Пакуванням
□ SKILL.md < 500 рядків?
□ description ≤ 1024 символи?
□ metadata.version bump?
□ metadata.last_updated = сьогодні?
□ UA-first директива в header?
□ evals/evals.json з ≥ 4 тестами?
□ SKILL.md у корені архіву (не вкладена папка)?
□ validation-mesh перевірив?
□ Snapshot зроблено?
□ CHANGELOG.md оновлено?
□ safety-compliance-gate пройдено? (IP/trademark, дисклеймер, no-logos, ліцензія, безпекова постава — для будь-якого скіла, що публікується / названий за чужим продуктом)
Description Optimization
Опис = єдиний механізм тригерингу. Оптимізуй агресивно:
- ALWAYS use when → конкретний список (не "коли треба X")
- Also trigger for → синоніми, помилкові написання, українські/англійські варіанти
- DO NOT use for → важливе! Прибирає false positives
- Обмеження: ≤ 1024 символи → кожне слово на вазі золота
📎 Advanced Patterns (v4)
Read references/composition.md WHEN you need: single responsibility, reference organization, multi-domain skills, coordination, eval/guard design.
Load only on demand — not proactively.
Зміни
⚠ Історична примітка: окремі ранні записи нижче мають дубльовані номери версій (артефакт злиттів). Усі записи збережено; нумерацію НЕ переписано без верифікації джерел.
-
v1.11.0 (2026-07-26) — Секція Critical Facts: фактичні твердження скіла винесено окремо й протеговано [C] за Core Rule 14 (claim-evidence). Лише додавання.
-
v1.10.0 (2026-07-19) — Хвиля 1 Self-Dev (аудит 2026-07-18): (A) P1 №26/№32 — +DO NOT-межі в description (governance → melania-SMA; маркетплейс → skill-marketplace-distribution; лаб-стандарт ai-lab → skill-new; аудит → skill-ecosystem-auditor) — дзеркально до SMA v2.16.0; закриває відсутність DO NOT, яку вимагає власний Core Rule 3. (B) №30 — синхронізовано банер (v1.1→v1.10.0) і last_updated (2026-06-13→2026-07-19) з frontmatter/changelog. Лише уточнення меж і синхронізація.
-
v1.9.3 (2026-06-26) — Stage 3: S-3 +власні evals/ (5, канон-схема). S-2 примітка про дубль v1.4.0. Додавання + примітка.
-
v1.9.2 (2026-06-26) — GSRE-інтеграція: +канон-нота схеми evals (name+assertions+version, НЕ expectations офіційного skill-creator) + правило «evals не потрапляють у .skill → тримати source окремо» після шаблону evals. Лише додавання.
-
v1.9.1 (2026-06-15) — DRY: «Протокол Збереження» → тонкий міст на канон у melania (де-дублювання + усунення 8-варіантного дрейфу). Поведінка незмінна — гейт той самий, джерело єдине.
-
v1.9.0 (2026-06-14) — P-U6 (harvest-2026): рядок про compatibility: field + portability-caveat (формати Codex/Cursor конвергують, портативність не безшовна). Частину «description = activation logic» НЕ додано — вже повністю покрита секцією Description Optimization.
-
v1.7.0 (2026-06-13) — A2: канонічне джерело + тонкі посилання (AGENTS.md canonical / CLAUDE.md адаптер, доказ ETH Zurich); A3: spec-driven (spec → evals → skill). (Реструктуризація CORE+nodes, Фаза A — A2+A3.)
-
v1.1.0 (2026-06-02) — додано Decision Gate (оновити vs створити), правило «українською-перша», повний metadata frontmatter, власні evals/, рядки melania + skill-ecosystem-auditor у таблиці координації. (аудит P-05/P-06/P-02/P-07)
-
v1.0 — початкова версія.
-
v1.4.0 (2026-06-02) — anti-patterns catalog, pre-packaging checklist, description optimization guide.
