🧰 Skill.md: почему 92% инструкций не переиспользуются Исследование *What Keeps Agent Skills from Being Reusable?* (2608.08453) проанализировало 138 133 файла навыков из 20 556 репозиториев. Вывод: почти 92% содержат хотя бы один дефект, который мешает агенту их найти и использовать повторно. Главная причина — нечёткое описание-триггер в первых 1–3 предложениях. Агент читает только заголовок, и если там не сказано чётко *«что делает»* и *«когда применять»* — инструкция игнорируется, даже если внутри всё идеально.

🔍 Как это работает (проблема) 1. Агент просматривает множество Skill.md, но читает только краткое описание. 2. Он сопоставляет его с двумя вопросами: *что делает?* + *когда использовать?* 3. Если ответ расплывчатый — файл «прячется» от агента, и он его не берёт. Поэтому метод фокусируется именно на «подписании» файла, а не на его содержимом.

✅ Чек-лист из 7 критериев (проверьте свой Skill.md)

1️⃣ Маршрутизация (описание-триггер) • 1–3 предложения, отвечающие на «что делает» и «когда использовать». • Добавьте конкретные слова-триггеры: *«используй при…»*, *«необходим для…»*. Уберите воду.

2️⃣ Тело инструкции • Компактность, без историй правок, TODO, FIXME, дублирования названия. • Примеры и код выносите в отдельные блоки, не смешивайте с основной логикой.

3️⃣ Организация ресурсов • Не загружайте inline-код и большие примеры — создайте папки examples/ и scripts/, подключайте через пути.

4️⃣ Запрещённый контент • Удалите install-инструкции, changelog, лицензии, TODO/FIXME. Оставьте только рабочий код. Если нужен changelog — вынесите в отдельный файл.

5️⃣ Безопасность поведения • Никаких паролей, ключей, опасных команд, локальных путей. • Используйте переменные окружения (${API_KEY}) и относительные пути.

6️⃣ Переносимость • Нет привязки к конкретной модели, платформе или ОС. • Замените model: claude-3-opus на model: any, уберите OS-специфичные команды.

7️⃣ Роль и границы • Не переопределяйте личность ассистента без необходимости. • Оставьте роль «ассистент» или уточните только при крайней необходимости.

📋 Практический шаблон для проверки Скопируйте и прогоните свой Skill.md: > 1️⃣ Маршрутизация: ✅ / ⚠️ > 2️⃣ Тело инструкции: ✅ / ⚠️ > 3️⃣ Организация ресурсов: ✅ / ⚠️ > 4️⃣ Запрещённый контент: ✅ / ⚠️ > 5️⃣ Безопасность поведения: ✅ / ⚠️ > 6️⃣ Переносимость: ✅ / ⚠️ > 7️⃣ Роль и границы: ✅ / ⚠️

> Переписанная версия: > {вставьте исправленный Skill.md}

🧪 Быстрый промпт для проверки инструкции

> *LLM, для какой платформы ты собираешься использовать эту инструкцию? (Custom GPT / Claude Project / командный документ)* > *Текст инструкции: {ваш_Skill.md}*

> *Проверь её по чек-листу выше и укажи проблемы. Затем перепиши исправленную версию.*

Ограничения метода - Диагностика, а не генерация – LLM не пишет инструкцию с нуля, только очищает существующую. - Не подходит для одноразовых промптов – если инструкция используется только в одном чате, чек‑лист избыточен. - Доказательства сильны лишь для описания‑триггера – остальные пункты подтверждены косвенно (жалобы пользователей).

📊 Ключевые цифры • Чистые описания-триггеры → вероятность нахождения агентом: 88,5% • Дефектные описания → 82,6% • 92% всех файлов имеют хотя бы один дефект Разница в 6 процентных пунктов — но с учётом, что большинство файлов всё равно дефектны, улучшение описания даёт ощутимый прирост в переиспользуемости.

⚠️ Ограничения • Сильные доказательства получены только для описания-триггера — остальные критерии подтверждены косвенно (на основе жалоб пользователей). • Не генерации новых инструкций, только для рефакторинга существующих.

🎯 Что делать прямо сейчас 1. Откройте свой Skill.md. 2. Проверьте первые 3 предложения — чётко ли они отвечают на «что делает» и «когда использовать»? 3. Прогоните по чек-листу все 7 пунктов. 4. Исправьте найденные проблемы и сохраните новую версию.

📎 Исследование 2608.08453