Як створити Agent Skill: SKILL.md, тести й безпечний rollout

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

Мінімальний skill — папка з файлом SKILL.md. У YAML frontmatter обов'язкові name і description; Markdown body містить інструкції. Scripts, references та assets додавайте лише коли вони дають потрібний код, детальну довідку або шаблон. Skill описує метод роботи, але не видає business authority: filesystem, shell, network, MCP tools і зовнішні записи все одно обмежують client, sandbox, policy та цільова система.

• Одна місія → один перевірюваний результат.
• Description → коли активувати й коли не активувати.
• Body → кроки, перевірки, stop conditions та формат відповіді.
• References/scripts → лише матеріал, який потрібен не в кожному run.
• Authority → окрема policy, а не текстова обіцянка в SKILL.md.

Запишіть mission card: користувач, trigger, inputs, outputs, dependencies, дозволені й заборонені дії, failure state, evidence та owner. Вузький release-review skill може приймати diff і policy, а повертати verdict із посиланнями на порушені правила. Формулювання «допомагає з розробкою» не дає ні стабільного trigger, ні acceptance test. Межа також має пояснювати, які суміжні задачі належать іншому skill або звичайній розмові.

Виділіть deterministic steps. Schema validation, пошук точного файла, арифметика та policy checks краще виконувати кодом або інструментом, а не просити модель імпровізувати. Модель корисна для зіставлення контексту, аналізу неоднозначності й підготовки пояснення. Якщо процедура потребує live data або side effect, опишіть потрібну capability, але підключайте її через окремий tool чи MCP contract із server-side authorization.

За поточною специфікацією name має збігатися з назвою батьківської папки, містити лише lowercase літери, цифри й дефіси, не починатися або закінчуватися дефісом і не містити подвійного дефіса. Description має пояснювати і capability, і умови використання. License, compatibility та metadata є опційними; allowed-tools позначено experimental, тому не покладайтеся на нього як на переносимий security control.

Побудуйте activation table до шліфування тексту: п'ять явних позитивних запитів, п'ять близьких негативних і п'ять неоднозначних. Додайте до description слова, які розрізняють ці групи, але не перетворюйте його на список усіх можливих фраз. Після зміни description повторіть suite: metadata завантажується на discovery stage, тому поганий опис може зламати skill ще до читання body.

• Positive trigger → skill потрібен і має завантажитися.
• Near-negative → тема схожа, але місія інша.
• Ambiguous → агент уточнює замість самовільної дії.
• Collision → два skills претендують на один запит; межу треба звузити.

Після активації весь SKILL.md конкурує за context window із запитом, історією та tool results. Тримайте в body лише завжди потрібний маршрут: prerequisites, послідовність, decision points, перевірки, failure handling і output contract. Специфікація рекомендує SKILL.md менш як 500 рядків, а creation guidance — орієнтир до 5 000 tokens. Це не ціль заповнення: коротший точний файл кращий за енциклопедію.

Виносьте довгі API notes, policy tables і domain examples у focused references та явно пишіть, коли їх читати. Не давайте абстрактне «дивись references/»: назвіть файл і trigger. Scripts повинні мати документовані dependencies, deterministic inputs, зрозумілі помилки й безпечні defaults. Assets зберігають шаблони чи output scaffolds; вони не повинні приховувати executable instructions від reviewer.

Інструкція має розрізняти read, propose і execute. Перед записом визначте source of truth, точний target, authority check, approval boundary та postcondition. Для batch або destructive operation спочатку створіть structured plan, звірте його з джерелом істини, а вже потім виконуйте. Невідомий target, відсутній credential, суперечлива policy або непідтверджений стан повинні завершуватися явним блокером, а не правдоподібною здогадкою.

Опишіть receipt без секретів: input revision, skill digest, client/model, завантажені references, tool calls, policy verdict, validation result і фінальний артефакт. Timeout після можливої зовнішньої дії переводить операцію в unknown: спочатку read-back і reconciliation, потім рішення про retry. SKILL.md може нагадати цей порядок, але idempotency, permissions і kill switch мають примусово реалізовуватися нижчим execution layer.

Static validation перевіряє frontmatter і структуру, але не поведінку. Запустіть три suites. Discovery suite вимірює правильне спрацювання та false activation. Instruction suite перевіряє, чи агент прочитав потрібний reference, зберіг constraints і зупинився на забороненій дії. Outcome suite порівнює artifact або authoritative final state з acceptance criteria. Гарна фінальна відповідь не компенсує пропущений check або зайвий side effect у trajectory.

Fixtures мають охоплювати happy path, missing input, stale reference, malformed file, unavailable tool, prompt injection усередині документа, permission denial, timeout і client without an optional feature. Повторюйте stochastic runs і зберігайте failures, а не лише найкращий приклад. Model grader може оцінити ясність, але filename, schema, test result, дозволи та final state перевіряйте deterministic assertions.

• Lint → format, name, links і required files.
• Activation → positive, negative, ambiguous і collision prompts.
• Execution → trajectory, tool envelope та failure transitions.
• Outcome → артефакт, citations і authoritative state.
• Regression → та сама suite після зміни skill, client, model або tool.

Сумісність із форматом не гарантує однакової поведінки. Clients відрізняються discovery paths, metadata support, tool names, sandbox, approval UX і context compaction. Створіть portability manifest із skill digest, required files, expected tools, environment assumptions, forbidden effects, fixtures та підтриманими client/version. Запустіть один corpus у кожному цільовому harness і порівнюйте verified outcome, а не стиль тексту.

Для стороннього skill фіксуйте source URL, license, reviewed commit або digest, maintainer, dependencies, scripts, network destinations, requested credentials, data classes і expiry. Review diff при кожному update. Unreviewed package запускайте без секретів у disposable sandbox; production promotion потребує pinned version, code review, malware/dependency checks, bounded permissions і власної eval suite. Популярність репозиторію не є security evidence.

Promotion рухається від local lint і offline fixtures до disposable sandbox, read-only canary та лише потім до bounded writes з approval. Release record містить owner, mission, digest, client/model, dependencies, permissions, eval revision, results, reviewer, rollout scope і expiry. Спостерігайте activation rate за slices, false activations, constraint violations, tool errors, verified task success, human corrections і incident signals без копіювання sensitive inputs у telemetry.

Rollback повинен вимикати discovery entry або повертати known-good digest незалежно від того, чи агент може прочитати нову інструкцію. Після side effect окремо reconcile-іть зовнішній стан; повернення Markdown не скасовує вже виконану дію. Retire skill, коли owner зник, procedure змінилася, залежність більше не підтримується або інший skill канонічно володіє intent. Archive зберігає evidence, але retired version не лишається активним випадково.