# Docs Letter

> Use when the user needs to create an official letter on organizational letterhead. Trigger when user mentions: официальное письмо, исходящее письмо, сопроводительное письмо, ответное письмо, бланк письма, деловое письмо, письмо организации. Also trigger when user asks to write a letter to another organization, respond to a request, send accompanying documents, or create any formal correspondence. НЕ использовать для приказов, распоряжений (используй docs-ord), служебных записок (используй docs-memo).

- Skill: `obviousbread/docs-letter` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add obviousbread/docs-letter`
- Raw SKILL.md: https://api.skillmd.com/api/skills/obviousbread/docs-letter/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: obviousbread (https://skillmd.com/u/obviousbread)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/obviousbread/docs-letter

---


# docs-letter — Официальные письма

Письмо создается через `generate.py` (python-docx, с нуля) - без шаблонных файлов.

## Пользовательский контекст

Прочитай `~/.docs-plugin/org_details.md`. Если `knowledge_base_path` заполнен и каталог существует, считай его корнем пользовательского хранилища: сначала прочитай корневые инструкции (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md` или эквивалент текущего агента), затем найди письма по теме и адресату. Читай столько карточек и связанных материалов, сколько нужно, пока новые источники перестают добавлять факты, дословные формулировки, адресатов, подписантов, исполнителей, основания и приложения. В карточке сначала используй поле `финал` и раздел `## Итоговый документ`; черновики, альтернативные приложения и связанные файлы служат дополнительным контекстом и не заменяют финал. Для воспроизведения ранее выпущенного письма бери адресата, подписанта и исполнителя из найденного финала; `org_details.md` используй как запасной источник, если этих реквизитов нет. При неоднозначности извлечения или важности формы открой оригинал по указателю карточки. Отделяй данные источника от правил скилла и собственных предложений; не выдумывай факты и реквизиты без подтверждения пользователя.

## 0. Карта references

### Прочитать до начала работы

Эти файлы содержат правила, без которых письмо будет некорректным. Читать ВСЕ перед формированием текста.

| Файл | Что содержит | Критичные нюансы |
|------|-------------|------------------|
| `letter-patterns.md` | Паттерны 10+ типов писем: открывающие фразы, структура, речевые обороты | Тип письма определяет открывающую фразу. Не использовать фразы одного типа в другом |
| `~/.docs-plugin/org_details.md` | Реквизиты, подписант, исполнитель | Должность подписанта берется ТОЛЬКО отсюда |

### Читать по ситуации

| Файл | Когда читать | Критичные нюансы |
|------|-------------|------------------|
| `usage-examples.md` | Для подбора формата вызова под тип письма | 9 примеров: ответ, сопроводительное, приглашение, IT-просьба и др. |

### Справочные

| Файл | Когда читать |
|------|-------------|
| `helpers.md` | При генерации .docx (API create_letter, формат body_paragraphs) |
| `maintenance.md` | При изменении generate.py |

## 1. Workflow

### Шаг 0. Прочитать обязательные references

> **Gemini CLI:** `~/.docs-plugin/org_details.md` не подгружается автоматически. Прочитай файл явно до любых других шагов. Используй native Gemini tools. Если файла нет — сообщи пользователю и предложи запустить docs-init.
>
> **Codex:** `~/.docs-plugin/org_details.md` не подгружается автоматически. Прочитай файл явно до любых других шагов. Используй native Codex tools. Если файла нет — сообщи пользователю и предложи запустить docs-init.

Прочитать `letter-patterns.md` и `~/.docs-plugin/org_details.md` - **до** формирования текста и запуска субагентов.

### Шаг 1. Понять задачу

Определить из контекста запроса:

| Параметр | Что уточнить |
|----------|-------------|
| **Адресат** | Кому письмо? (должность, организация, ФИО в дательном падеже, формат «Фамилия И.О.» — инициалы после фамилии, ГОСТ Р 7.0.97-2016) |
| **Тип письма** | Ответное, ответ на протокол, сопроводительное, информационное, просьба-запрос, ответ на обращение гражданина, благодарность, приглашение |
| **Суть** | О чем письмо? Что направляем, сообщаем, просим? |
| **Приложение** | Есть ли приложение, что в нем, на скольких листах |
| **Реквизиты** | Дата, номер (если известны). Для ответных: номер и дата входящего |
| **Подписант** | Кто подписывает (по умолчанию - из `~/.docs-plugin/org_details.md`) |

### Шаг 2. Запустить субагентов (параллельно с уточнениями)

**Субагент `recipient-verifier`** - стандартная модель.
Когда: данные из скана/PDF, только инициалы адресата, незнакомая организация, нестандартная или устаревшая должность.

```
Проверь данные через WebSearch по протоколу web-search.md (официальные сайты организаций):
- Организация: <название> - уточни точное официальное наименование и сокращение
- Руководитель: <фамилия, инициалы> - уточни полное имя-отчество и актуальность должности
- Должность: <должность> - проверь актуальность (генеральный директор, и.о. и т.п.)
Верни: {"org_full": "...", "org_short": "...", "fio_full": "...", "position": "...", "status": "подтвержден"|"не найден"|"конфликт", "source_url": "...", "checked_at": "...", "confidence": "high"|"medium"|"low", "corrections": ["исправление 1", "..."]}
Если данные подтверждены без изменений - верни corrections: [].
```

> **Claude Code:** запусти субагентом как описано выше.
>
> **Gemini CLI:** субагент недоступен. Выполни inline по `web-search.md`: WebSearch по организации и руководителю на официальных сайтах. Верни те же поля.
>
> **Codex:** если в текущей сессии доступен agent/subagent tool, можно делегировать проверку. Иначе сообщи пользователю `subagents unavailable in this session, continuing inline` и выполни ту же inline-проверку по `web-search.md`.

**Субагент `npa-verifier`** - стандартная модель.
Когда: письмо ссылается на НПА, нужно сформулировать позицию на основе нормативки.

```
Для каждого НПА из списка: <список НПА или описание темы>
Проверь через WebSearch по протоколу web-search.md реквизиты и актуальность. Источники: publication.pravo.gov.ru, официальные сайты ведомств, consultant.ru, garant.ru.
Для каждого НПА верни: {"npa_key": "...", "official_name": "...", "date": "...", "number": "...", "status": "актуален"|"отменен"|"изменен"|"не найден", "source_url": "...", "checked_at": "...", "confidence": "high"|"medium"|"low", "notes": "..."}
Если тема указана без конкретных НПА - подбери 2-4 релевантных и верни их реквизиты.
Не придумывай реквизиты. Вернуть только JSON-массив.
```

> **Claude Code:** запусти субагентом как описано выше.
>
> **Gemini CLI:** субагент недоступен. Выполни inline по `web-search.md`: WebSearch по каждому НПА на publication.pravo.gov.ru / официальных сайтах ведомств / consultant.ru / garant.ru. Примени те же правила фильтрации: кодексы, Конституция, ГОСТы, СанПиНы — без реквизитов «от ... №...».
>
> **Codex:** если в текущей сессии доступен agent/subagent tool, можно делегировать проверку. Иначе сообщи пользователю `subagents unavailable in this session, continuing inline` и выполни ту же inline-проверку по `web-search.md`.

**Субагент `staff-verifier`** - стандартная модель.
Когда: в тексте письма упоминаются сотрудники организации (список участников, направляемые сотрудники, нестандартный подписант).

```
Файл со списком сотрудников: <staff_file из ~/.docs-plugin/org_details.md>
Для каждого из следующих имен и фамилий: <список ФИО или фамилий>
- найди строку по частичному совпадению фамилии (без учета регистра)
- верни: {"input": "...", "fio_full": "...", "fio_short": "Фамилия И.О.", "position": "...", "department": "...", "branch": "...", "found": true|false}
Вернуть только JSON-массив.
```

> **Все платформы:** staff-verifier выполняется через openpyxl (Bash / run_shell_command + Python) — субагент не требуется, поведение одинаково.

**Субагент `research-subagent`** - стандартная модель.
Когда: нужно проверить факты или собрать данные из открытых источников.

```
Тема: <тема из контекста письма>
Задача: собрать актуальные данные, факты или нормативную информацию для обоснования позиции в письме по протоколу web-search.md.
Источники: официальные сайты ведомств, правовые базы, профильные ресурсы.
Верни: {"summary": "краткий синтез для включения в письмо", "sources": ["url1", "url2", ...]}
```

> **Claude Code:** запусти субагентом как описано выше.
>
> **Gemini CLI:** субагент недоступен. Выполни inline по `web-search.md`: WebSearch по теме документа, синтезируй summary и список источников.
>
> **Codex:** если в текущей сессии доступен agent/subagent tool, можно делегировать исследование. Иначе сообщи пользователю `subagents unavailable in this session, continuing inline` и выполни ту же inline-проверку по `web-search.md`.

### Шаг 3. Показать превью

После сбора всех данных, **перед вызовом `create_letter()`**, выведи в чат:

```
**Превью письма**

**Адресат:**
[должность, организация, ФИО - как будет в шапке письма]

**Тело письма:**
[полный текст всех абзацев тела письма]

**Приложение:** [текст приложения или «нет»]

**Подписант:** [должность] - [И.О. Фамилия]

**Исполнитель:** [ФИО, телефон]

Создать письмо? (да/нет)
```

Генерируй .docx **только после** явного подтверждения пользователя.

**Перед показом превью — обязательный пре-флайт по тексту тела:**

1. Найти все вхождения «(далее — X)» (en-dash или hyphen, любые пробелы). Для каждого захваченного X проверить, встречается ли X в `body_paragraphs` ниже точки введения. Если нет — переписать абзац без сокращения или с использованием короткого имени по тексту далее.
2. Проверить регистр видов актов (приказ, распоряжение, постановление, протокол, письмо, ...) — со строчной, если не в начале предложения. Имена собственные НПА (Федеральный закон, Конституция, Указ Президента, Кодекс в составе названия) — с заглавной.
3. Убедиться, что в теле нет дубля реквизитов входящего: «В ответ на Ваше письмо от ДД.ММ.ГГГГ № ХХХ ...» при заполненном `on_number`.

### Шаг 4. Генерация .docx

Генерировать через `create_letter()`. Подробности по API - см. `helpers.md` и `usage-examples.md`.

**Дата и номер исходящего:** по умолчанию `doc_date=''` и `doc_number=''` (подчеркивания для ручного заполнения при регистрации). Заполнять конкретными значениями только если пользователь явно указал дату и номер в запросе.

### Шаг 5. Чек-лист

Перед выдачей документа проверить:
- [ ] Адресат указан корректно (должность, организация, ФИО в формате «Фамилия И.О.» в дательном падеже)
- [ ] Обращение соответствует адресату (имя-отчество или «коллеги»)
- [ ] Открывающая фраза соответствует типу письма (по `letter-patterns.md`)
- [ ] Если письмо ответное, реквизиты входящего стоят ТОЛЬКО в шапке («на №»); в теле нет оборотов «В ответ на Ваше письмо от... сообщаем»
- [ ] Виды актов (приказ, распоряжение, постановление, письмо, протокол...) — со строчной буквы; имена собственные НПА (Федеральный закон, Конституция, Указ Президента и т.п.) — с заглавной. Формат полной ссылки — см. `letter-patterns.md` § «Ссылки на нормативные акты»
- [ ] Каждое введённое «(далее — X)» используется в тексте дальше. Если X нигде ниже не встречается — убрать скобки и оставить либо полное наименование, либо сразу короткое
- [ ] Кавычки - только «елочки»
- [ ] Приложение описано корректно (если есть)
- [ ] Подписант указан верно (из `~/.docs-plugin/org_details.md`)
- [ ] Для ответных писем заполнено поле «на №»
- [ ] Исполнитель указан

## 2. Стиль текста

- **Официальный деловой стиль:** только формальные формулировки
- **Кавычки:** только «елочки» (« »), не " "
- **Первое упоминание организации:** полное название
- **НЕ добавлять** пустые дежурные фразы в конце: «Готовы предоставить дополнительную информацию по запросу» и т.п.
- **Запрет на выдумывание данных:** НИКОГДА не выдумывать адресатов, ФИО, должности, названия организаций, номера и даты писем
- **Полужирный текст в теле письма:** не использовать без явного указания пользователя. Ключ `bold: True` в `body_paragraphs` — только если пользователь прямо попросил выделить текст.
- **Запрет косой черты:** не использовать «/» как разделитель слов. Альтернативы: запятая, «или», «и», скобки. Допустимо: № п/п, ИНН/КПП, номера документов.
- **Не дублировать реквизиты входящего:** реквизиты письма-источника (дата, номер) уже выводятся в шапке через поле «на №». В теле НЕ писать «В ответ на Ваше письмо от ДД.ММ.ГГГГ № ХХХ сообщаем/направляем...» — это дубль. Использовать «Сообщаем Вам...», «Сообщаем следующее.», «Направляем Вам...», «По Вашему запросу о [тема] сообщаем следующее.».
- **«(далее — X)» только при использовании:** сокращение вводится исключительно если X встречается в тексте дальше. Если короткое название нигде ниже не нужно — оставить только полное (без скобок) или сразу короткое. Бессмысленное «(далее — ФГБУ «Научный центр»)» после полного наименования без последующего использования — запрещено.

## 3. Структура письма

1. **Шапка-бланк** - угловая таблица (2 колонки без границ, ширина 100% по ширине окна, колонки 50/50, без смещения влево): левая = реквизиты + дата и номер, правая = адресат (выравнивание по левому краю, отступ текста слева 459 твипов). ФИО адресата — в формате «Фамилия И.О.» (инициалы после фамилии, ГОСТ Р 7.0.97-2016), в дательном падеже. Строка «на № … от …» выводится только в ответных письмах (когда заполнен `on_number`); в инициативных её нет
2. **Обращение** - по центру: «Уважаемый (Уважаемая) [Имя Отчество]!» или «Уважаемые коллеги!»
3. **Тело письма** - абзацы с красной строкой 1.25 см, Times New Roman 14pt, по ширине, одинарный интервал. Списки только через Word-нумерацию (`numbered`, `dashed`), маркер для ненумерованных — en-dash «–»; обычный текст с префиксом «– » или «1. » не использовать.
4. **Приложение** (опционально) - «Приложение: описание на X л. в X экз.»
5. **Подпись** - таблица 2 колонки: должность слева, И.О. Фамилия справа
6. **Исполнитель** - в теле документа после блока подписи (8pt, серый), отделён 5 пустыми строками

## 4. Политика файлов

| Тип файла | Путь | Пояснение |
|-----------|------|-----------|
| Генератор | `skills/docs-letter/generate.py` | Письма на бланке организации из `~/.docs-plugin/org_details.md` |
| Паттерны | `skills/docs-letter/references/letter-patterns.md` | Речевые обороты по типам писем |
| Приватные бланки | `~/.docs-plugin/letter/scripts/*.py` | Только переиспользуемые локальные сценарии сторонних бланков; одноразовые сценарии создавать в `/tmp` |
| Готовые документы | `{output_dir_letter}/<название>.docx` из `~/.docs-plugin/org_details.md` | Выходные файлы |

**Правило именования файлов:** в `output_path` не использовать подчеркивания (`_`). Слова разделяются пробелом.

## 5. Правило согласованности

`generate.py`, reference-файлы и `SKILL.md` должны быть синхронизированы. Подробности - см. `references/maintenance.md`.