skill-creation-guide

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

1. Формат файлу: завжди .md — мінімум токенів, нативний для LLM
2. Розмір: SKILL.md < 500 рядків; більше → references/
3. Тригер: description з ALWAYS use when + синоніми + DO NOT use for
4. Тести: 4–6 evals.json кейсів з конкретними assertions
5. Decision Gate: спершу онови НАЯВНИЙ скіл; новий створюй ЛИШЕ якщо оновлення неможливе/нелогічне
6. Українською-перша: тригери + поведінка за замовчуванням + приклади — українською

---

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, потім з нього еволи, і лише тоді текст навички:

1. Spec (кілька рядків): мета · тригери (ALWAYS use when / DO NOT use for) · критерії приймання · координація. Зберігай у references/spec.md.
2. Evals зі spec — кожен критерій приймання → eval-кейс (spec = джерело тестів).
3. TDD — далі RED→GREEN→REFACTOR (нижче). Spec → evals → skill.

Spec — легка домовленість про межі, не бюрократія: не дає скілу «розповзтися» і робить еволи похідними від наміру.

TDD для навичок (Iron Law)

Жодної навички без failing-тесту спершу. Стосується і НОВИХ навичок, і ПРАВОК наявних. Створення навички = TDD над документацією процесу:

1. RED — спершу напиши eval-кейс на бажану поведінку й переконайся, що baseline (без навички/без правки) його провалює. Якщо тест проходить без змін — навичка не потрібна.
2. GREEN — додай мінімальний текст навички, щоб тест пройшов.
3. 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        # kebab-case, max 64 символи
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

Опис = єдиний механізм тригерингу. Оптимізуй агресивно:

1. ALWAYS use when → конкретний список (не "коли треба X")
2. Also trigger for → синоніми, помилкові написання, українські/англійські варіанти
3. DO NOT use for → важливе! Прибирає false positives
4. Обмеження: ≤ 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.