writing-clearly — скилл для ясного и простого текста

writing-clearly — агентский скилл, который учит ИИ-агента писать и редактировать текст для людей простым понятным языком. Метод взят из двух книг инфостиля Максима Ильяхова: «Пиши, сокращай» (в соавторстве с Людмилой Сарычевой) и «Ясно, понятно». Скил работает с русским и английским и подходит Claude Code, pi, OpenCode и любому другому агенту, который понимает формат SKILL.md.

Главный принцип: сначала ясно, потом коротко

Скил начинает не с правки слов, а с читателя. Его базовое правило: текст сначала должен быть понятным, и только потом — коротким.

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

Скил почти не занимает контекста. Постоянно загружается только SKILL.md с воркфлоу и главными правилами. Подробные справочники с каталогами подгружаются по требованию — только когда они понадобились.

Когда скил срабатывает

Скил включается, когда агент пишет или правит любую прозу для человека:

• документацию и README;
• описание pull request и commit;
• отчёты и деловые письма;
• посты, анонсы, release notes;
• тексты ошибок и надписи в интерфейсе;
• объяснения, пересказы, ответы в чате.

Отдельный запрос не нужен. Понятный текст в скиле считается нормой по умолчанию, поэтому он применяется даже тогда, когда пользователь просто просит «напиши текст» и не называет стиль. Русский и английский равноправны.

Что скил не трогает: исходный код и имена идентификаторов, короткие заголовки коммитов, художественную литературу, юридические тексты, где нужна точная формулировка. Если пользователь явно попросил другой стиль — академический, SEO, поэтический — прямой запрос пользователя всегда главнее.

Воркфлоу из четырёх шагов

Шаг 0. Сначала читатель, потом текст

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

• Кто читает и что уже знает? Термин, привычный вам, может быть пустым для него. Фраза «EBITDA выросла на 15%» бесполезна тому, кто этого термина не знает.
• Где он встретит текст? README читают по диагонали в поисках «как запустить». Письмо открывают между двадцатью другими. Сообщение об ошибке — в раздражении.
• Что он должен сделать или понять? Если ответа нет, тексту рано существовать.
• Какое у него предубеждение? Читатель может заранее ждать плохого — и это лечится прямым признанием: назовите его сомнение и ответьте на него.

Дальше выбирается регистр: официальный для юридических документов, деловой для переписки, профессиональный для техдокументации, нейтральный для блогов, разговорный для чатов. Подробная шкала с признаками лежит в справочнике по «Ясно, понятно».

Шаг 1. Структура

• Главная мысль — в начале. В тексте, в каждом разделе, в каждом абзаце. Читатель, бросивший текст на любом абзаце, уносит с собой главное.
• Заголовок говорит тему и пользу, а не интригует. Проверка простая: если заголовок подходит к любому тексту на эту тему — он плохой. «Преимущества» → «Экономия 40% на отоплении». «Overview» → «What the tool does and when to use it».
• Одна мысль — один абзац, 3–5 предложений. Длиннее значит, что в абзац смешали две мысли. Делите.
• Проверка чтением по диагонали. Прочитайте только заголовки и первые предложения абзацев. Скелет аргумента должен быть виден.
• К каждому отвлечённому понятию — пример. В идеале пример и антипример. Если формулируете правило, покажите, как оно работает.

Шаг 2. Редактура

Дальше текст прогоняют через конкретные операции. Это ядро скила.

1. Убрать слова-паразиты. Вводный мусор («стоит отметить», «как известно»), паразиты времени («на сегодняшний день»), смягчения и вода. Удаляем — смысл сохраняется.
2. Оценки заменить фактами. «Качественный», «эффективный», «удобный», «профессиональный» без доказательства — главный убийца текста. Спрашивайте: из чего? сколько служит? насколько быстрее? Нет факта — удаляйте оценку.
3. Отглагольные существительные заменить глаголами. «Осуществление поддержки» → «поддерживаем». Детектор простой: «осуществление / проведение / обеспечение / оказание» + существительное — внутри спрятан глагол, достаньте его.
4. Пассивный залог заменить активным, назвав деятеля. «Было принято решение» → «мы решили». «Файл обрабатывается скриптом» → «скрипт обрабатывает файл». Пассив уместен, только когда деятель неизвестен или неважен: «Дом построен в 1905 году».
5. Канцелярит и заумь заменить простыми словами. «Данный» → «этот», «является» → тире, «верифицировать» → «проверить», «в целях» → «чтобы», «осуществлять деятельность» → «работать». Для английского: utilize → use, leverage → use, facilitate → help.
6. Эвфемизмы заменить прямыми словами. «Определённые сложности» → «серьёзные проблемы», «неоднозначный результат» → «провал», «оптимизация штата» → «увольнения». Правило: если после чтения читатель не понял, что проблема есть, — эвфемизм убран.
7. Убрать ничем не подкреплённые утверждения. «Всё больше людей…», «стремительно набирает популярность», «многие эксперты считают» — назовите число, исследование или человека либо удаляйте.
8. Близкие синонимы схлопнуть до самого сильного. «Долгого, нудного и утомительного» → «нудного», а ещё лучше — факт «два месяца». Осторожно с рефлексом тройки.
9. Одна мысль на предложение, синтаксис упростить. Ломайте конструкции «не только… но и…» с длинными частями, цепочки причастий длиннее трёх слов, вложенные «который». Максимум одно «который» на предложение.
10. Типографика. «Ёлочки», длинное тире, буква «ё», правильные знаки препинания в списках.

Частые случаи сведены в таблицу:

Шаг 3. Самопроверка

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

Как это выглядит на практике

В репозитории лежит каталог пар «до и после» по типам текста. Он нужен, чтобы откалибровать глубину правки. Вот два примера из него.

Описание pull request

Было:

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

Стало:

Ускорил выборку заказов: заменил N+1-запросы на один JOIN — страница списка открывается за 200 мс вместо 1,5 с. Заодно добавил повтор запроса при обрыве соединения: раньше падало с 500-й, теперь переживает рестарт базы.

Что произошло: пассив превратился в первое лицо, «оптимизация» и «ряд улучшений» — в конкретные действия с цифрами, «повышение стабильности» — в конкретный сценарий отказа.

Сообщение об ошибке

Было:

Произошла непредвиденная ошибка при осуществлении операции. Пожалуйста, попробуйте повторить попытку позднее или обратитесь к администратору системы.

Стало:

Не удалось сохранить файл: нет прав на запись в папку /backups.

Дайте права командой chmod +w /backups или выберите другую папку.

Что произошло: «непредвиденная ошибка при осуществлении операции» стала конкретным описанием того, что не получилось и почему, а бесполезное «попробуйте позднее» — конкретным действием.

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

Что лежит в репозитории

Проверка качества: eval-цикл

Скил прошёл проверку на пяти реалистичных заданиях. Каждое задание прогоняли дважды: с чистым агентом и с агентом вместе со скилом. Задания — раздел README, описание pull request, редактура канцелярского абзаца, англоязычный анонс для нетехнических читателей и письмо команде о переносе релиза.

Автопроверки в evals.json проверяют три вещи: запрет канцелярита регулярными выражениями, сохранение фактов и команд из задания, главная мысль в первых строках. Это внешний контроль по правилам, а не самопроверка агента, поэтому результаты двух прогонов можно сравнить.

Установка

В Claude Code:

git clone https://github.com/fockus/writing-clearly ~/.claude/skills/writing-clearly

Чтобы один скил обслуживал сразу Claude Code, pi и OpenCode, склонируйте репозиторий в общий каталог и разложите симлинки:

git clone https://github.com/fockus/writing-clearly ~/.agents/skills/writing-clearly

ln -s ~/.agents/skills/writing-clearly ~/.claude/skills/writing-clearly
ln -s ~/.agents/skills/writing-clearly ~/.pi/agent/skills/writing-clearly
ln -s ~/.agents/skills/writing-clearly ~/.config/opencode/skills/writing-clearly

Обновление общего каталога обновляет скил сразу во всех агентах.

Источники и лицензия

Принципы взяты из книг Максима Ильяхова «Пиши, сокращай» (в соавторстве с Людмилой Сарычевой) и «Ясно, понятно». Короткие пары «плохо — хорошо» — это канонические примеры инфостиля из этих книг и из сервиса Главред. Авторы книг к проекту отношения не имеют, скил — независимый конспект метода.

Часть каталогов правил заимствована из talkstream/ru-text (MIT). Структура редакторского воркфлоу вдохновлена скилом ru-editor из репозитория miolamio/claude-skills, содержимое переписано.

Лицензия — MIT.