Clear Writing gives AI agents practical guidance for writing and editing in English and Russian. Use it to make emails, documentation, articles, reports, presentations, and UI copy easier to understand without losing meaning.
Clear Writing — скилл с практическими правилами письма и редактуры для AI-агентов. Помогает сделать письма, документацию, статьи, отчёты, презентации и тексты интерфейса понятнее, сохранив смысл. Работает с русским и английским текстом.
- Organize the message. Put the reader's question first, choose a useful structure, and explain unfamiliar ideas with examples.
- Remove clutter. Replace bureaucratic phrasing and vague claims with direct language. Keep the detail the reader needs.
- Preserve meaning. Keep facts, conditions, negation, uncertainty, numbers, and deadlines. Do not invent missing information.
- Use the right language. Each language has a complete guide. Editing keeps the source language unless translation is requested; bilingual work uses both guides.
- Clarify technical steps. Technical profiles cover prerequisites, conditions, consistent terms, warnings, and observable results: STE-informed English and plain technical Russian. They do not certify compliance with a standard.
The skill contains instructions and reference material for an AI agent. It needs no books or external summaries. For Russian and English prose, it also includes an optional, offline Python 3.9+ checker for Cleanliness and Readability. Its JSON report highlights review phrases and long sentences. The scores are Clear Writing indicators, not Glavred scores or a verdict on the text. See the method and limits.
python3 skills/clear-writing/scripts/check_text.py --language en --file article.txtFor substantive prose, the skill also requests a separate editor agent when the host supports and permits delegation. The editor checks the source, proposes a revision, and interprets local metrics; the writer verifies the changes. Reviews are bounded to one pass and, for a remaining critical issue, one focused recheck. Without agent delegation, the skill uses self-review and does not claim independent review. See the editor contract.
After installation, ask your agent:
Use $clear-writing to edit this customer email.
Keep the deadline and the condition. Return only the edited text.
"We would like to inform you that if payment is not received by 15 October,
access to the service will be suspended."
Example edit:
If we do not receive payment by 15 October, we will suspend access to the service.
For other tasks, provide the text or source facts, describe the reader, and specify what must stay unchanged. For example: “Explain this API to a junior developer” or “Restructure this report so the decision comes first.”
$clear-writing explicitly invokes the skill in Codex. Other agents may use different invocation syntax.
For technical writing, try:
Use $clear-writing to simplify these instructions. Keep the labels and restrictions.
If the status is Ready, perform a click on Export and wait for Complete.
If the status is Failed, retries are prohibited. Return only the edited instructions.
The English profile draws on ASD-STE100 Issue 9. It does not include the full standard or its approved dictionary. The Russian profile is an independent adaptation, not an official Russian STE equivalent; it draws on the cross-language principles of ISO 24495-1:2023. Ordinary emails and articles still use the general guide.
With Node.js and npm installed, run this from your project directory:
npx skills add serge-masiutin/clear-writing --skill clear-writingThe skills CLI lets you choose the target agent. To install for Codex or Claude Code explicitly:
npx skills add serge-masiutin/clear-writing --skill clear-writing -a codex
npx skills add serge-masiutin/clear-writing --skill clear-writing -a claude-codeChoose the command for your agent. Add -g to make the skill available across your projects. If clear-writing is already installed, check your local changes before replacing it.
Alternatively, use Git and copy the complete skill folder into your agent's skills directory. For a project using .agents/skills (POSIX shell):
git clone https://github.com/serge-masiutin/clear-writing.git clear-writing-source
mkdir -p .agents/skills
test ! -e .agents/skills/clear-writing && \
cp -R clear-writing-source/skills/clear-writing .agents/skills/clear-writingThe copy runs only if the destination does not exist. Copy the whole folder: SKILL.md links to the guides and references beside it. Follow your agent's instructions for loading newly installed skills.
Start with SKILL.md, which tells the agent which guide to read. Each edition includes:
| Material | English | Russian |
|---|---|---|
| Complete guide | Guide | Руководство |
| Technical profile | STE-informed English | Технический русский |
| Editing techniques | Patterns | Приёмы |
| Decision table | Cheatsheet | Шпаргалка |
| Terminology | Glossary | Словарь |
| Behavioral review | Cases | Случаи |
Six topic chapters cover the reader, wording, evidence, structure, presentation, and writing formats. The agent loads the relevant chapters as needed.
To change the skill, follow the localization review and work through the review cases in both languages. These are manual checks; they do not replace reviewing the agent's output for your task.
Repository maintenance and isolated GitHub access are documented in development. For a before/after comparison, use the technical evaluation procedure (both in Russian).
The guidance draws on «Пиши, сокращай» by Maxim Ilyakhov and Lyudmila Sarycheva (4th edition, 2024) and «Ясно, понятно» by Maxim Ilyakhov (2021). This is an independent adaptation, not an official skill by the authors. The books are not included; the rules and teaching examples were written for this skill.
MIT license, copyright © 2026 Serge Masiutin. A copy of the license is included inside the installable skill folder.
- Выстроить объяснение. Начать с вопроса читателя, выбрать подходящую структуру и пояснить незнакомые идеи примерами.
- Убрать лишнее. Заменить канцелярит и расплывчатые оценки прямыми формулировками. Сохранить подробности, которые нужны читателю.
- Сохранить смысл. Не потерять факты, условия, отрицания, степень уверенности, числа и сроки. Не выдумывать недостающие сведения.
- Выбрать язык. Для каждого языка есть полное руководство. При редактуре язык исходника сохраняется, если перевод не запрошен; для двуязычного текста используются оба руководства.
- Уточнить технические шаги. Отдельные профили помогают явно описать подготовку, условия, термины, предупреждения и проверяемый результат: STE-ориентированный английский и ясный технический русский. Это не сертификация по стандарту.
Скилл состоит из инструкций и справочных материалов для AI-агента. Книги и внешние конспекты для работы не нужны. Для русской и английской прозы в нём также есть необязательная локальная проверка на Python 3.9+: «Чистота» и «Читаемость». JSON-отчёт указывает фразы для проверки и длинные предложения. Это собственные показатели Clear Writing, а не баллы Главреда или итоговая оценка текста. См. методику и ограничения.
python3 skills/clear-writing/scripts/check_text.py --language ru --file article.txtДля содержательных текстов скилл также подключает отдельного агента-редактора, если среда поддерживает и разрешает делегирование. Редактор сверяет текст с исходником, предлагает правки и учитывает локальные метрики; основной агент проверяет изменения. Предусмотрен один проход и, при оставшейся критической ошибке, одна прицельная повторная проверка. Без делегирования скилл проводит самопроверку и не называет её независимой. См. контракт редактора.
После установки попросите агента:
Используй $clear-writing, чтобы отредактировать письмо клиенту.
Сохрани срок и условие. Верни только чистовой текст.
«Настоящим уведомляем вас о том, что в случае непоступления оплаты
до 15 октября доступ к сервису будет приостановлен».
Пример редактуры:
Если оплата не поступит до 15 октября, мы приостановим доступ к сервису.
Для других задач передайте текст или исходные факты, опишите читателя и укажите, что нельзя менять. Например: «Объясни этот API начинающему разработчику» или «Перестрой отчёт: начни с решения».
$clear-writing явно вызывает скилл в Codex. У других агентов синтаксис вызова может отличаться.
Для технического текста попробуйте:
Используй $clear-writing: упрости инструкцию, сохрани подписи и ограничения.
Если статус Ready, осуществите нажатие Export и дождитесь статуса Complete.
Если статус Failed, повтор запрещён. Верни только чистовую инструкцию.
Английский профиль опирается на ASD-STE100 Issue 9, но не включает полный стандарт и его утверждённый словарь. Русский — самостоятельная адаптация, а не официальный аналог STE; общая опора — межъязыковые принципы ISO 24495-1:2023. Обычные письма и статьи по-прежнему используют общее руководство.
Установите Node.js и npm, затем выполните в каталоге своего проекта:
npx skills add serge-masiutin/clear-writing --skill clear-writingУстановщик skills предложит выбрать агента. Чтобы явно указать Codex или Claude Code:
npx skills add serge-masiutin/clear-writing --skill clear-writing -a codex
npx skills add serge-masiutin/clear-writing --skill clear-writing -a claude-codeВыберите команду для своего агента. Добавьте -g, чтобы скилл был доступен во всех ваших проектах. Если clear-writing уже установлен, перед заменой проверьте свои локальные правки.
Другой способ — клонировать репозиторий через Git и скопировать папку скилла целиком. Для проекта, который использует .agents/skills, выполните в POSIX-совместимой оболочке:
git clone https://github.com/serge-masiutin/clear-writing.git clear-writing-source
mkdir -p .agents/skills
test ! -e .agents/skills/clear-writing && \
cp -R clear-writing-source/skills/clear-writing .agents/skills/clear-writingКопирование выполнится, только если папки назначения ещё нет. Копируйте папку целиком: SKILL.md ссылается на руководства и справочники внутри неё. Для подключения нового скилла следуйте инструкции вашего агента.
Начните с SKILL.md: он указывает агенту, какое руководство читать. В каждой языковой версии есть:
| Материал | Русский | English |
|---|---|---|
| Полное руководство | Руководство | Guide |
| Технический профиль | Технический русский | STE-informed English |
| Приёмы редактуры | Приёмы | Patterns |
| Таблица выбора | Шпаргалка | Cheatsheet |
| Термины | Словарь | Glossary |
| Проверка поведения | Случаи | Cases |
Шесть тематических глав посвящены читателю, формулировкам, доказательствам, структуре, подаче и форматам текста. Агент читает нужные главы по мере работы.
При изменении скилла пройдите проверку локализации и контрольные случаи на обоих языках. Это ручные проверки; они не заменяют оценку ответа агента в вашей задаче.
Проверки репозитория и изолированный вход GitHub описаны в руководстве по разработке. Для сравнения старой и новой редактуры используйте порядок проверки технического профиля.
В основе — подходы из книг «Пиши, сокращай» Максима Ильяхова и Людмилы Сарычевой (4-е издание, 2024) и «Ясно, понятно» Максима Ильяхова (2021). Это самостоятельная адаптация, а не официальный скилл авторов. Книги в состав скилла не входят; правила и учебные примеры написаны для него.
Лицензия MIT, © 2026 Serge Masiutin. Копия лицензии включена в устанавливаемую папку скилла.