--- name: skill-from-task description: "Превращает только что выполненную задачу в скилл или обновляет существующий скилл по итогам реальной работы. Используй этот скилл, когда пользователь говорит «сделай из этого скилл», «преврати задачу в скилл», «запиши это в скилл», «оформи как скилл», «сохрани инструкцию для агента», «чтобы в следующий раз агент делал так же», а также когда после выполненной задачи остались исправления, найденные грабли, точные команды или форматы, которые стоит переиспользовать, — даже если слово «скилл» не прозвучало. Используй и при доработке существующего скилла: добавить правило или граблю, обновить описание, проверить срабатывание. Не используй, если задача ещё не выполнена или не проверена либо если опыт одноразовый и не повторяется." metadata: version: "1.0" --- # Как превратить выполненную задачу в скилл Скилл — это снимок реально выполненной работы, а не конспект по теме. Ты пишешь инструкцию, которая меняет поведение агента в следующий раз: точные команды, форматы, порядок шагов, грабли. Всё, что не подтверждено выполненной задачей, — гипотеза, и в скилл она попадать не должна. Главное правило: **сначала задача, потом скилл.** Если результат ещё не проверен, писать нечего — ты зафиксируешь догадку. ## Когда скилл не нужен - Задача не выполнена или не проверена. Скажи об этом прямо и предложи вернуться после проверки. - Опыт одноразовый и не повторяется. - Агент справится с этим и без скилла: нет разницы между поведением по умолчанию и нужным поведением. - Правило относится ко всем задачам проекта — его место в `AGENTS.md` или в документации, а не в скилле. - Пользователь просит промпт, ответ или разовую инструкцию, а не переиспользуемый навык. ## Порядок работы ### Шаг 0. Проверь, что задача выполнена Условие входа: результат существует и подтверждён — файл создан, тест проходит, пользователь принял работу. Если это не так, остановись и скажи: «Задача ещё не проверена. Если написать скилл сейчас, мы зафиксируем гипотезу, а не опыт. Проверим результат и вернёмся?» ### Шаг 1. Собери след Перечитай переписку и артефакты, не полагайся на память. Выпиши пять групп: 1. **Шаги, которые сработали** — последовательность действий и точные команды. Копируй команды из истории запусков, а не перепечатывай. 2. **Исправления** — места, где пользователь поправил агента. Цитаты сохраняй дословно: «ключи вписываются переписыванием, а не дописыванием». Каждое исправление — будущая грабля. 3. **Форматы входа и выхода** — что было на входе (файл, схема, поля) и что должно получиться (файл, таблица, отчёт, карточка), с критериями готовности. 4. **Контекст проекта** — лимиты API, окружение, юридические рамки, порядок шагов, правила именования. Всё, чего агент не знает без скилла. 5. **Тупики** — что пробовали, почему отказались. Это защита от повторения неверного подхода. Артефактов может не быть: задача была аналитической, файл удалён или результат уже передан. Тогда источник — только переписка; пометь это в отчёте. Если чего-то не хватает, задай вопросы одним сообщением и пометь ответы как «уточнено у автора». Не выдавай догадку за факт. ### Шаг 2. Определи границы и имя - **Один скилл — один связный класс задач.** Слишком узкий скилл заставляет загружать несколько скиллов на одну задачу; слишком широкий плохо срабатывает. - **Сначала проверь, нет ли уже такого скилла.** Посмотри каталог скиллов проекта (`.dsh/skills/`, `.agents/skills/` или тот, что использует клиент). Если каталогов нет — найди существующие скиллы поиском `**/SKILL.md`. Подходящий скилл дополни, а не создавай двойника. Уточни у пользователя, если непонятно. - **Имя:** kebab-case, только строчные латинские буквы, цифры и дефисы, 1–64 символа, без дефиса в начале и конце, без двух дефисов подряд. Имя должно совпадать с именем папки. Если папка уже существует и её имя не подходит — предложи переименовать, а не оставляй несоответствие. - Если в задаче два независимых повторяемых класса — предложи два скилла, а не один «про всё». ### Шаг 3. Напиши описание Кроме имени, до запуска агент видит только описание. Оно определяет, будет ли скилл использован. Обязательные элементы: 1. Что скилл делает — 1–2 фразы с конкретными действиями и результатом. 2. «Используй этот скилл, когда…» — прямые ситуации. 3. Косвенные ситуации — когда пользователь не называет домен напрямую («даже если слово „скилл“ не прозвучало»). 4. Границы — что явно не входит в скилл, если есть риск ложных срабатываний. Требования: императивная формулировка, настойчивость (агенты склонны не использовать скилл), не более 1024 символов. Посчитай длину после правки. Подробная методика и проверка триггеров — в `references/description.md`. ### Шаг 4. Собери `SKILL.md` Пиши по порядку: цель и входы (1–2 строки) → процедура с точными командами → грабли → проверка результата и формат вывода → ограничения и «чего не делать». Правила: - **Каждая строка проходит аудит:** «Агент ошибся бы без неё?» Если нет — удали. Никаких «обрабатывайте ошибки надлежащим образом», «будьте внимательны», «проверяйте качество». - **Добавляй то, чего у агента нет,** и не объясняй то, что он знает. Общеизвестные определения — не твоя работа. - **Хрупкое — точной командой.** Параметры, порядок шагов, формат, которые легко испортить, описывай дословно: «запусти ровно эту команду, не меняй флаги». - **Гибкое — с причиной.** Где нужны решения, объясняй, почему так: агент переносит понятую причину на новые случаи лучше, чем заученный запрет. - **Один вариант по умолчанию,** альтернатива — только как условие-исключение. Не давай меню из пяти библиотек. - **Учи методу, а не одному ответу.** Формулируй процедуру для класса задач; конкретные имена файлов и шаблоны вывода допустимы и нужны. - **Объём:** меньше 500 строк и 5 000 токенов. Всё, что не влезает, выноси в `references/`. Аудит относится к телу `SKILL.md`. В `references/` подробности допустимы, но каждый файл должен иметь условие чтения и не дублировать тело. Справочник по аудиту строк, командам и формату грабель — в `references/audit.md`. ### Шаг 5. Вынеси детали - `references/` — длинные справочники, схемы, словари, варианты домена. Для каждого файла укажи **когда его читать** и держи ссылки на один уровень вглубь от `SKILL.md`. - `scripts/` — повторяющаяся логика. Если в задаче появился переиспользуемый скрипт, положи его сюда; если инструмент уже есть в проекте, сошлись на него (как в `references/example.md`), а не копируй код без нужды. Скрипт должен быть неинтерактивным, иметь `--help`, понятные ошибки, структурный вывод (данные — в stdout, диагностика — в stderr), осмысленные коды возврата; для действий, которые меняют или удаляют пользовательские данные (миграции, перезапись исходников, удаление), — `--dry-run`. Перезапись собственных выходных файлов к разрушительным действиям не относится. - `assets/` — шаблоны и статические данные, которые нужны для результата. - Не дублируй одно и то же в `SKILL.md` и `references/`: в теле — ядро и навигация, в справочниках — глубина. ### Шаг 6. Проверь скилл Запусти валидатор. Он лежит в папке этого скилла, поэтому команда должна указывать путь к нему, а не к новому скиллу: ```bash # пример для DSH: скилл установлен в .dsh/skills/ python .dsh/skills/skill-from-task/scripts/validate_skill.py path/to/new-skill ``` Если в проекте есть свой валидатор — запусти и его. Затем проверь вручную: - фронтматтер на месте, `name` и `description` заполнены; - имя совпадает с папкой, description не длиннее 1024 символов; - все файлы, на которые ссылается `SKILL.md`, существуют; - все команды реально запускаются и делают то, что написано; - в файлах нет секретов, токенов и приватных данных; - нет абсолютных путей, привязанных к одной машине. Исключение — обязательные для окружения (например, путь к интерпретатору Python в DSH): пометь его как обязательный, чтобы это не выглядело ошибкой. Остальные пути — относительные от корня скилла или проекта. ### Шаг 7. Протестируй 1. Возьми 2–3 реалистичные задачи и прогони каждую дважды: со скиллом и без него. Сравни результат, число шагов, потраченное время и токены. 2. Прочитай траекторию, а не только финальный файл: где агент буксовал, какие инструкции проигнорировал, что сделал лишнего. 3. Проверь срабатывание: около 20 запросов, из них 8–10 «должен сработать» (включая косвенные формулировки) и 8–10 близких «не должен». Если есть возможность, прогони каждый 3 раза и запиши долю срабатываний. Без такой возможности — сформулируй список запросов и честно скажи, что автоматическая проверка не проводилась. 4. Удали строки, которые не помогли; если скилл не сработал — правь описание, а не добавляй ключевые слова. 5. Если что-то не проверено, так и напиши в отчёте. Не выдавай «скилл протестирован» за факт, если запуска не было. Дешёвый минимум, если нет стенда и времени: одна реальная задача «со скиллом / без» и 5 запросов на срабатывание вручную. Полный набор — когда есть возможность прогнать несколько раз и посчитать доли. Если у скилла есть объективные критерии результата, заведи `evals/evals.json`: 2–3 запроса, ожидаемый результат и проверяемые утверждения. Утверждения проверяются скриптом или отдельным проходом; это делает проверку повторяемой. ### Шаг 8. Отдай результат Отчёт по шаблону: ``` Скилл: — <путь к папке> Что зафиксировано: <шаги, исправления, форматы, контекст> Что сознательно не вошло: <и почему> Как проверено: <задачи, с/без скилла, проверка триггеров> Куда установить: <каталог скиллов клиента> Открытые вопросы: <что осталось непроверенным> ``` После следующего исправления агента предложи добавить новую граблю — это самый прямой способ улучшать скилл. ## Грабли - **Начал писать скилл до проверки задачи.** В скилл попадёт гипотеза. Сначала шаг 0. - **Пересказал общие знания.** Проверка: каждая строка должна опираться на след задачи, а не на «так обычно делают». - **Описание в духе «помогает с…».** Непонятно, когда использовать. Формулируй «Используй этот скилл, когда…». - **«Когда использовать» осталось только в теле.** Агент до тела не дойдёт, если описание не сработало. - **Меню вместо выбора.** Пять вариантов без default дают непредсказуемый результат. Выбери один. - **Команды перепечатаны по памяти.** Флаг или кавычки теряются. Копируй из истории запусков и проверяй. - **Абсолютные пути своей машины.** Скилл должен работать у другого пользователя. Пути — относительные от корня скилла или проекта. - **Секреты и приватные данные в примерах.** Токены, ключи, персональные данные — вырезать. - **Раздутый `SKILL.md`.** Больше 500 строк — выноси в `references/`. Лишние инструкции не нейтральны: их всё равно могут исполнить. - **`references/` без условия чтения.** «Смотри references/» бесполезно. Пиши, когда именно читать каждый файл. - **Вложенные ссылки.** `SKILL.md` → файл → файл: агент может не дойти. Один уровень вглубь. - **Дубликат существующего скилла.** Сначала посмотри, что уже установлено, — дополни, а не плоди. - **Скрипт ждёт ввода.** Агент работает в неинтерактивной среде и зависнет. Только флаги, аргументы и stdin. - **Не проверил срабатывание.** Скилл может ни разу не загрузиться. Проверь описание на запросах. - **Не сравнил с базой.** Без прогона «без скилла» непонятно, есть ли польза. - **Соврал про тестирование.** Если прогонов не было — скажи об этом. Отчёт важнее красивого вида. - **Описание на чужом языке.** Наблюдение: если пользователи пишут по-русски, русское описание обычно срабатывает лучше; для международного скилла — английское. Это стоит проверить на своих запросах, а не считать доказанным правилом. - **Забыл версию и историю изменений.** Если в проекте приняты `metadata.version` и `CHANGELOG.md`, обнови их. ## Чек-лист - [ ] Задача выполнена и проверена. - [ ] След собран: шаги, исправления, форматы, контекст, тупики. - [ ] Скилл описывает один связный класс задач. - [ ] Проверено, нет ли уже подходящего скилла. - [ ] `name` в kebab-case и совпадает с именем папки. - [ ] Описание по формуле, с косвенными ситуациями, не длиннее 1024 символов. - [ ] Каждая строка проходит аудит «агент ошибся бы без неё?». - [ ] Хрупкие действия — точными командами; гибкие — с причинами; выбран default. - [ ] Грабли записаны в формате «симптом — причина — что делать». - [ ] Подробности в `references/`, у каждого файла указано, когда читать. - [ ] Тело меньше 500 строк и 5 000 токенов. - [ ] Валидатор пройден; ссылки, команды и отсутствие секретов проверены. - [ ] Прогон на 2–3 задачах со скиллом и без; проверка триггеров или честная оговорка. - [ ] Отчёт с путём установки и открытыми вопросами. ## Справочники | Файл | Когда читать | |---|---| | `references/description.md` | пишешь или правишь `description` либо проверяешь срабатывание скилла | | `references/audit.md` | сокращаешь `SKILL.md`, проверяешь каждую строку, оформляешь грабли или команды | | `references/example.md` | нужен полный пример: как из выполненной задачи собрать скилл по шагам | ## Куда положить ``` / ├── SKILL.md ├── references/ ├── scripts/ ├── assets/ ├── README.md # необязательно: для человека └── CHANGELOG.md # необязательно: что менялось и почему ``` В DSH скиллы проекта лежат в `.dsh/skills//`. У других клиентов наборы каталогов шире: VS Code с Copilot — проектные `.github/skills/`, `.claude/skills/`, `.agents/skills/` и личные `~/.copilot/skills/`, `~/.claude/skills/`, `~/.agents/skills/`; Claude Code — `.claude/skills/` и `~/.claude/skills/`. Проверь документацию клиента и скажи пользователю точный путь установки.