Конкретные правила в SKILL.md: как одна строка с командой или путём заставляет агента действовать

ШАГ 1: Найди, где агент ошибается или пропускает действие → список «что он должен был сделать»
ШАГ 2: Для каждого пропуска напиши правило-приказ с точным токеном в `кавычках` → одна строка
ШАГ 3: Проверь, что токена не было в старой инструкции → если был, правило даёт меньше
ШАГ 4: Прогони тот же запрос до и после → смотри, появилось ли нужное действие
ШАГ 5: Выкинь правила без заметного эффекта → не раздувай файл

Это работа с файлом инструкций, не один промпт. Шаги 4–5 — это отдельные запуски агента.

Задача: Вы ведёте продукт в приложении доставки продуктов (в духе «Самоката»). Агент в Claude Code пишет релиз-ноуты для магазинов приложений. Каждый раз он выдумывает свой тон и забывает про проверку лимита символов. В скиле release-notes написано расплывчатое: «Пиши в нашем тоне, следи за длиной».

Промпт (правки в SKILL.md):

---
name: release-notes
description: Пишет текст релиза для App Store и RuStore. Используй, когда просят
  подготовить release notes, «что нового» или описание версии.
---

# Правила

- **Перед написанием** прочитай `docs/tone-of-voice.md`.
- Список изменений бери только из `CHANGELOG.md`, не из памяти.
- Сформируй текст для RuStore в файле `release/rustore.txt`, для App Store — в `release/appstore.txt`.
- **После написания** запусти `npm run check:length` и исправь текст, если проверка не пройдена.
- Не используй слова из списка `docs/banned-words.md`.

Результат: Агент чаще начнёт работу с чтения именно docs/tone-of-voice.md, возьмёт изменения из CHANGELOG.md, создаст два файла по указанным путям и запустит проверку длины. Прирост будет заметнее по тем пунктам, где раньше в инструкции не было ни пути, ни команды. Часть этого эффекта потеряется, если агент решит не загружать скил целиком. Поэтому в description стоит перечислить фразы, по которым скил должен включаться.

Слабость LLM. Модель не знает структуру вашего проекта. Фраза «следуй нашему тону» не говорит, где этот тон записан и что делать. Модель подставит среднее по интернету. Если нужный файл просто лежит в репозитории или упомянут где-то рядом, этого мало. В исследовании «видел токен рядом» не заменяло правило.

Сильная сторона LLM. Модель отлично выполняет прямые указания, когда в них есть точное имя: «прочитай X», «запусти Y», «положи в Z». Такой приказ можно выполнить буквально, и результат легко проверить. Кроме того, старые и новые поколения моделей выигрывают примерно одинаково, так что приём не завязан на самую свежую модель.

Как метод обходит слабость. Правило с токеном превращает расплывчатое пожелание в конкретное действие. Больше всего это помогает, когда токена в старой инструкции не было совсем: агент не мог угадать ни путь, ни команду.

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

Про стоимость. Новая версия добавляет примерно 18–19% входных токенов в одиночном ответе. Но ответ при этом становится короче. В агентном эпизоде обнаружить рост расхода от самой правки не удалось. Зато сама подгрузка тела скила повышает расход эпизода в среднем на 50%.

---
name: {имя_скила}
description: {что делает скил}. Используй, когда {ситуации_запуска_через_запятую}.
---

# Правила

- Перед {действие_1} прочитай `{путь_к_файлу_1}`.
- Для {задача_2} используй команду `{команда_2}`.
- Результат сохраняй в `{путь_для_результата}`.
- После {действие_3} запусти `{команда_проверки}` и исправь, если проверка не пройдена.
- Не используй `{запрещённое_имя_или_флаг}`.

Что подставлять: - {имя_скила} и {что делает скил} — короткое имя и одна фраза о назначении. - {ситуации_запуска} — реальные формулировки запросов, по которым агент должен включить скил. - {путь_к_файлу}, {команда}, {путь_для_результата} — точные токены из вашего проекта. Не «наш гайд по стилю», а docs/tone-of-voice.md. - {команда_проверки} — любая команда, по результату которой можно сразу понять, сделано ли действие.

🚀 Быстрый старт — вставь в чат с агентом или обычной LLM:

Вот шаблон правил для SKILL.md. Адаптируй под мою задачу: {твоя задача}.
Вот мой текущий SKILL.md (или инструкция): {вставить}.
Задавай вопросы, чтобы заполнить поля.

[вставить шаблон выше]

LLM спросит про точные пути, команды и ситуации запуска, потому что метод работает только на конкретных токенах. Она сверит их с вашей текущей инструкцией, найдёт те, о которых там ничего не сказано, и превратит их в правила-приказы.

⚠️ В реальных агентах эффект меньше: в одиночном ответе правило поднимает соблюдение очень сильно. В агентной среде прирост заметно скромнее. По итоговой правильности результата (по слепой оценке людей) он умеренный.

⚠️ Скил может не загрузиться: реальные инструменты подгружают тело скила только когда агент решит, что оно нужно. При такой загрузке сохраняется примерно половина прироста, у открытых моделей — около трети.

⚠️ Только проверяемые правила: измеряли правила с точным токеном (команда, путь, имя). Правила про тон, стиль и «будь аккуратнее» в исследовании не оценивали. Для них вывод не доказан.

⚠️ Лишние токены: загрузка тела скила повышает расход эпизода примерно наполовину. В части случаев (около каждой пятой пары правило — модель) токены тратятся без видимой пользы.

⚠️ Условия проверки: режим «размышления» у моделей отключали, часть экспериментов шла на небольших открытых моделях. Проверка в одиночных ответах шла по буквальному совпадению строки, что точное, но грубое мерило. Песочница — 80 задач.

⚠️ Эффект работает только там, где правило нужно: все результаты — для запросов, в которых правило применимо. Если запрос его не касается, пользы нет.

Команда взяла 3159 реальных SKILL.md из 856 репозиториев на GitHub и восстановила историю правок каждого. Для 2608 пар «первая версия — последняя версия» они выбрали строки, которые мейнтейнеры добавили или удалили: приказ плюс конкретное имя (команда, путь, флаг) в обратных кавычках. Из этого получилось 396 «зондов»: пользовательский запрос, где правило обязательно нужно, но о нём прямо не сказано. Проверка шла по строке: есть в ответе нужный путь или команда, или нет.

Каждый зонд прогнали в трёх условиях: без тела скила, со старой версией и с новой. Разница «новая минус старая» показывает чистый эффект правки. Тестировали 21 модель (16 открытых, 5 закрытых, включая Claude Sonnet 4.5 и GPT-5.5) и четыре агента в песочнице на 80 исполняемых задачах. Результаты проверяли слепой оценкой людей.

Прирост соблюдения в одиночном ответе оказался в среднем +0.41, у агентов — действие совершается чаще на +0.23, итоговая правильность растёт на +0.10. Неожиданно, что само присутствие токена где-то ещё в контексте не заменяло правило, а в агентном эпизоде правка не добавила заметных затрат. Практический вывод: пиши прямые указания с названием действия, но следи, чтобы скил вообще загружался.

Request (generated; never mentions the directive):
I need to save a new note about the Q4 marketing strategy. Please categorize it into the correct project folder based on our current project structure.

Added directive (line 21 of the new version of the Skill note-organizer):
Must read: knowledge/projects/_index.md

Check: response must contain knowledge/projects/_index.md

Result (compliant samples, none / old / new):
Qwen 3.5-9B: 0/5, 0/5, 5/5
All 16 models: 0/80, 0/80, 43/80

Контекст: это иллюстрация из статьи (Fig. 2). Реальный скил организует заметки. Одна добавленная строка с путём превратила «никто не читает индекс» в «читают в большинстве случаев».

💡 Адаптация для правил в CLAUDE.md и AGENTS.md: файлы инструкций проекта, в отличие от тела скила, обычно лежат в контексте всегда. Критичные приказы («перед коммитом запусти npm run lint», «не трогай legacy/») логично держать там, а в скиле оставить детали процедуры. Эту схему статья напрямую не сравнивала. Это вывод из механики загрузки, проверяй на своих задачах.

Copy

# CLAUDE.md
- Перед любым коммитом запусти `npm run lint` и `npm test`.
- Для задач про релизные тексты используй скил `release-notes`.

🔧 Техника: усиль description → скил включается чаще. Если агент решает, загружать скил или нет, по одному описанию, перечисли в нём реальные формулировки запросов: «Используй, когда просят release notes, “что нового”, описание версии». Это тоже вывод из механики, а не измеренный в статье приём.

• Статья: Agent Skill Evolution: How Revisions Affect Coding Agents
• Авторы: Jiajie Wang (The University of Arizona), Yutong Zhao (California State University, Long Beach), Tianlin Li (Nanyang Technological University), Huashan Chen (Institute of Information Engineering, Chinese Academy of Science), Jinfu Chen (Wuhan University), Kebin Peng (East Carolina University), Sen He (The University of Arizona)
• Данные: датасет SkillMD-138K, 396 зондов, 80 исполняемых задач и разметка людей (в статье указан пакет для воспроизведения)