Перейти к содержимому
TelegramGitHub

Claude AI Bible, глава 14: Skills — многоразовые умения

Главная мысль: Skill — это папка с инструкциями, которую Claude подключает сам, когда задача совпадает с её описанием. Вы один раз записываете, как делать работу правильно, и Claude делает её так каждый раз. Главное в skill — поле description: по нему Claude решает, нужен ли skill сейчас.

В главе 13 Claude Code брал постоянные правила проекта из CLAUDE.md. Эта глава о пакете знаний под одну задачу, который грузится только по необходимости. Темы: устройство skill, роль description, первый skill по шагам, скрипты и образцы, проверка, библиотека skill и обмен ими.

Автор начинает с примера. Одна сотрудница знает всё про коммерческие предложения: порядок разделов, обязательный абзац юристов, нужный тон. Остальные забывают абзац и берут старый шаблон цен. Skill упаковывает её знания так, чтобы любой человек или Claude делали предложение её способом.

Как Claude подключает skill: читает description всех skill, при совпадении грузит тело SKILL.md, а скрипты и образцы только по шагу инструкции; внизу три слоя загрузки

Запрос сравнивается с описаниями, и только при совпадении в контекст попадает тело skill. Нижний ряд показывает, когда каждый слой занимает контекст.

Раньше приходилось объяснять всё заново в каждом разговоре: три абзаца про формат, тон и частые ошибки. Каждый раз текст выходил немного другим, и результат тоже менялся, а коллега писал свои абзацы и получал свой результат. Опыт, который живёт в голове или в старых переписках, трудно передать другим и трудно держать одинаковым.

Skill переносит этот опыт из головы в файл. Его пишут один раз, а Claude применяет его сам, поэтому новичок делает работу правильно с первого дня. Вторая польза — чистый контекст: подробные инструкции не грузятся в каждый разговор, а ждут своей задачи.

Skill — это папка с одним обязательным файлом SKILL.md из двух частей:

  • Метаданные — блок «ключ: значение» в начале файла с полями name и description. Описание автор называет самым важным предложением: оно говорит Claude, когда skill нужен.
  • Тело — инструкции в Markdown: шаги, правила, форматы, примеры. Это как хорошая страница внутренней wiki, только для Claude.

Ещё в папку можно положить скрипты для точных, детерминированных операций (расчёт, преобразование файла) и ресурсы: шаблоны, образцы, чек-листы.

Части skill грузятся слоями. Описание в одном-двух предложениях видно всегда. Тело грузится при срабатывании, а скрипты и ресурсы — только когда до них дошёл шаг инструкции. Поэтому даже справочник на тысячу строк почти не занимает контекст, пока он не нужен.

Skill не вызывают по имени, как команду. Claude сам читает описания доступных skill и сравнивает их с запросом: совпало — skill грузится, нет — skill не используется. Значит, description — не документация: по этому полю Claude сопоставляет запрос со skill. В нём называют задачу, ситуации и слова, которыми люди на самом деле просят эту работу.

Тело отвечает на вопрос «как делать» и может быть длинным. Описание Claude сверяет с каждым запросом, поэтому оно короткое и точное. Правило автора: условия — в описании, метод — в теле.

Самая частая ошибка — skill, который не срабатывает. Skill на 600 слов про возврат денег с описанием «Handles refunds» молчит на просьбу «верни клиенту деньги»: этих слов в описании нет. Поэтому в описание добавляют разные формулировки той же просьбы.

Пример автора выдуманный: книжная сеть Marlowe & Finch с филиалами в разных округах. Руководители округов пишут недельные сводки продаж каждый по-своему, и головной офис не может их сравнить. Шаги такие:

  1. Назвать умение точно: не «reports», а weekly-store-summary.
  2. Продумать каждое слово описания и собрать фразы, которыми просят эту работу: недельная сводка, отчёт по филиалам, итоги продаж, «цифры за понедельник».
  3. Написать тело: разделы, их порядок, правила, тон и то, что нельзя пропускать.

Наша версия файла на русском короче книжной, но устроена так же:

---
name: weekly-store-summary
description: >
Готовит стандартную недельную сводку по филиалам книжной сети из сырых цифр продаж.
Используй, когда просят недельную сводку, отчёт по филиалам, итоги продаж
за неделю, «цифры за понедельник» или сравнение филиалов с прошлым годом.
---
# Недельная сводка по филиалам
Цель: управляющий за минуту видит, каким филиалам нужно внимание.
Одинаковый формат важнее красивых слов.
## Что нужно на входе
По каждому филиалу: выручка за неделю, выручка за ту же неделю год назад,
число покупок, число посетителей. Если чего-то нет, спроси. Не угадывай.
## Формат (всегда в этом порядке)
1. Заголовок: общая выручка и изменение к прошлому году в процентах.
2. Таблица: филиал, выручка, изменение к прошлому году, покупки, посетители, конверсия.
3. Лучший и худший филиал по изменению к прошлому году.
4. Список наблюдения: филиалы с падением выручки или с конверсией ниже 8%.
Если таких нет, напиши: «В списке наблюдения никого нет».
5. Одно конкретное действие на следующую неделю.
## Правила
- Конверсию считай только скриптом: `python3 scripts/conversion.py <покупки> <посетители>`.
- Деньги: символ валюты, разделитель тысяч, без копеек.
- Тон сухой и короткий. Без слов «отлично» и «ужасно».
- Не делай выводов, которых нет в цифрах.
## Образец
Структура и длина — как в `resources/example-summary.md`.

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

Автор сравнивает три описания для skill, который оформляет отчёт об инциденте после сбоя:

ОписаниеОценка
«Отчёты об инцидентах»Плохо: сработает ли он на «опиши, что случилось во время сбоя», — как повезёт
«Skill для разных отчётов, полезен во многих ситуациях, где нужна документация»Плохо: длинно и размыто, сработает на всё или ни на что
«Оформляет отчёт после сбоя в production. Используй, когда нужно описать инцидент, написать postmortem или записать, что случилось и как это исправили»Хорошо: названы результат, ситуация и фразы для запроса

Рецепт автора: назовите результат и ситуацию, перечислите слова, которыми живые люди просят эту работу. Помогает не длина, а точность.

Тело подходит для решений, где нужно суждение, и для формата. Но то, что должно выполняться одинаково каждый раз, лучше отдать скрипту. Конверсию (покупки, делённые на посетителей) Claude обычно посчитает верно, но «обычно» не годится для числа, по которому принимают решения. Поэтому инструкция велит запустить скрипт. Наша версия:

"""Конверсия филиала: покупки / посетители, в процентах.
Запуск: python3 scripts/conversion.py <покупки> <посетители>"""
import sys
def conversion(units: float, footfall: float) -> str:
if footfall == 0: # посетителей не было: делить нельзя
return "0.0%"
return f"{units / footfall * 100:.1f}%"
if __name__ == "__main__":
print(conversion(float(sys.argv[1]), float(sys.argv[2])))

Запуск для трёх филиалов, у последнего не было посетителей:

Окно терминала
python3 scripts/conversion.py 412 3870
python3 scripts/conversion.py 95 1420
python3 scripts/conversion.py 10 0
10.6%
6.7%
0.0%

Модель отвечает за текст и выводы, скрипт — за точность. Такое разделение автор считает признаком хорошего skill. Ресурсы тоже лежат в папке и нужны по шагу инструкции: по образцу resources/example-summary.md Claude повторяет структуру и длину сводки. Папка целиком:

weekly-store-summary/
├── SKILL.md
├── scripts/
│ └── conversion.py
└── resources/
└── example-summary.md

Папка skill weekly-store-summary: обязательный SKILL.md с метаданными и телом, а также скрипт conversion.py и образец example-summary.md, которые тело вызывает по шагам

Полный пример с рабочим скриптом лежит в репозитории сайта: scripts/claude-ai-bible-code/ch14_weekly-store-summary/.

Skill — это программа, и с первого раза он редко работает идеально. Автор предлагает две проверки:

  • Срабатывание. В новом разговоре просите так, как попросил бы живой человек: «дай цифры за понедельник». Не сработало — описание узкое, добавьте в него эту фразу. Сработало на чужой запрос — описание широкое, сузьте его.
  • Результат. Соблюдён ли формат, запущен ли скрипт, спросил ли Claude про пропуски или выдумал их? Такие ошибки исправляют в теле.

Две проверки skill: проверка срабатывания ведёт к правке description, проверка результата ведёт к правке тела

Меняйте по одной вещи: обычно виновато одно неясное предложение, а не весь skill. Ещё автор советует намеренно ломать срабатывание: спрашивать торопливо, синонимами и соседними вопросами, на которые skill должен молчать.

Claude буквально выполняет конкретные указания и импровизирует там, где их нет. Поэтому будьте конкретны там, где вам важно. Четыре приёма автора:

  • Сначала цель, потом шаги. Фраза «Сводка нужна, чтобы управляющий сразу видел проблемные филиалы» поможет Claude решить спорный шаг. Шаги без цели соблюдают букву, но не смысл.
  • Жёсткие правила — отдельно. Абзац юристов слово в слово, то, что недопустимо никогда, выносят в раздел «Правила» или «Никогда». Если всё сказано одинаково мягко, модель не отличит гибкое правило от обязательного.
  • Покажите пример. Образец результата не оставляет места для толкований, а плохой пример с пометкой, что в нём не так, работает ещё лучше.
  • Продумайте нехватку данных. Фраза «Если чего-то не хватает, спроси. Не угадывай» убирает целый класс уверенных, но неверных ответов.

Тонкая ошибка — подробно описать шрифт и заголовки, а трудное решение, ради которого задача существует, упомянуть мимоходом. Такой skill идеально форматирует и проваливает суть.

Когда skill становится много, автор советует три вещи:

  • Один skill — одна работа. У skill на восемь задач не может быть точного описания. Разделите его.
  • Следите за пересечением описаний. Если описания двух skill похожи, Claude может взять не тот. Проведите границу или объедините их.
  • Называйте единообразно и время от времени чистите библиотеку от лишнего.

Пример из книги: консультантка из Найроби, которая помогает НКО с заявками на гранты, собрала 11 skill под форматы разных фондов. Общий шаг «объяснить бюджет простыми словами» она вынесла в отдельный skill, и остальные стали опираться на него. Время на заявку сократилось примерно на треть. Причина не в одном удачном skill: узкие skill без пересечений начали усиливать друг друга.

Skill окупается, если задача повторяется и у неё есть свой правильный способ. Разовую задачу проще объяснить в разговоре, а если годится любой подход, записывать нечего. Skill не нужен, если требуется связь с внешней системой (это MCP server, глава 16) или если весь метод сводится к «сделай хорошо». Проверка автора: можно ли записать три конкретных правила? Если нет, упаковывать нечего.

CLAUDE.md в Claude Code всегда в контексте проекта и хранит правила для всей работы в нём. Skill грузится под задачу и подходит многим проектам, поэтому метод одной задачи лучше вынести из CLAUDE.md в skill.

Дерево решений: внешняя система ведёт к MCP server, разовая задача к вопросу в разговоре, задача без конкретных правил обходится без skill, правила проекта идут в CLAUDE.md, остальное становится skill

Дерево читают сверху вниз: каждый ответ ведёт к другому инструменту или к следующему вопросу.

Skill — это просто папка: упакуйте её в zip и отправьте. У коллеги Claude включит skill так же, потому что логика срабатывания записана в файле. Так личный приём становится общим инструментом команды: формат меняют в одном skill, и результат меняется у всех.

Общие skill держат в одном репозитории, чтобы не было семи расходящихся копий. Чтобы раздать skill вместе с MCP server, slash-командами и агентами одним пакетом, есть plugin и marketplace (глава 15).

  • Skill — это папка с SKILL.md, и Claude подключает её сам, когда задача совпадает с описанием.
  • Поле description решает, сработает ли skill, поэтому в нём перечисляют реальные фразы запроса.
  • Описание видно всегда, тело грузится при срабатывании, а скрипты и ресурсы — по шагу инструкции.
  • Точные расчёты отдают скрипту, а не модели.
  • Skill проверяют дважды: срабатывает ли он и верен ли результат.
  • В теле сначала идёт цель, жёсткие правила вынесены отдельно, а про пропуски Claude должен спрашивать.
  • Один skill делает одну работу, а описания разных skill не пересекаются.
  • Папку skill легко передать команде, и тогда опыт становится общим.
ТерминЗначение
skillПапка с инструкциями, скриптами и ресурсами, которую Claude подключает по description
SKILL.mdОбязательный файл: метаданные сверху, инструкции ниже
descriptionПоле метаданных: когда skill нужен
пересечение описанийПохожие описания двух skill, из-за которых Claude берёт не тот
CLAUDE.mdПостоянные правила проекта, всегда в контексте
  • Ревью dbt-модели, разбор упавшего DAG и ночной отчёт о качестве данных хорошо ложатся в skill.
  • Сверку числа строк и суммы считайте скриптом или SQL-файлом из папки skill.
  • Правила репозитория держите в CLAUDE.md, а доступ к хранилищу даёт MCP server, а не skill.
  • Храните общие skill в репозитории команды и меняйте их через pull request.
  1. Почему skill с хорошим телом может ни разу не сработать?
  2. Почему тело может быть длинным, а описание — нет?
  3. Когда расчёт лучше вынести в скрипт?
  4. Чем skill отличается от CLAUDE.md и от MCP server?
  5. Зачем делить большой skill на несколько маленьких?

Предыдущая: Claude Code: агент для кода в терминале. Следующая: Plugins и marketplaces.