Скиллы

Скилл — каталог с SKILL.md в skills_dir. В системный промпт едет только его название и описание; тело агент читает, когда скилл понадобился.

Формат SKILL.md

YAML front-matter и markdown-тело, как у плагинов Claude/Anthropic.

---
name: deploy
description: Как выкладывать сборку — шаги, проверки, откат
---

# deploy

1. Собери: `scripts/build.sh`
2. Проверь: `scripts/check.sh`
3. Выложи: `scripts/publish.sh`

Откат и грабли — `references/rollback.md`.

Обязательны только name и description. description — то, по чему агент решает, нужен ли скилл: «Как работать над X» полезнее, чем «про X».

Если name пуст или front-matter отсутствует, ядро берёт имя каталога, а описание останется пустым — такой скилл в оглавлении выглядит строкой без смысла и не читается никогда.

Что попадает в промпт

Оглавление: по строке на скилл, отсортировано по имени, плюс путь к skills_dir.

Скиллы (/home/me/.local/share/snens/skills) — как работать в незнакомой части
проекта: прочитай подходящий прежде чем действовать, рядом с ним могут быть
references/ с деталями и scripts/ для запуска.
- deploy: Как выкладывать сборку — шаги, проверки, откат
- harness: Как работать над snens

Тело в префикс не едет. Плата за все тела каждый ход выше, чем цена одного чтения по требованию; при этом скилл, о котором агент не знает, не существует — поэтому оглавление обязательно, а текст — нет.

Оглавление собирается при каждой сборке промпта: новый скилл виден со следующего хода, перезапуск не нужен. Пустой skills_dir не добавляет ничего.

references/ и scripts/

• references/*.md — детали на уровень глубже: длинные таблицы, разбор грабель, то, что не нужно при каждом обращении к скиллу.
• scripts/* — исполняемые проверки и хелперы: скилл может не объяснять процедуру словами, а запускать её.

Разделение: в SKILL.md — маршрут и то, без чего нельзя начать; в references/ — всё, что читается по одному разу в десять сессий.

Как скилл появляется

Сначала — тикет. Первое появление неудобства (тул путает контракт, вызов пришлось повторять, вывод пришлось дочитывать) фиксируется тикетом с hits: 1, и больше ничего не происходит.

Второй раз то же самое — тикет с hits ≥ 2, и это работа snens improve: строка в подходящий скилл, процедура или грабли. По ходу разговора скиллы не пишутся: одна сессия не знает, повторяется ли проблема.

Скилл — это данные, а не код: чтобы добавить возможность, достаточно каталога с SKILL.md. Класть его можно и в git рядом с проектом, на который он ссылается, — тогда скилл версионируется вместе с кодом, который описывает.

Проверить

ls ~/.local/share/snens/skills             # что установлено
head -5 ~/.local/share/snens/skills/*/SKILL.md   # front-matter на месте

Оглавление не появилось — проверь, что файл называется ровно SKILL.md и лежит в каталоге первого уровня skills_dir.

Дальше: файлы инстанса · свои инструменты