Исходный пост опубликован AI Guides в X. Вложенная статья: How to Create the Right Skill for Your AI Agent.

Ваш агент продолжает ошибаться, а вы продолжаете переписывать prompt. Исправление находится на три слоя выше того места, куда вы смотрите.

Карта ниже разбирает четыре слоя AI engineering: Prompt, Context, Harness и Loop. Каждый слой оборачивает предыдущий, а большинство разработчиков так и не выходят за пределы первого.

Как создать правильный skill для вашего AI-агента

Вашему AI-агенту не нужен ещё один prompt. Ему нужен skill.

Prompt — это одноразовая инструкция. Вы вводите её, агент выполняет, а к следующей сессии вся беседа исчезает. Каждый раз вы начинаете с нуля.

Skill — это переиспользуемый workflow-файл, который лежит в вашем проекте. Вы пишете его один раз. Агент загружает его каждый раз, когда возникает соответствующая задача, и снова и снова следует одному и тому же определённому процессу.

Цифры это подтверждают. SkillsBench, первый peer-reviewed benchmark для agent skills, опубликованный в феврале 2026 года и включающий 84 задачи из 11 доменов, показал, что curated skills повышают средний pass rate агентов на 16,2 процентного пункта. Self-generated skills, где агент пытался писать skill сам, не показали надёжного улучшения.

Качество skill — ключевая переменная. По мере того как агенты становятся способнее, люди, умеющие писать хорошие skills, всё сильнее отрываются от тех, кто просто вводит инструкции в чат и надеется на лучшее.

Формат skill больше не является функцией одного вендора. Anthropic выпустила спецификацию Agent Skills как открытый стандарт в декабре 2025 года на agentskills.io. В течение трёх месяцев OpenAI Codex, Google Gemini CLI, GitHub Copilot, Cursor, VS Code и десятки других инструментов приняли тот же формат.

По состоянию на середину 2026 года более 40 продуктов поддерживают стандарт SKILL.md. Напишите skill один раз — и он будет работать во всех основных coding agents без изменений.

В этом гайде разобрано всё: что такое skill, как написать его с нуля, как избежать security traps в skills из сообщества и что меняется в повседневной работе, когда вы начинаете их создавать.

Сохраните это. Вы будете возвращаться к этому всю неделю.

Что skill представляет собой на самом деле

Skill — это папка. Внутри неё находится файл SKILL.md. У этого файла две части: короткий header с именем и описанием skill, написанный в YAML, и body с фактическими инструкциями, которым должен следовать агент, написанный обычным Markdown.

my-skill/
├── SKILL.md          # Обязательно: metadata + instructions
├── scripts/          # Опционально: исполняемый код
├── references/       # Опционально: документация
└── assets/           # Опционально: шаблоны, ресурсы

Файл SKILL.md — единственный обязательный компонент. Всё остальное опционально и загружается только тогда, когда это нужно агенту.

Как skills загружаются: progressive disclosure

Ваш агент не читает каждый установленный skill в начале каждой сессии. Это забило бы context window и сделало агента глупее. Вместо этого skills загружаются в три уровня:

Tier 1: только name и description. При старте сессии агент читает только имя и однострочное описание каждого установленного skill. Это стоит 30–50 токенов на skill. Достаточно, чтобы знать, что доступно, и не сжигать контекст.

Tier 2: полные инструкции. Когда агент решает, что skill релевантен текущей задаче, он подтягивает полный body SKILL.md в контекст. Теперь у него есть полный workflow.

Tier 3: reference files. Если инструкции ссылаются на внешние файлы — scripts, templates, documentation — агент загружает их только тогда, когда доходит до шага, которому они нужны.

Именно благодаря этой трёхуровневой системе можно установить десятки skills без замедления агента. Он загружает минимум того, что нужно, и только тогда, когда это нужно.

Skill vs. Prompt vs. Config File

Эти три вещи постоянно путают. Разница довольно проста.

Prompt — это одноразовая инструкция, которую вы вводите в чат: «Проверь этот код на баги». После сессии она исчезает.

Config file, например CLAUDE.md, AGENTS.md или .cursorrules, — это набор инструкций, которые всегда отправляются агенту в начале каждой сессии: «Всегда используй TypeScript. Следуй нашим naming conventions. Никогда не push в main».

Это always-on rules, которые применяются ко всему, что делает агент.

Skill находится между ними. Он не always-on — иначе это тратило бы контекст — и не одноразовый — иначе вы зря тратили бы усилия на его написание. Он подтягивается по запросу, когда задача совпадает.

Агент читает описание и решает: «Эта задача подходит под этот skill». Затем он загружает полные инструкции и следует определённому workflow.

Технический термин для этого различия — push vs. pull. Config files push инструкции агенту независимо от того, нужны они или нет. Skills позволяют агенту pull инструкции, когда он распознаёт нужный момент.

Два типа skills

User-invoked skills — это skills, которые вы запускаете сами. Вы вводите /grill-me или /tdd, и агент начинает workflow. Они нужны для orchestration — чтобы начать определённый процесс в определённый момент.

Model-invoked skills — это skills, к которым агент может обратиться самостоятельно, когда задача подходит. Вы не вводите команду.

Агент читает описание skill, распознаёт совпадение и подтягивает его. Такие skills нужны для discipline — чтобы встроить хорошие практики, которые срабатывают без прямой просьбы.

Оба типа используют один и тот же формат SKILL.md. Разница в том, как они запускаются, а не в том, как они устроены.

Cross-platform по умолчанию

До стандарта Agent Skills у каждого инструмента был собственный формат кастомизации. Cursor использовал .cursorrules. Claude Code использовал /commands. Copilot использовал instruction files.

Если вы меняли инструмент, ваши кастомизации не переносились.

Открытый стандарт SKILL.md изменил это. Skill, написанный для Claude Code, работает в Codex, Gemini CLI, Cursor, Copilot и VS Code без изменений. Список совместимых инструментов теперь превышает 40 продуктов: от terminal agents до полноценных IDE и cloud-based autonomous systems.

Вы пишете skill один раз. Он работает везде.

Начинайте с проблемы, а не с инструмента

Не садитесь «писать skill». Садитесь исправлять failure mode.

AI-агенты ошибаются предсказуемым образом. Каждый разработчик, который месяц работал с coding agent, сталкивался с одними и теми же четырьмя проблемами. Понимание того, какая из них обходится вам дороже всего, подсказывает, какой skill стоит создать первым.

Failure Mode 1: агент сделал не то, что вы хотели

Это самый частый случай. Вы описываете, чего хотите. Агент принимает задачу и начинает строить.

Вы возвращаетесь и понимаете, что он понял что-то другое.

Корневая причина — misalignment. Вы и агент не пришли к общему пониманию проблемы до того, как прыгнули в код.

Frederick P. Brooks описывал это в The Design of Design как «design tree». В каждом дизайне есть ветви решений, которые нужно разрешить до начала строительства. Пропустите эти ветви — и вы строите на предположениях.

Исправление — grilling skill. Skill, который говорит агенту: «Перед тем как писать код, проведи интервью. Задай подробные вопросы по каждому аспекту плана. Пройди по каждой ветви decision tree. Не останавливайся, пока мы оба не согласимся, что именно строим».

Самая популярная версия этого паттерна состоит всего из трёх предложений. Она работает в Claude Code, Codex и Gemini CLI. Пользователи сообщают о сессиях из 16–50 вопросов до того, как агент начинает писать код.

Звучит медленно. Но one-shot success rate после нормальной grilling session намного выше, чем альтернатива: начать кодить и исправлять misalignment уже после нанесённого ущерба.

Failure Mode 2: агент слишком многословен

Агенты попадают в ваш проект и по ходу дела разбираются с локальным жаргоном. Ваша codebase называет что-то «materialization cascade», но агент не знает этот термин и пишет: «процесс, при котором урок внутри секции курса становится реальным с учётом места в файловой системе». Это 24 слова вместо двух.

Проблема накапливается. В каждой сессии агент заново открывает ваш vocabulary. Он тратит токены, пересказывая то, что уже выяснил в прошлый раз, а длинные описания вытесняют полезную работу.

Исправление — shared language skill. Skill, который поддерживает glossary file, часто называемый CONTEXT.md, в вашем проекте. Агент читает его в начале каждой сессии.

Переменные, функции и файлы получают согласованные имена. Агент тратит меньше токенов на размышления, потому что получает доступ к более плотному языку.

Eric Evans называл это «ubiquitous language» в Domain-Driven Design ещё в 2003 году. Концепция старше AI-агентов. Skill её автоматизирует.

Failure Mode 3: код не работает

Ваш агент пишет код, который выглядит разумно, но ломается в runtime. У него нет feedback о том, запускается ли результат. Без теста, type check или браузера, в который можно посмотреть, агент кодит вслепую.

Исправление — feedback loop skill. Самая эффективная версия — TDD skill, который enforce’ит цикл red-green-refactor: агент сначала пишет падающий тест, затем минимальный код, чтобы тест прошёл, а затем чистит решение.

Тест должен упасть до начала implementation. Это structural gate, а не рекомендация.

Почему это важно? Потому что агенты перескакивают к написанию кода и дописывают тесты потом. Это разрушает смысл подхода.

Хорошо написанный TDD skill предотвращает это, делая последовательность обязательной: сначала red, потом green, потом refactor. Skill превращает мягкий nudging в правило.

Failure Mode 4: codebase превращается в грязь

AI-агенты ускоряют написание кода. Это их selling point. Но они также ускоряют software entropy.

Каждое изменение, которое не учитывает общую структуру codebase, добавляет маленькие несогласованности. Они накапливаются. Через несколько недель неконтролируемого AI-generated code проект превращается в хрупкий клубок мелких взаимосвязанных файлов, в котором не может разобраться ни человек, ни агент.

John Ousterhout в A Philosophy of Software Design описывал это как различие между deep modules и shallow modules. Deep module имеет простой интерфейс, скрывающий много функциональности. Shallow module — тонкая обёртка почти ни над чем.

Агенты склонны производить shallow modules, потому что их легко генерировать. Но shallow codebases трудно тестировать, трудно менять, и другим агентам трудно с ними работать.

Исправление — architecture skill, который регулярно сканирует codebase и ищет места, где можно углубить modules: где понимание одного концепта требует прыгать между десятью файлами?

Где pure functions были вынесены только ради testability, но реальные bugs скрываются в том, как они вызываются? Где tightly coupled modules протекают через boundaries?

Запуск такого skill раз в неделю поддерживает codebase в форме и для людей, и для агентов.

Напишите свой первый SKILL.md

Вы определили свой самый дорогой failure mode. Теперь создайте skill, который его исправляет.

Header: YAML Frontmatter

Каждый SKILL.md начинается с YAML-блока между тройными дефисами. Обязательны два поля: name и description.

---
name: code-review-checklist
description: >
  Run a structured code review on the current changeset.
  Trigger when reviewing PRs or before merging any branch.
  Do not use for architecture-level reviews. Use the
  architecture skill instead.
---

Поле description — самый важный текст во всём skill. Агент читает его, чтобы решить, загружать ли skill для текущей задачи.

Выносите keywords и trigger conditions вперёд. Явно указывайте, когда skill НЕ должен срабатывать. Размытые описания приводят к false matches, которые тратят контекст и путают агента.

Body: Markdown Instructions

Ниже header напишите workflow, которому должен следовать агент. Обычный Markdown. Никакого специального синтаксиса не требуется.

# Code Review Checklist

When reviewing a changeset:

1. Read the diff in full before commenting.
2. Check for test coverage on every new function.
3. Flag any function longer than 40 lines.
4. Verify naming follows CONTEXT.md conventions.
5. If a module's public interface changed, confirm
   the changelog entry exists.
6. Summarize findings in a structured comment:
   pass/fail per check, with line references.

Это полноценный skill в одном файле и шести шагах. Теперь агент запускает именно этот checklist каждый раз, когда делает code review, во всех совместимых инструментах, которыми вы пользуетесь.

Держите его коротким

Самый impactful skill в самом популярном skills repository на GitHub состоит из трёх предложений. Он говорит агенту провести интервью с пользователем о плане, пройти по каждой ветви design tree и исследовать codebase в поисках ответов перед тем, как спрашивать пользователя.

Эти три предложения установили более 250 000 раз.

Skill не обязан быть длинным. Он должен выбирать правильные слова в правильный момент.

Если вы пишете skill длиннее двух печатных страниц, скорее всего, вы объединяете два skills в один. Разделите их. One skill, one job.

Начинайте stateless, stateful добавляйте позже

Stateless skill ничего не сохраняет между сессиями. Он запускается, делает свою работу и не оставляет следов.

Каждый invocation начинается с чистого листа. Первый skill лучше делать stateless, потому что в нём меньше того, что может пойти не так.

Stateful skill сохраняет файлы на диск — glossary, progress tracker, context document — и они переживают сессии. Такие skills мощнее, но сложнее.

Shared language skill, описанный выше, stateful, потому что поддерживает CONTEXT.md. Teaching skill может быть stateful, потому что отслеживает, что learner уже прошёл.

Сначала создавайте stateless skills. Добавляйте state, когда почувствуете ограничение от постоянного старта с нуля.

Не скачивайте poison

В community hubs вроде SkillsMP проиндексировано более 1,9 млн публичных skills, собранных из GitHub-репозиториев по всему миру. Большинство нормальные. Некоторые — нет.

В феврале 2026 года security researchers из prplbx.com обнаружили 341 malicious skill в публичных директориях. Эти skills содержали скрытые payloads: data exfiltration, credential theft и prompt injection, который перенаправлял агента на выполнение unauthorized commands. Последующий аудит Snyk, отчёт ToxicSkills, протестировал более широкую выборку и нашёл prompt injection vulnerabilities в 36% изученных skills.

Качество тоже не гарантировано

Помимо безопасности есть проблема качества. Команда SkillsBench проаудировала более 47 150 публичных skills перед тем, как выбрать curated ones для своего benchmark. Большинство публичных skills не дотягивали: vague descriptions, которые срабатывают не на тех задачах; слишком generic instructions, которые не дают стабильного результата; отсутствие clear workflow structure.

Когда SkillsBench сравнил производительность агентов с curated skills и self-generated skills, модели, пытавшиеся писать skills самостоятельно, не показали надёжного улучшения. Качество skill важнее самого факта его наличия.

Разрыв между curated, хорошо структурированным skill и случайным skill из community directory — это разрыв между обученным процессом и догадкой. Если вы собираетесь использовать community skills, берите их из established sources с видимым количеством установок и активными maintainers. Или пишите свои.

Правило Audit-Before-Adopt

Перед установкой любого community skill:

1. Прочитайте полный SKILL.md. Не ограничивайтесь name и description.
2. Откройте папку scripts/, если она есть. Прочитайте каждый файл. Если script что-то скачивает из интернета или обращается к environment variables, вы должны понимать зачем.
3. Проверьте, кто опубликовал skill. Анонимный GitHub-аккаунт с одним repo и нулём followers — это один risk profile; established developer с годами публичной работы — другой.
4. Сначала протестируйте skill на disposable project. Никогда не устанавливайте непроверенный skill сразу в production codebase.

Это та же гигиена, которую вы применяете к npm packages или VS Code extensions. Skills — это код, который работает внутри вашего агента. Относитесь к ним соответственно.

Что меняется, когда вы создаёте skills

Сначала сдвиг кажется небольшим. Вы пишете SKILL.md, устанавливаете его, и агент следует checklist, который раньше пропускал.

Это полезно. Но важен compounding effect.

Вы перестаёте повторяться

До skills каждая сессия начиналась с повторного объяснения ваших предпочтений: «Используй TypeScript. Следуй нашим naming conventions. Сначала пиши тесты. Не используй any-types».

Со skills эти инструкции живут в файлах. Вы пишете их один раз, агент подтягивает их каждый раз. Первое сообщение каждой сессии может быть самой задачей, а не setup ritual.

Ваш агент становится предсказуемым

Агент без skills — способный improviser. Он может справиться с большинством задач, но его подход меняется от сессии к сессии.

Иногда он пишет тесты сначала. Иногда нет. Иногда задаёт уточняющие вопросы. Иногда просто начинает строить.

Агент со skills следует определённым процессам. TDD skill гарантирует, что тесты идут до кода. Grilling skill гарантирует alignment до implementation.

Architecture skill следит, чтобы codebase не загнивала. Вы перестаёте надеяться, что агент сделает хороший выбор, и начинаете знать, что он будет следовать хорошему процессу.

Ваши инструменты становятся взаимозаменяемыми

Поскольку skills следуют открытому стандарту SKILL.md, ваши workflows переносятся при смене агентов. Переходите с Claude Code на Codex или добавляете Cursor рядом с Gemini CLI — ваши skills идут с вами.

Ваш процесс становится portable. Инвестиция в написание хороших skills окупается независимо от того, на каком инструменте вы остановитесь.

Вы начинаете кодировать то, как работаете

Это более глубокий сдвиг. Skill — не просто инструкция для агента. Это формализованная версия того, как вы думаете о задаче.

Сам акт написания skill заставляет артикулировать процесс: какие шаги вы выполняете? В каком порядке? Где decision points?

Большинство инженеров носит это знание как инстинкт. Записав его как skill, вы делаете его передаваемым агентам, teammates и самому себе в будущем.

Начните здесь

Выберите failure mode, который отнимает больше всего времени. Напишите один SKILL.md, который его закрывает. Держите его короче 30 строк. Установите. Используйте неделю. Затем напишите следующий.

Люди, которые относятся к AI-агентам как к chat windows, будут каждое утро вставлять одни и те же инструкции. Люди, которые относятся к ним как к team members с encoded process, будут compounding their productivity — сессия за сессией, skill за skill.

Skills портативны между tools, composable между workflows и накапливают эффект со временем. В этом разница между «использовать AI» и «строить с AI».

Ресурсы

• Agent Skills specification: agentskills.io
• SKILL.md format reference and examples: github.com/agentskills/agentskills
• Browse community skills: skills.sh
• Security audit findings: ищите “ToxicSkills Snyk 2026” для полного отчёта
• SkillsBench research paper: arxiv.org/abs/2602.12670 — 84 задачи, 11 доменов, peer-reviewed

Follow @free_ai_guides for daily AI tips, guides, and resources.