doc2md: 81% menos tokens ao processar documentos com agentes de IA
Existe um custo que a maioria ignora até ver a fatura. Quando você manda um PDF direto para um agente processar, ele não "lê" o arquivo — ele consome a estrutura binária inteira: layout, fontes, metadados, camadas de formatação. O conteúdo que você queria está lá no meio, mas você pagou por tudo ao redor. O doc2md resolve isso antes que o agente sequer abra a boca.
A biblioteca por baixo: markitdown da Microsoft
Antes de qualquer outra coisa: eu não inventei a conversão para Markdown. Quem faz o trabalho pesado é o markitdown — biblioteca open source da Microsoft que roda localmente via terminal, sem API, sem nuvem.
O que eu fiz foi envelopar essa biblioteca numa skill de agente de IA. A diferença é de contexto: em vez de passar parâmetros manualmente toda vez, padronizei o processo para o meu fluxo de trabalho — pasta .raw-docs/ como entrada, pasta docs/ como saída, cache para não reprocessar o que já foi convertido, integração direta com o graphify para os projetos de código.
O crédito da conversão é da Microsoft. A skill é a camada de conveniência em cima disso.
Por que Markdown virou a língua franca dos agentes
Markdown é texto limpo com estrutura mínima. LLMs leem melhor, processam com mais eficiência, cometem menos erros de interpretação. Não é coincidência que o Spec-Driven Development, o graphify e a maioria dos pipelines modernos de agentes trabalhem com .md como formato padrão.
O problema: o mundo não vive em Markdown. Vive em PDF, DOCX, PPTX, XLSX, e-mails, planilhas, vídeos no YouTube. Converter isso manualmente é lento. Deixar o agente converter é caro. Precisava de uma etapa entre os dois mundos — e essa etapa não deveria custar token nenhum.
O que é o doc2md
Uma skill de agente de IA. Você coloca arquivos em .raw-docs/, roda /doc2md, e os .md aparecem em docs/ prontos para qualquer agente consumir.
Formatos suportados: documentos como PDF, DOCX, PPTX, XLSX e CSV; conteúdo web como YouTube (transcrição completa), Wikipedia e qualquer HTML; e ainda EPUB, Jupyter Notebook, e-mail Outlook e ZIP.
Cache MD5 integrado — arquivos já convertidos não são reprocessados. Modo --watch converte novos arquivos automaticamente a cada 3 segundos. Stack: markitdown (Microsoft, open source), Python stdlib. Sem API, sem nuvem, sem chave.
Os números que importam
Exemplo: relatório de 50 páginas, ~12.000 palavras. Mandado direto para o agente como PDF: ~90.000 tokens — equivalente a ~US$ 0,27 por documento no Claude Sonnet. Pré-processado com doc2md, o mesmo conteúdo chega como ~9.000 tokens — ~US$ 0,027. 81% menos tokens, ~US$ 0,24 economizados por documento.
À medida que o volume cresce: 10 docs/mês → ~US$ 2,40 economizados. 100 docs/mês → ~US$ 24,00 economizados. 500 docs/mês → ~US$ 120,00 economizados — sem esforço adicional.
E os tokens são só a parte visível. Agentes que recebem Markdown bem estruturado erram menos, pedem menos reprocessamento, e produzem outputs mais precisos na primeira tentativa. Isso também tem custo — só não aparece diretamente na fatura.
Como encaixa no pipeline
O doc2md vai no começo de qualquer fluxo que precisa consumir documentos externos.
Para YouTube especificamente — palestras, tutoriais, reuniões gravadas — o ganho é direto: em vez de mandar o link para o agente buscar e processar, o doc2md extrai a transcrição completa com metadados localmente, antes de qualquer chamada de LLM.
PDF / DOCX / PPTX / YouTube
↓
/doc2md ← zero tokens, local, instantâneo
↓
.md limpo
↓
Claude / graphify ← recebe texto estruturado, não binário
↓
Output mais preciso, custo menorA reflexão que fica
Você encontra uma biblioteca open source. Ela faz 80% do que você precisa — mas do jeito dela, com os parâmetros dela, na ordem que ela decidiu. Antes, você ficava refém disso. Usava como estava ou não usava.
Agora você pega a biblioteca, envelopa numa skill, e conversa com ela em linguagem natural para adaptá-la ao seu contexto. Muda a estrutura de pastas, ajusta o fluxo, integra com outras ferramentas. Sem reescrever nada do zero, sem depender do roadmap de ninguém.
O doc2md é um exemplo pequeno disso — mas o princípio vale para ferramentas inteiras. A IA não está só automatizando tarefas. Está eliminando a distância entre "o que existe" e "o que eu precisaria que existisse". Isso vai ficar cada vez mais presente. E quem entender isso antes vai parar de esperar que alguém construa a ferramenta certa — e vai simplesmente ajustar a que já existe.
O que aprendi construindo isso
Ferramentas de infraestrutura têm ROI diferente de ferramentas de produto. Você não vê o resultado imediatamente — mas todo workflow que passa por ela fica um pouco mais barato, mais preciso, mais rápido. O efeito acumula silenciosamente.
O repositório está público. A skill pode ser copiada, modificada, adaptada para o seu contexto — esse é o ponto.