Скилл устроен разочаровывающе просто: папка, а в ней текстовый файл, где обычными словами написано, как делать одну конкретную работу. Весь эффект держится на одной строке внутри этого файла. Её пишут формально, в две секунды, а потом неделями выясняют, почему скилл не срабатывает.
У меня их около тридцати, и работают они каждый день. Разбираю устройство на своей практике, а не по документации, — с оговоркой, что часть выводов ниже это мои наблюдения, а не официальные правила.
Что такое скилл
Скилл — это папка с файлом SKILL.md внутри, где записана инструкция под повторяющуюся задачу. Инструкция пишется обычным текстом, по-русски, в свободной форме: вот что делаем, вот в каком порядке, вот чего не делаем никогда, вот примеры хорошего результата.
Официальное описание формата лежит в документации Claude Code. Но формат там простой до неприличия: заголовок в начале файла и дальше свободный текст.
Сами по себе скиллы не работают: они живут внутри обвязки. Обвязка — это программа, в которой сидит ИИ-модель: она даёт модели инструменты, держит её правила и водит по кругу, пока задача не сделана. Claude Code — одна из таких обвязок, и про их устройство у меня есть отдельный разбор.
Выглядит начало файла так: сначала идёт короткий блок из двух обязательных строк — имя скилла и его описание, а после них весь остальной текст инструкции. Имя нужно, чтобы вызвать скилл вручную. Описание работает иначе, и именно оно решает судьбу скилла.
Чем скилл отличается от промпта
Это главный вопрос, и ответ на него не про формат, а про то, кто кого вспоминает.
Промпт вы вспоминаете сами. Открыли чат, набрали руками «пиши коротко, без канцелярита, обращение на вы», получили результат. Закрыли чат — всё исчезло. Завтра набираете заново, чуть-чуть другими словами, и получаете чуть-чуть другой результат.
Скилл вспоминает вас. Файл лежит на диске. Вы говорите «сделай пост про эту новость», агент смотрит на описания всех имеющихся скиллов, видит, что один из них про написание постов, и подключает его сам. Вы про скилл в этот момент даже не думаете.
Разница выглядит косметической ровно до того момента, пока задач не станет больше пяти. Держать в голове пять формулировок можно. Держать тридцать — нельзя, и вы начинаете упрощать: писать «сделай нормально» вместо точной инструкции. Результат падает, и вы решаете, что модель стала хуже. Модель не стала хуже, вы перестали объяснять.
Description: строка, которая решает всё
Внутри скилла есть поле description, описание. Выглядит оно как формальность вроде подписи к папке. На самом деле это единственное, что агент читает, решая, брать этот скилл в работу или нет.
Механика такая. Агент держит перед глазами список всех описаний, а сами скиллы не открывает — это было бы слишком много текста. Приходит ваша задача, он сопоставляет её с описаниями и открывает тот скилл, чьё описание совпало. Не совпало ни одно — работает без скиллов, как обычно.
Отсюда самая частая поломка: скилл написан прекрасно и не срабатывает никогда. Причина всегда одна. Описание пишется внутренним языком автора, названием задачи, как она звучит у него в голове. А вслух задача ставится совсем другими словами, и агент не видит совпадения.
Лечится это одним приёмом. Прежде чем писать описание, вспомните пять-шесть фраз, которыми вы сами просите сделать эту работу. Именно вслух, со всеми своими словечками. Вот эти фразы и вставляйте в описание, целиком. Не «генерация контента для социальных сетей», а «напиши пост», «сделай пост про», «нарежь на тред».
И второе: в описании стоит указывать не только когда скилл нужен, но и когда он не нужен. Иначе при десятке скиллов два начинают претендовать на одну задачу.
Как выглядит рабочее описание
Покажу на скилле для постов — разница видна сразу.
Первая версия выглядела так:
description: Генерация контента для социальных сетей
Скилл не подключился ни разу. Формально всё верно, тема названа. Но такими словами задача не ставится: вслух это звучит как «сделай пост про эту новость», и совпадения не происходит.
Рабочая версия выглядит так:
description: Пишет посты для телеграма и соцсетей: новости, разборы, личные истории. Триггеры: «напиши пост», «сделай пост про», «нарежь на тред», «пост в телеграм». НЕ для уроков курса и НЕ для сценариев видео, там другие скиллы.
Изменились две вещи. Внутрь описания попали живые фразы, которыми задача ставится вслух, целиком и дословно, а не в пересказе. И прямо названы границы: где скилл не работает и кому уступает место.
Проверить своё описание можно за минуту. Прочитайте его вслух и спросите себя: этими ли словами вы просите сделать работу? Если формулировка звучит как название раздела в документации, скилл не подключится.
Где скиллы лежат
Скиллы живут в папке .claude/skills. Точка в начале имени означает, что папка скрытая: в обычном виде файлового менеджера вы её не увидите, это нормально.
Мест два, и разница между ними практическая.
Внутри рабочей папки проекта. Тогда скилл виден только там. Годится для правил, которые касаются одного дела: своя структура папок, свои договорённости, свой формат отчётов.
В домашней папке пользователя. Тогда скилл доступен из любого проекта. Сюда идёт всё, что описывает вас, а не проект: как вы пишете, каким тоном разговариваете, что для вас неприемлемо в тексте.
Я держу голос и правила письма в домашней папке, а всё, что касается конкретных дел, — внутри их папок. Так, переехав в новый проект, я не остаюсь без голоса и не тащу за собой чужие правила.
Как написать первый скилл, чтобы он заработал
Порядок собран из наблюдения за собственной работой, а не придуман с чистого листа.
Шаг первый. Не придумывайте скилл. Возьмите задачу, которую уже сделали руками раза три-четыре, и перечитайте, что вы писали агенту каждый раз. Скилл — это не проект будущего, это конспект уже случившегося. Скиллы, придуманные заранее, почти всегда описывают не те шаги, которые нужны на деле.
Шаг второй. Опишите порядок, а не пожелания. «Пиши хорошо» — не инструкция. «Сначала найди в тексте главную мысль, потом проверь её по двум источникам, потом пиши, потом прогони по списку запретов» — инструкция. Агент выполняет шаги, а прилагательные интерпретирует.
Шаг третий. Добавьте запреты. Список того, чего делать нельзя, работает сильнее, чем список того, что нужно. У меня в скилле про тексты запретов больше, чем указаний, и именно они держат тон: слова, которые не пишем, обороты, которые выдают машину, темы, которые не трогаем.
Шаг четвёртый. Вставьте примеры. Два-три куска настоящего текста, который вам понравился. Один хороший пример объясняет больше, чем страница объяснений, — это самое сильное, что можно положить внутрь скилла, и это же самое редкое, потому что примеры лень собирать.
Шаг пятый. Опишите словами, которыми просите. Тот самый description. Пять-шесть живых фраз.
Шаг шестой. Проверьте, что он вообще подключился. Дайте задачу обычными словами и посмотрите, взялся ли скилл. Не взялся — правьте описание, а не содержание. В девяти случаях из десяти проблема там.
Зачем это понадобилось самой Anthropic
Формат придумала компания, которая делает Claude Code, и придумала под свою задачу. Понимать её полезно: от этого зависит, будут формат развивать или свернут через год.
Техническая причина видна прямо из устройства. Модель удерживает в голове ограниченный объём текста. Засунуть туда тридцать полных инструкций нельзя — не останется места на саму работу. Формат решает это разделением: постоянно висят только короткие описания, а тело инструкции подгружается тогда, когда задача совпала. Тридцать скиллов обходятся в тридцать строк, пока не понадобятся по-настоящему.
Коммерческую причину я читаю так — и это моя оценка, а не заявление компании. Человек, у которого написано двадцать своих скиллов, сидит уже не на подписке, а на собственной системе. Перенести её к конкуренту значит переписать всё заново. Формат раздаётся бесплатно, а на выходе получается пользователь, которому дорого уходить.
Практический вывод для нас с вами простой: вложенное в скиллы не пропадёт на следующем обновлении. Этот формат компании выгоден.
Чего скиллы не делают
Три ограничения, которые стоит знать до того, как браться.
Скилл не заменяет решение. Он описывает, как делать работу, но не отвечает, какую работу делать. Тридцать скиллов не помогут, если не решено, что вы вообще выпускаете.
Скилл не спасает от плохого исходника. Если фактура слабая, идеальная инструкция даст аккуратно оформленную пустоту. Быстрее, чем раньше, и всё так же ни о чём.
Скиллы конфликтуют между собой. Когда их становится много, два скилла начинают претендовать на одну задачу и мешать друг другу. Лечится границами в описаниях: у каждого прямо сказано, где он не работает. Это скучная работа, и её приходится делать.
Зачем это маркетологу
Затем, что маркетинговая работа состоит из повторов, которые каждый раз делаются чуть иначе. Пост, письмо, сценарий, отчёт, разбор конкурента — всё это одни и те же шаги, выполненные с разной степенью усталости.
Скилл фиксирует вашу лучшую версию этих шагов. Ту, которую вы придумали в спокойный день, а не в пятницу вечером перед сдачей. Дальше эта версия применяется всегда, независимо от того, в каком вы состоянии.
Это и есть переход от работы промптами к работе системой. Не в том, что стало быстрее, а в том, что качество перестало зависеть от вашего настроения.
Коротко
Скилл держится на трёх вещах: порядок шагов, список запретов и живые примеры. А подключится он или нет, решает одна строка описания.
Но есть следствие, которое обычно замечают позже. Когда правила работы вынесены из головы в файлы, вы перестаёте быть единственным местом, где эти правила хранятся. Их можно передать помощнику, подрядчику, второму человеку в команде — и он начнёт работать по вашему стандарту, а не по своему. Скиллы писались как удобство для одного, а оказались способом описать работу так, чтобы её мог делать кто-то ещё.
С чего начнёте — с той задачи, которая надоела вам сильнее всего?