Doc2md

---
name: doc2md
description: Конвертирует Word, PowerPoint, Excel, OpenDocument, RTF, EPUB, CSV и PDF в чистый Markdown ДО того, как агент начинает читать документ — один файл, список файлов или целая папка разом. Используй, когда нужно разобрать пачку разноформатных документов (договоры, акты, презентации, выгрузки), когда штатный ридер под формат либо отсутствует, либо избыточен для простой пачки, или когда документов больше 2-3 и дешевле прогнать всё разом, чем открывать по одному. Триггеры — "сконвертируй эти файлы", "разбери пачку документов", "не могу прочитать этот файл", "переведи в markdown", "подготовь документы для агента".
license: MIT
metadata:
  author: ilyautov
  version: 1.2.0
  based_on: firecrawl/anydoc (MIT)
---

# doc2md — конвертация документов в Markdown до чтения агентом

## Зачем

Агент обычно читает `.docx`, `.xlsx`, `.pptx`, `.pdf` каждый своим отдельным ридером — на пачке из 10-20 файлов это десятки лишних вызовов инструментов и разный формат вывода под каждый тип. doc2md прогоняет всё через один конвертер и на выходе всегда получается чистый GitHub-Flavored Markdown, независимо от того, что было на входе.

Это не замена скиллам `docx`/`pdf`/`xlsx`/`pptx` для точечной работы с одним файлом (правки, форматирование, извлечение изображений — там нужны они). doc2md — для случая «прочитать содержимое пачки документов и дальше с ней работать», особенно когда документов много и формат смешанный.

## Три способа подать файлы на вход

1. **Путь(и), которые назвал пользователь.** Передать как есть, можно несколько через пробел.
2. **Файл прислали в чат.** Cowork кладёт вложения в папку uploads текущей сессии — путь виден в системном контексте. Передать этот путь напрямую, отдельно скачивать не нужно.
3. **Целая папка.** Передать путь к папке — скрипт рекурсивно найдёт внутри всё поддерживаемое и сконвертирует.

## Быстрый старт

Основной, кросс-платформенный вариант (Windows/macOS/Linux, нужен только Node.js — он и так требуется для `npx`/anydoc):

```bash
node <папка скилла>/scripts/convert.js договор.docx
node <папка скилла>/scripts/convert.js ~/Downloads/акты/ -o ~/Downloads/акты-md/
node <папка скилла>/scripts/convert.js a.pdf b.xlsx "отчёт за март.pptx"
```

На Unix (macOS/Linux/WSL/Git Bash) можно вызвать тот же конвертер через bash:

```bash
bash <папка скилла>/scripts/convert.sh договор.docx
```

Без `-o` каждый `<имя>.<расширение>.md` пишется рядом с исходником (например, `отчёт.docx` → `отчёт.docx.md`). С `-o папка/` результаты собираются в одном месте. Тёзки из разных подпапок получают суффикс пути, чтобы один результат не перезаписал другой.

Для одного файла и разового вызова можно и напрямую, без скрипта:

```bash
npx -y @firecrawl/anydoc report.docx -o report.docx.md
```

Скрипт `convert.js` нужен для пакетного случая (папка, список файлов) и для честной сводки по результатам, single-file вызов ничего не добавляет к прямому `npx`.

## Поддерживаемые форматы

| Группа | Расширения |
|---|---|
| Word | `.doc` `.docx` `.docm` |
| PowerPoint | `.ppt` `.pps` `.pot` `.pptx` `.pptm` `.ppsx` `.ppsm` |
| Excel | `.xls` `.xlsx` `.xlsm` `.xlsb` |
| OpenDocument | `.odt` `.ods` `.odp` |
| Прочее | `.rtf` `.epub` `.csv` `.pdf` |

## Что скрипт делает, а что нет

- Конвертирует файл(ы), печатает построчный статус (`OK` / `ПРОПУСК` / `ОШИБКА`) и итоговую сводку: сколько успешно, сколько пропущено, сколько ошибок вызова.
- **Различие ПРОПУСК vs ОШИБКА.** `OK` — код anydoc `0` и результат записан. `ПРОПУСК` — код `3`, PDF нужны OCR-страницы. Любой другой сбой чтения, конвертации, записи или вызова — `ОШИБКА` и ненулевой код всего пакета. В строку выводится stderr от anydoc.
- **Сканы и PDF-картинки без текстового слоя локальный режим не читает.** Такие файлы попадают в «ПРОПУСК», batch на этом не падает. Для них: сначала OCR через скилл `pdf` (шаг «сделать PDF searchable»), потом повторный прогон. У anydoc 0.2.4 есть `--ocr hosted`, но он отправляет весь документ в Firecrawl Parse; эта обёртка его не включает.
- Зашифрованные/защищённые паролем файлы — `ОШИБКА` с объяснением от anydoc; не отправляй их на OCR.
- Не удаляет и не трогает исходники. Повторный запуск может обновить ранее созданный `.md`.

> Содержимое файла передаётся через stdin, чтобы путь с пробелами и `%VAR%` не попадал в командную строку `cmd.exe` на Windows. Коды возврата взяты из `anydoc --help` версии 0.2.4.

## После конвертации

Для больших документов не пересказывай `.md` в контекст целиком — прочитай оглавление/начало, дальше ищи (grep) по конкретным разделам. На пачке из десятков файлов это ощутимая экономия токенов относительно построчного чтения каждого через штатный формат-специфичный ридер.

## Установка

Ничего ставить не нужно: `npx -y @firecrawl/anydoc` сам скачивает нужный бинарник под платформу при первом запуске (нужен Node 18+, в песочнице Cowork уже есть). Для постоянного использования без повторной загрузки каждый раз: `npm install -g @firecrawl/anydoc`.

## Протестировано (06.08.2026, песочница Cowork, Node 22, Linux/macOS)

- `.csv` с кириллицей → чистая GFM-таблица, без искажений.
- `.docx` с заголовком, абзацем и таблицей на русском → корректный Markdown, кириллица не потеряна.
- Папка с двумя файлами одного имени, разных расширений (`test.csv` + `test.docx`) → **найдена и починена коллизия имён** до релиза: без сохранения расширения в имени `.md` оба ложились в один файл и второй перезаписывал первый.
- Путь с пробелами и кириллицей в имени файла → работает.
- Несуществующий путь в списке аргументов → пропускается с понятным сообщением, batch не падает.
- `scripts/convert.js` (кросс-платформенная Node-версия): та же батарея тестов повторена и прошла — рекурсивный обход папки, коллизия имён, кириллица в `.docx`/`.csv`, вложенная подпапка, несуществующий путь.
- Синтаксис-гейт обеих версий (`node --check`, `bash -n`) и smoke-тесты (`--help`, несуществующий путь) гоняются в CI на каждый PR.

**Автоматический Windows CI прошёл 07.10.2026:** CSV и настоящий DOCX с пробелами и `%TEMP%` в имени, извлечение текста из DOCX и коллизии в `-o`. Установку скилла и боевую пачку на пользовательском Windows-компьютере ещё не проверяли; `.pptx`, `.xlsx`, `.pdf` и `.epub` тоже не тестировались вживую.

## Источник

Обёртка над [github.com/firecrawl/anydoc](https://github.com/firecrawl/anydoc) (MIT, Rust). По собственному бенчмарку авторов (⚠️ вендорские цифры, независимо не перепроверялись) против libreoffice/unstructured/markitdown/pandoc/docling/mammoth на 100 документах — anydoc первым местом по качеству на всех 14 форматах и на два порядка быстрее (медиана 4.4 мс/документ против 100+ мс у конкурентов). Апстрим публикует свой минимальный skill (`npx skills add firecrawl/anydoc`) — он умеет то же самое для одного файла за раз, без пакетной обработки, без сводки по batch и без русской документации. Этот скилл достраивает именно то, чего там нет.