DEV Community: Indiorlei de Oliveira

O Calibre não enxergava o meu OCR: como fiz um app para Mac que leva PDFs escaneados ao Kindle

Indiorlei de Oliveira — Thu, 12 Nov 2026 14:30:33 +0000

Eu leio muito no Kindle, e boa parte do que quero ler só existe em PDF. Alguns são exportados direitinho, com texto de verdade. Muitos são livros escaneados: 400 fotos de páginas, 180 MB, meio tortas.

Dá para mandar o PDF direto para o Kindle, mas o resultado é ruim. O PDF tem página fixa, então numa tela de 6" a letra fica minúscula e não dá para aumentar. O que você quer é um EPUB, que se ajusta à tela e deixa trocar a fonte e o tamanho da letra, como um livro comprado na loja.

A receita de sempre usa quatro ferramentas: uma para o OCR, o Calibre para converter, alguma coisa para diminuir as imagens e o e-mail ou o app da Amazon para enviar. Eu queria uma janela só, onde arrasto o PDF e o livro aparece no Kindle.

O pipeline

Cada PDF entra numa fila e passa pelas mesmas cinco etapas, um livro de cada vez:

PDF ─▶ Análise ─▶ OCR ─────────────▶ Conversão ─▶ Compressão ─▶ Envio
       PDFKit     ocrmypdf ou Vision  Calibre      ImageIO        Send to Kindle
                  (só se escaneado)   ou Modo imagem              ou SMTP

Vou passar por cada uma, mas a parte interessante é a terceira.

1. Análise: esse PDF tem texto, é escaneado ou os dois?

Rodar OCR num PDF que já tem texto gasta minutos e ainda pode piorar o resultado. Então o primeiro passo é descobrir o que temos em mãos.

O Lumink usa o PDFKit para extrair o texto de até 30 páginas espalhadas pelo livro. Uma página "tem texto" se tiver 40 caracteres ou mais, sem contar espaços:

let ratio = Double(withText) / Double(indices.count)
let kind: PDFKind =
    ratio >= 0.9 ? .text :     // PDF com texto: pula o OCR
    ratio < 0.5  ? .scanned :  // escaneado
                   .mixed      // misto

Como só uma amostra é lida, essa etapa leva menos de um segundo, mesmo num livro de 600 páginas. Quando o OCR roda de verdade, aí sim o Lumink verifica todas as páginas e só reconhece as que estão com menos de 40 caracteres.

2. OCR, com plano B

Nos PDFs escaneados e mistos, o Lumink roda o ocrmypdf (Tesseract) com --skip-text, para não refazer as páginas que já têm texto.

O ocrmypdf é opcional. Se ele não estiver instalado ou falhar, o Lumink usa o Vision da Apple (VNRecognizeTextRequest no modo accurate), que já vem no macOS. É mais lento, mas o OCR funciona até num Mac sem nada instalado.

Se um PDF escaneado render menos de 100 caracteres por página, em média, depois do OCR, provavelmente é uma HQ ou um livro de fotos. Nesse caso o Lumink muda sozinho para o Modo imagem (falo dele mais abaixo).

3. O bug: o Calibre ignora texto invisível

Foi essa parte que me custou uma noite.

O OCR não substitui a imagem escaneada. Ele mantém a imagem e põe por cima uma camada de texto invisível, posicionada sobre as palavras. No PDF, isso é texto com render mode 3 (um modo de pintura que não desenha nada). É por isso que dá para selecionar e buscar texto num PDF com OCR e continuar vendo o scan original.

Passei esse PDF para o ebook-convert do Calibre, e o EPUB saiu... sem texto nenhum. Só imagens, uma por página.

Testei o outro motor de PDF do Calibre, e deu o mesmo resultado. Os dois descartam texto invisível. Para o Calibre, uma página com OCR é uma foto sem nada escrito.

A solução: montar eu mesmo o PDF que vai para o Calibre (TextLayerPDFBuilder no código). São dois passos.

Primeiro, ler de volta o texto que o OCR gravou, linha por linha e com a posição de cada uma. O PDFKit faz isso direto da camada invisível:

let box = page.bounds(for: .mediaBox)
let lines = page.selection(for: box)?.selectionsByLine() ?? []
// cada linha: texto + retângulo na página

Depois, gerar um PDF novo. As páginas que já tinham texto são copiadas como estão. Nas páginas escaneadas, cada linha é desenhada como texto visível, no mesmo lugar, e a imagem do scan fica de fora:

// A caixa da linha inclui ascendentes e descendentes; ~75% dela é o corpo da fonte.
let fontSize = max(4, rect.height * 0.75)
// ...
// Estica ou encolhe na horizontal para ocupar a largura original da linha.
let sx = min(max(rect.width / width, 0.5), 2)
ctx.textMatrix = CGAffineTransform(scaleX: sx, y: 1)
ctx.textPosition = CGPoint(x: rect.minX, y: rect.minY + descent)
CTLineDraw(ctLine, ctx)

Esse esticamento horizontal parece detalhe, mas faz diferença. O Calibre decide se duas linhas fazem parte do mesmo parágrafo olhando onde cada uma termina. Se a linha redesenhada ficasse mais curta que a original, ele quebraria o parágrafo no meio.

O resultado é que o Calibre enxerga texto de verdade e o reflow funciona. De bônus, o EPUB não carrega uma foto de cada página, o que o deixa muito menor.

O custo é que as figuras dentro de páginas escaneadas não vão para o EPUB. Para livros que são quase só ilustração, o Modo imagem é a melhor escolha.

4. Conversão com o Calibre

Para texto, o Lumink chama o ebook-convert com opções pensadas para livros, não para documentos. Esta é a parte que importa:

ebook-convert entrada.pdf saida.epub \
  --output-profile kindle_pw3 \
  --pdf-engine calibre \
  --pdf-header-skip -1 --pdf-footer-skip -1 \
  --pdf-footer-regex '^\s*[-–—]?\s*\d{1,4}\s*[-–—]?\s*$' \
  --unwrap-factor 0.45 \
  --enable-heuristics \
  --filter-css font-family,color,background-color \
  --epub-version 3

--pdf-header-skip/--pdf-footer-skip -1 detectam e tiram os títulos que se repetem no topo e no pé de toda página.
A regex tira os números de página soltos, inclusive os do tipo — 42 —.
--enable-heuristics junta linhas quebradas e desfaz a hifenização.
--filter-css tira a fonte e as cores do PDF, e o Kindle aplica as que o leitor escolheu.

Sem essas opções, o EPUB parece uma fotocópia, com um número de página no meio da frase a cada poucos parágrafos.

Um detalhe sobre o idioma: o Lumink detecta o idioma do livro com o NLLanguageRecognizer (do texto do PDF ou do texto do OCR) e grava em dc:language, nos metadados do EPUB. Parece cosmético, mas o Kindle usa esse campo para escolher o dicionário, a hifenização e a voz da leitura em voz alta. O mesmo idioma vai na frente da lista de idiomas do OCR, porque tanto o Vision quanto o Tesseract dão mais peso ao primeiro.

Modo imagem, para HQ e mangá

HQs, mangás e livros de fotos não têm texto que valha ajustar à tela. O Modo imagem pula o OCR e o Calibre e gera direto um EPUB 3 de layout fixo (rendition:layout igual a pre-paginated), com uma imagem por página. É o único modo que não precisa do Calibre.

5. Compressão

Livros escaneados são pesados, e as duas formas de envio têm limite de tamanho. Então o Lumink descompacta o EPUB e recomprime as imagens em paralelo com o ImageIO:

Nível	Altura máxima	Qualidade do JPEG
Alta	1600 px	85%
Média	1600 px	75%
Máxima	1200 px	55%

Além disso, os PNGs opacos de 40 KB ou mais viram JPEG, depois de conferir a transparência pixel a pixel. E uma imagem nova só fica se for mesmo menor que a original.

Quando um PNG vira JPEG, as referências no HTML, no CSS e no OPF, e também o media-type, são atualizados. Depois o app compacta o livro de novo, com o mimetype como primeira entrada e sem compressão, como a especificação do EPUB exige (zip -X -0). Se essa regra não for seguida, alguns leitores recusam o arquivo.

Se o livro ainda passar do limite, ele tenta o nível seguinte. Se nem a compressão máxima resolver, salva o EPUB e avisa, em vez de mandar um arquivo que vai voltar.

6. Envio, sem pedir a sua senha

A primeira versão enviava os livros por e-mail, o que significava pedir uma senha SMTP. Mesmo guardada no Keychain, eu não gostava de pedir senha para ninguém.

Agora o padrão é o app oficial Send to Kindle da Amazon para Mac. O Lumink abre o EPUB nele, você escolhe o Kindle e confirma. O login fica com a Amazon: nenhuma senha no Lumink, nenhum servidor no meio, e um limite de 200 MB.

O e-mail continua como opção, para quem quer envio totalmente automático. Dois detalhes que gostei de resolver ali:

A conta do tamanho. O Send to Kindle por e-mail aceita 50 MB, mas o Gmail recusa mensagens acima de 25 MB, e o base64 aumenta o anexo em uns 33%. Sobram uns 18 MB de anexo. Quando o servidor é o Gmail, o Lumink usa 18 MB como limite automaticamente.

Por que curl. Eu poderia usar um pacote Swift de SMTP, mas a maioria mal é mantida, e cada um traria o próprio código de TLS e autenticação para eu auditar. Em vez disso, o Lumink monta a mensagem MIME e entrega para o curl que já vem no macOS. A senha vai para o curl pelo stdin (--config -), então nunca aparece no ps nem num arquivo no disco.

O que aprendi

Teste a ferramenta com a entrada real, não com a que você imagina. Eu testava o Calibre com PDFs de texto, e funcionava. O problema só apareceu com PDFs saídos do OCR, porque "ter texto" e "ter texto visível" são coisas diferentes.
Plano B nativo vale a pena. Ter o Vision como alternativa ao ocrmypdf fez o app funcionar num Mac novo, sem Homebrew e sem Python.
Às vezes o recurso mais seguro é o que não existe. Tirar a senha do caminho padrão resolveu mais do que qualquer cuidado com o Keychain.

O que ele ainda não faz

Não tem leitura da direita para a esquerda para mangá japonês: as páginas ficam na ordem do PDF.
Figuras dentro de páginas escaneadas são descartadas (veja a parte do Calibre).
O OCR do Vision é bem mais lento que o do ocrmypdf, principalmente na primeira vez, quando carrega os modelos.
Ainda não é notarizado pela Apple. Na primeira abertura, é preciso ir em Ajustes do Sistema → Privacidade e Segurança → Abrir mesmo assim, ou rodar um comando xattr.

Experimente

O Lumink é grátis e de código aberto, para macOS 14 ou mais novo, em Macs Apple Silicon e Intel. A interface está em português e em inglês. Para converter livros com texto, você precisa ter o Calibre instalado. O ocrmypdf é opcional.

Site e download: https://lumink-app.vercel.app
Código: https://github.com/indiorlei/lumink-app

Se você lê PDFs no Kindle, quero saber o que quebra. Issues e pull requests são bem-vindos, e o código é pequeno o bastante para ler numa tarde.

E fica a pergunta: você já esbarrou em alguma ferramenta que ignorava uma parte "invisível" do arquivo? Conta nos comentários.

Por que o nome? **Lume* é uma palavra antiga do português: fogo, chama, luz (do latim* lumen*), como em "vir a lume". Ink é tinta em inglês, como na tela de tinta eletrônica do leitor. E, em inglês,* kindle quer dizer acender.

Read this post in English: Calibre couldn't see my OCR: building a Mac app that gets scanned PDFs onto a Kindle

Calibre couldn't see my OCR: building a Mac app that gets scanned PDFs onto a Kindle

Indiorlei de Oliveira — Thu, 12 Nov 2026 14:30:27 +0000

I read a lot on a Kindle, and a lot of what I want to read only exists as a PDF. Some are clean exports with real text. Many are scanned books: 400 photos of pages, 180 MB, slightly crooked.

You can send a PDF straight to a Kindle, but the result is bad. A PDF has fixed pages, so on a 6" screen the text is tiny and you can't make it bigger. What you want is an EPUB, which reflows to fit the screen and lets you change the font and text size, like a book bought from the store.

The usual recipe takes four tools: one for OCR, Calibre to convert, something to shrink the images, then email or Amazon's app to send. I wanted one window where I drop the PDF and the book shows up on my Kindle.

The pipeline

Every PDF goes into a queue and through the same five stages, one book at a time:

PDF ─▶ Analyze ─▶ OCR ─────────────▶ Convert ─▶ Compress ─▶ Send
       PDFKit     ocrmypdf or Vision  Calibre    ImageIO      Send to Kindle
                  (only if scanned)   or image mode           or SMTP

I'll go through each one, but the interesting part is the third.

1. Analyze: is this PDF text, scanned, or both?

Running OCR on a PDF that already has text wastes minutes and can make things worse, so the first step is to find out what we have.

Lumink uses PDFKit to pull the text from up to 30 pages spread across the book. A page "has text" if it has 40 or more non-whitespace characters:

let ratio = Double(withText) / Double(indices.count)
let kind: PDFKind =
    ratio >= 0.9 ? .text :     // text PDF: skip OCR
    ratio < 0.5  ? .scanned :  // scanned
                   .mixed      // mixed

Because it only reads a sample, this step takes under a second, even on a 600-page book. When OCR does run, Lumink checks every page and only processes the ones with fewer than 40 characters.

2. OCR, with a fallback

For scanned and mixed PDFs, Lumink runs ocrmypdf (Tesseract) with --skip-text, so pages that already have text are left alone.

ocrmypdf is optional. If it isn't installed or it fails, Lumink falls back to Apple's Vision framework (VNRecognizeTextRequest in accurate mode), which ships with macOS. It's slower, but it means OCR works on a fresh Mac with nothing installed.

If a scanned PDF yields fewer than 100 characters per page on average after OCR, it's probably a comic or a photo book. In that case Lumink switches to image mode on its own (more on that below).

3. The bug: Calibre ignores invisible text

This is the part that cost me an evening.

OCR doesn't replace the scanned image. It keeps the image and adds an invisible text layer on top, positioned over the words. In PDF terms, that's text drawn with render mode 3, a paint mode that draws nothing. That's how you can select and search text in an OCR'd PDF while still seeing the original scan.

I fed that PDF to Calibre's ebook-convert, and the EPUB came out... with no text at all. Just images, one per page.

I tried Calibre's other PDF engine and got the same result. Both drop invisible text. As far as Calibre is concerned, an OCR'd page is a picture with nothing written on it.

The fix: build the PDF that goes to Calibre myself (TextLayerPDFBuilder in the code). It takes two steps.

First, read back the text the OCR wrote, line by line, with each line's position. PDFKit reads it straight from the invisible layer:

let box = page.bounds(for: .mediaBox)
let lines = page.selection(for: box)?.selectionsByLine() ?? []
// each line: text + rectangle on the page

Then, write a new PDF. Pages that already had text are copied as they are. On scanned pages, every line is drawn as visible text in the same spot, and the scan image is left out:

// The line box includes ascenders and descenders; ~75% of it is the font size.
let fontSize = max(4, rect.height * 0.75)
// ...
// Stretch or squeeze horizontally to fill the line's original width.
let sx = min(max(rect.width / width, 0.5), 2)
ctx.textMatrix = CGAffineTransform(scaleX: sx, y: 1)
ctx.textPosition = CGPoint(x: rect.minX, y: rect.minY + descent)
CTLineDraw(ctLine, ctx)

The horizontal stretch looks like a detail, but it matters. Calibre decides whether two lines belong to the same paragraph by looking at where each line ends. If a redrawn line came out shorter than the original, Calibre would break the paragraph in the middle.

Now Calibre sees real text, and reflow works. As a bonus, the EPUB doesn't carry a photo of every page, which makes it far smaller.

The trade-off is that figures inside scanned pages don't make it into the EPUB. For books that are mostly illustrations, image mode is the better choice.

4. Convert with Calibre

For text, Lumink calls ebook-convert with options tuned for books rather than documents. Here are the ones that matter:

ebook-convert input.pdf output.epub \
  --output-profile kindle_pw3 \
  --pdf-engine calibre \
  --pdf-header-skip -1 --pdf-footer-skip -1 \
  --pdf-footer-regex '^\s*[-–—]?\s*\d{1,4}\s*[-–—]?\s*$' \
  --unwrap-factor 0.45 \
  --enable-heuristics \
  --filter-css font-family,color,background-color \
  --epub-version 3

--pdf-header-skip/--pdf-footer-skip -1 detect and remove the running titles at the top and bottom of every page.
The regex removes stray page numbers, including ones like — 42 —.
--enable-heuristics joins broken lines and undoes hyphenation.
--filter-css strips the PDF's fonts and colors, so the Kindle applies the ones the reader picked.

Without these options, the EPUB reads like a photocopy, with a page number in the middle of a sentence every few paragraphs.

A note on language: Lumink detects the book's language with NLLanguageRecognizer (from the PDF's text or from the OCR output) and writes it to dc:language in the EPUB metadata. It looks cosmetic, but the Kindle uses that field to pick the dictionary, hyphenation and the text-to-speech voice. The same language also goes to the front of the OCR language list, because both Vision and Tesseract give more weight to the first entry.

Image mode, for comics and manga

Comics, manga and photo books don't have text worth reflowing. Image mode skips OCR and Calibre and builds a fixed-layout EPUB 3 (rendition:layout set to pre-paginated) directly, one image per page. It's the only mode that doesn't need Calibre at all.

5. Compress

Scanned books are heavy, and both delivery paths have size limits. So Lumink unzips the EPUB and recompresses the images in parallel with ImageIO:

Level	Max height	JPEG quality
High	1600 px	85%
Medium	1600 px	75%
Maximum	1200 px	55%

On top of that, opaque PNGs of 40 KB or more become JPEGs, after a pixel-by-pixel transparency check. A new image is only kept if it's actually smaller than the original.

When a PNG becomes a JPEG, the references in the HTML, CSS and OPF, and the media-type, are updated too. Then the app zips the book back up, with mimetype as the first, uncompressed entry, as the EPUB spec requires (zip -X -0). Some readers reject the file if that rule isn't followed.

If the book is still over the limit, it tries the next level. If even maximum compression doesn't fit, it saves the EPUB and tells you, instead of sending a file that would bounce.

6. Send, without asking for your password

The first version sent books by email, which meant asking for an SMTP password. Even stored in the Keychain, I didn't like asking anyone for a password.

The default now is Amazon's own Send to Kindle app for Mac. Lumink opens the EPUB in it, and you pick your Kindle and confirm. The login stays with Amazon: no password in Lumink, no server in between, and a 200 MB limit.

Email is still there as an option for fully automatic delivery. Two details I liked solving there:

The size math. Send to Kindle by email accepts 50 MB, but Gmail rejects messages over 25 MB, and base64 makes the attachment about 33% bigger. That leaves roughly 18 MB of attachment. When the server is Gmail, Lumink uses 18 MB as the limit automatically.

Why curl. I could have used a Swift SMTP package, but most are barely maintained, and each would bring its own TLS and auth code for me to audit. Instead, Lumink builds the MIME message itself and hands it to the curl that ships with macOS. The password goes to curl through stdin (--config -), so it never shows up in ps or in a file on disk.

What I learned

Test the tool with the real input, not the one you picture. I tested Calibre with text PDFs, and it worked. The problem only showed up with PDFs that came out of OCR, because "has text" and "has visible text" are different things.
A native fallback is worth it. Having Vision as a fallback for ocrmypdf made the app work on a fresh Mac, with no Homebrew and no Python.
Sometimes the safest feature is the one you remove. Taking the password out of the default path did more than any amount of Keychain care.

Things it doesn't do (yet)

No right-to-left reading for Japanese manga: pages stay in PDF order.
Figures inside scanned pages are dropped (see the Calibre section).
Vision OCR is much slower than ocrmypdf, especially the first time, when it loads its models.
It isn't notarized by Apple yet, so on first launch you need to go to System Settings → Privacy & Security → Open Anyway, or run one xattr command.

Try it

Lumink is free and open source, for macOS 14 or later, on Apple Silicon and Intel. The interface is in English and Portuguese. To convert text books, you need Calibre installed. ocrmypdf is optional.

Website and download: https://lumink-app.vercel.app/en
Source: https://github.com/indiorlei/lumink-app

If you read PDFs on a Kindle, I'd love to hear what breaks. Issues and pull requests are welcome, and the code is small enough to read in an afternoon.

And a question for you: have you ever run into a tool that silently ignored an "invisible" part of a file? Tell me in the comments.

Why the name? **Lume* is an old Portuguese word for fire and light (from Latin* lumen*). Ink is for the e-ink screen. And in English, to* kindle means to set alight.

Leia este post em português: O Calibre não enxergava o meu OCR: como fiz um app para Mac que leva PDFs escaneados ao Kindle

Como transformei tarefas repetitivas de Git em agentes de IA com o Kiro CLI

Indiorlei de Oliveira — Sun, 11 Oct 2026 13:41:17 +0000

Toda equipe tem aquele conjunto de tarefas chatas que ninguém gosta de fazer, mas que precisam ser feitas sempre do mesmo jeito: abrir PR com o título no padrão, nomear a branch certo, montar o changelog, linkar o work item. São tarefas de baixo valor intelectual e alto custo de atenção — e, pior, qualquer desvio do padrão vira ruído na revisão.

Resolvi atacar isso de uma forma diferente: em vez de escrever mais um script bash gigante, montei agentes de IA especializados que encapsulam esses fluxos. Neste artigo mostro como estruturei esse setup usando o Kiro CLI, com um padrão que separa claramente configuração, conhecimento e regras de segurança.

Vou usar meus próprios agentes como exemplo — abstraindo nomes internos — mas o padrão serve para qualquer time.

O problema

No meu dia a dia eu repetia, várias vezes por dia, dois fluxos:

Abrir um Pull Request: criar a branch no padrão, commitar com a convenção certa, inferir a branch de destino, abrir o PR com título e descrição padronizados e linkar o work item.
Fechar um pacote de release: buscar os PRs já concluídos de uma demanda, gerar o changelog, commitar e abrir um PR de release para a branch certa.

Nenhum desses passos é difícil. O problema é que todos eles têm detalhes — e detalhe esquecido é retrabalho. Automatizar com um script puro seria frágil, porque boa parte das decisões depende de contexto (qual branch, qual título, qual destino).

Agente de IA é bom justamente nessa zona cinzenta: segue regras, mas interpreta contexto.

A ideia central: separar configuração, conhecimento e regras

O que mais me ajudou foi não jogar tudo em um prompt gigante. Em vez disso, dividi cada agente em quatro camadas, cada uma em um arquivo próprio:

.kiro/
├── agents/        # Configuração: quais ferramentas o agente pode usar
├── prompts/       # Identidade: quem o agente é e seu contexto fixo
├── steering/      # Guardrails: o que ele NUNCA pode fazer
├── skills/        # Conhecimento: o passo a passo de cada tarefa
└── settings/      # Integração com ferramentas externas (via MCP)

A sacada é que cada camada tem uma responsabilidade única:

Agent = o contrato (ferramentas permitidas, atalho, mensagem de boas-vindas)
Prompt = a identidade (contexto que nunca muda)
Steering = os limites (proibições inegociáveis)
Skill = o manual (como executar cada passo, com exemplos)

Separar assim traz um benefício enorme: as skills viram reutilizáveis entre agentes. A skill de "criar commit" é a mesma para o agente que abre PR e para o que fecha release.

Camada 1 — O agente (configuração)

O arquivo de configuração do agente é enxuto. Ele diz o que o agente pode fazer, não como. Veja um exemplo (abstraído):

{
  "name": "open-pr",
  "description": "Agente que abre Pull Requests: cria branch, commita, abre o PR e linka o work item.",
  "prompt": "file://./prompts/open-pr.md",
  "includeMcpJson": true,
  "tools": ["shell", "read", "write", "grep", "glob", "@git-provider"],
  "allowedTools": [
    "shell",
    "read",
    "write",
    "@git-provider/create_pull_request",
    "@git-provider/create_branch",
    "@git-provider/link_work_item"
  ],
  "resources": [
    "skill://.kiro/skills/commit/SKILL.md",
    "skill://.kiro/skills/create-branch/SKILL.md",
    "skill://.kiro/skills/open-pr/SKILL.md"
  ],
  "keyboardShortcut": "ctrl+shift+p",
  "welcomeMessage": "Me diga o ID da demanda ou descreva a feature. Eu cuido do resto."
}

Dois pontos importantes aqui:

allowedTools é uma allowlist explícita. O agente só consegue chamar exatamente as ferramentas que eu listei. Isso é segurança por design: ele não vai, por engano, chamar uma ferramenta destrutiva que eu nunca autorizei.
resources injeta as skills. O agente carrega as instruções detalhadas sob demanda, em vez de carregar tudo o tempo todo.

Camada 2 — O prompt (identidade e contexto fixo)

O prompt define quem o agente é e qual contexto nunca muda. É aqui que eu "ancoro" o agente para ele não ficar perguntando o óbvio toda vez.

Você é um agente especializado em abrir Pull Requests para o
repositório da equipe.

## Contexto Fixo
- Provedor de git: <configurado via MCP>
- Projeto / repositório: <fixos, injetados pela configuração>
- Branch de origem padrão: `main`

## Regras de Operação
- SEMPRE usar o projeto e repositório fixos — NUNCA perguntar ao usuário
- Inferir a branch de destino a partir do contexto da demanda
- Seguir as convenções de branch e commit definidas nas skills

## O que NÃO fazer
- NÃO perguntar projeto ou repositório — são fixos
- NÃO fazer push direto para branches protegidas

Repare no padrão "Regras" + "O que NÃO fazer". Dizer ao agente o que não fazer é tão importante quanto dizer o que fazer. Isso reduz muito o comportamento imprevisível.

Dica: dados que não devem vazar (IDs internos, GUIDs, URLs) ficam fora do artigo/documentação pública e são injetados via configuração ou MCP. Nunca coloque isso no corpo de uma skill que vai pro repositório aberto.

Camada 3 — Steering (guardrails inegociáveis)

Essa é a camada que me deixa dormir tranquilo. O steering lista proibições absolutas, independentes de qualquer instrução que o agente receba.

# Open PR — Guardrails

## Proibições
- NUNCA fazer force push
- NUNCA push direto em branches protegidas
- NUNCA criar PR sem pelo menos 1 commit na branch
- NUNCA prosseguir se o git mostrar conflitos não resolvidos

## Confirmações Obrigatórias
- SEMPRE mostrar o resumo (branch, commits, destino, título) antes de abrir o PR
- SEMPRE confirmar se houver dúvida sobre a branch de destino

## Comportamento em Falha
- Se o push falhar → mostrar o erro e sugerir ação (nunca forçar)
- Se a branch de destino não existir → perguntar ao usuário

A diferença entre prompt e steering é intencional: o prompt é a personalidade (pode ter nuance), o steering é a lei (não tem exceção). Mesmo que o usuário peça "faz um force push aí", o guardrail segura.

Camada 4 — Skills (o conhecimento reutilizável)

As skills são o coração do setup. Cada uma é um documento curto que ensina um procedimento, com formato e exemplos. A skill de commit, por exemplo, define a convenção completa:

# Responsabilidade
Criar commits padronizados.

## Formato
<type>(<scope>): <emoji> <descrição curta>

## Procedimento
1. Rodar `git status --short`
2. Analisar os caminhos para determinar tipo e escopo
3. Agrupar em commits lógicos
4. Fazer staging seletivo (nunca `git add .`)
5. Commitar com a mensagem formatada

## Exemplos
feat(module-a): ✨ add product tag component
fix(module-b): 🐛 correct price display
refactor(shared): 🔨 simplify item props

O ponto forte: a mesma skill de commit é usada pelo agente de PR e pelo agente de release. Escrevi uma vez, reaproveitei em todos. Quando a convenção muda, altero um arquivo só.

Meu segundo agente — o de fechar release — é basicamente uma orquestração de skills:

Recebe o ID da demanda
  → busca os PRs já concluídos
  → troca para a branch certa
  → gera o changelog
  → usa a skill de commit
  → usa a skill de open-pr para abrir o PR de release
  → linka o work item

Ou seja: um agente complexo nasce da composição de skills simples. Isso é muito mais fácil de manter do que um prompt monolítico.

Camada 5 — Integração via MCP

Para o agente conseguir realmente abrir PRs e buscar demandas, ele precisa falar com o provedor de git. Eu faço isso via MCP (Model Context Protocol), que expõe as operações externas como ferramentas que o agente pode chamar.

{
  "mcpServers": {
    "git-provider": {
      "command": "npx",
      "args": ["-y", "<pacote-mcp-do-provedor>", "--arg", "valor"],
      "env": {
        "PROVIDER_ORG_URL": "<url-da-organizacao>",
        "PROVIDER_DEFAULT_PROJECT": "<projeto>",
        "PROVIDER_DEFAULT_REPOSITORY": "<repo>"
      }
    }
  }
}

O MCP é o que conecta o "cérebro" (o agente) às "mãos" (as operações no provedor de git). E, combinado com a allowlist lá do agente, eu controlo exatamente quais dessas operações ficam disponíveis.

Camada 6 — Docs de onboarding

Por último, mantenho um doc curto por agente explicando o que ele é e como invocar. É o que eu passo pra qualquer pessoa nova do time:

# Agente `open-pr`

## Como invocar
- Atalho: Ctrl+Shift+P
- Ou: "Abre um PR para a demanda 123" / "Commita e abre PR"

## Fluxo
Usuário informa demanda → busca contexto → cria branch →
commit → push → abre PR → linka work item → retorna o link

## Onde vivem as regras
| Assunto              | Arquivo                     |
|----------------------|-----------------------------|
| Convenção de branch  | skills/create-branch        |
| Convenção de commit  | skills/commit               |
| Regras de PR         | skills/open-pr              |
| Guardrails           | steering/open-pr            |

O resultado na prática

Depois que esse setup entrou no fluxo, abrir um PR virou uma frase: "abre um PR pra demanda X". O agente infere a branch, commita no padrão, abre o PR com título e descrição corretos e linka o work item — sempre do mesmo jeito, sem eu precisar lembrar de cada detalhe.

E, olhando o histórico de commits do repositório, dá pra ver a convenção sendo seguida de forma consistente: tipo, escopo, emoji e descrição curta em inglês, commit após commit. Essa consistência é exatamente o que eu queria — e ela não depende mais da minha memória num dia cansado.

O que eu levaria pra qualquer projeto

Se eu fosse resumir o aprendizado em princípios reaproveitáveis:

Separe configuração de conhecimento. O agente diz o que pode; a skill diz como fazer.
Guardrails são uma camada à parte. Proibições não deveriam estar misturadas com instruções normais.
Skills pequenas e reutilizáveis. Um agente complexo é composição de skills simples.
Allowlist de ferramentas sempre. Segurança por design, não por confiança.
Diga o que NÃO fazer. Isso reduz comportamento imprevisível mais do que qualquer instrução positiva.
Mantenha dados sensíveis fora das skills. Injete por configuração/MCP, nunca no texto versionado.

No fim, não automatizei só tarefas — padronizei decisões. E isso, mais do que o tempo economizado, foi o que mudou meu fluxo de trabalho.

Se você também vive repetindo os mesmos passos de Git, vale experimentar esse padrão. Comece com uma skill só, como a de commit, e vá compondo a partir daí.

🇺🇸 English version: How I turned repetitive Git chores into AI agents with the Kiro CLI

How I turned repetitive Git chores into AI agents with the Kiro CLI

Indiorlei de Oliveira — Sun, 11 Oct 2026 13:41:02 +0000

Every team has that set of boring tasks nobody enjoys but everybody has to do the exact same way every time: open a PR with the right title format, name the branch correctly, build the changelog, link the work item. These are low-intellectual-value, high-attention-cost chores — and worse, any deviation from the standard becomes noise during review.

I decided to tackle this differently: instead of writing yet another giant bash script, I built specialized AI agents that encapsulate these workflows. In this article I'll show how I structured that setup using the Kiro CLI, with a pattern that cleanly separates configuration, knowledge, and safety rules.

I'll use my own agents as the example — with internal names abstracted away — but the pattern works for any team.

The problem

In my day-to-day, I repeated two workflows several times a day:

Opening a Pull Request: create the branch in the right format, commit with the correct convention, infer the target branch, open the PR with a standardized title and description, and link the work item.
Closing a release package: find the already-completed PRs for a work item, generate the changelog, commit it, and open a release PR against the right branch.

None of these steps is hard. The problem is that every one of them has details — and a forgotten detail means rework. Automating with a pure script would be fragile, because many of the decisions depend on context (which branch, which title, which target).

AI agents are great precisely in that gray zone: they follow rules, but they interpret context.

The core idea: separate configuration, knowledge, and rules

What helped me the most was not throwing everything into one giant prompt. Instead, I split each agent into four layers, each in its own file:

.kiro/
├── agents/        # Configuration: which tools the agent is allowed to use
├── prompts/       # Identity: who the agent is and its fixed context
├── steering/      # Guardrails: what it must NEVER do
├── skills/        # Knowledge: the step-by-step for each task
└── settings/      # Integration with external tools (via MCP)

The key insight is that each layer has a single responsibility:

Agent = the contract (allowed tools, shortcut, welcome message)
Prompt = the identity (context that never changes)
Steering = the limits (non-negotiable prohibitions)
Skill = the manual (how to execute each step, with examples)

Splitting it this way brings a huge benefit: skills become reusable across agents. The "create commit" skill is the same for the agent that opens PRs and the one that closes releases.

Layer 1 — The agent (configuration)

The agent's config file is lean. It states what the agent can do, not how. Here's an example (abstracted):

{
  "name": "open-pr",
  "description": "Agent that opens Pull Requests: creates a branch, commits, opens the PR and links the work item.",
  "prompt": "file://./prompts/open-pr.md",
  "includeMcpJson": true,
  "tools": ["shell", "read", "write", "grep", "glob", "@git-provider"],
  "allowedTools": [
    "shell",
    "read",
    "write",
    "@git-provider/create_pull_request",
    "@git-provider/create_branch",
    "@git-provider/link_work_item"
  ],
  "resources": [
    "skill://.kiro/skills/commit/SKILL.md",
    "skill://.kiro/skills/create-branch/SKILL.md",
    "skill://.kiro/skills/open-pr/SKILL.md"
  ],
  "keyboardShortcut": "ctrl+shift+p",
  "welcomeMessage": "Give me the work item ID or describe the feature. I'll handle the rest."
}

Two important points here:

allowedTools is an explicit allowlist. The agent can only call exactly the tools I listed. That's security by design: it won't accidentally call a destructive tool I never authorized.
resources injects the skills. The agent loads detailed instructions on demand instead of carrying everything all the time.

Layer 2 — The prompt (identity and fixed context)

The prompt defines who the agent is and which context never changes. This is where I "anchor" the agent so it doesn't keep asking the obvious every time.

You are an agent specialized in opening Pull Requests for the
team's repository.

## Fixed Context
- Git provider: <configured via MCP>
- Project / repository: <fixed, injected by configuration>
- Default source branch: `main`

## Operating Rules
- ALWAYS use the fixed project and repository — NEVER ask the user
- Infer the target branch from the work item context
- Follow the branch and commit conventions defined in the skills

## What NOT to do
- Do NOT ask for project or repository — they are fixed
- Do NOT push directly to protected branches

Notice the "Rules" + "What NOT to do" pattern. Telling the agent what not to do is just as important as telling it what to do. It dramatically reduces unpredictable behavior.

Tip: data that must not leak (internal IDs, GUIDs, URLs) stays out of public articles/docs and is injected via configuration or MCP. Never put that in the body of a skill that lands in an open repository.

Layer 3 — Steering (non-negotiable guardrails)

This is the layer that lets me sleep at night. Steering lists absolute prohibitions, independent of any instruction the agent receives.

# Open PR — Guardrails

## Prohibitions
- NEVER force push
- NEVER push directly to protected branches
- NEVER create a PR without at least 1 commit on the branch
- NEVER proceed if git shows unresolved conflicts

## Mandatory Confirmations
- ALWAYS show the summary (branch, commits, target, title) before opening the PR
- ALWAYS confirm if there's any doubt about the target branch

## Failure Behavior
- If the push fails → show the error and suggest an action (never force)
- If the target branch doesn't exist → ask the user

The distinction between prompt and steering is intentional: the prompt is the personality (it can have nuance), the steering is the law (no exceptions). Even if the user says "just force push it," the guardrail holds.

Layer 4 — Skills (reusable knowledge)

Skills are the heart of the setup. Each one is a short document that teaches one procedure, with a format and examples. The commit skill, for instance, defines the full convention:

# Responsibility
Create standardized commits.

## Format
<type>(<scope>): <emoji> <short description>

## Procedure
1. Run `git status --short`
2. Analyze the paths to determine type and scope
3. Group into logical commits
4. Stage selectively (never `git add .`)
5. Commit with the formatted message

## Examples
feat(module-a): ✨ add product tag component
fix(module-b): 🐛 correct price display
refactor(shared): 🔨 simplify item props

The strong point: the same commit skill is used by both the PR agent and the release agent. I wrote it once and reused it everywhere. When the convention changes, I edit a single file.

My second agent — the release closer — is basically skill orchestration:

Receives the work item ID
  → finds the already-completed PRs
  → switches to the right branch
  → generates the changelog
  → uses the commit skill
  → uses the open-pr skill to open the release PR
  → links the work item

In other words: a complex agent emerges from composing simple skills. That's far easier to maintain than a monolithic prompt.

Layer 5 — Integration via MCP

For the agent to actually open PRs and fetch work items, it needs to talk to the git provider. I do this via MCP (Model Context Protocol), which exposes external operations as tools the agent can call.

{
  "mcpServers": {
    "git-provider": {
      "command": "npx",
      "args": ["-y", "<provider-mcp-package>", "--arg", "value"],
      "env": {
        "PROVIDER_ORG_URL": "<org-url>",
        "PROVIDER_DEFAULT_PROJECT": "<project>",
        "PROVIDER_DEFAULT_REPOSITORY": "<repo>"
      }
    }
  }
}

MCP is what connects the "brain" (the agent) to the "hands" (the operations on the git provider). And combined with the agent's allowlist, I control exactly which of those operations are available.

Layer 6 — Onboarding docs

Finally, I keep a short doc per agent explaining what it is and how to invoke it. It's what I hand to anyone new on the team:

# `open-pr` Agent

## How to invoke
- Shortcut: Ctrl+Shift+P
- Or: "Open a PR for work item 123" / "Commit and open a PR"

## Flow
User provides a work item → fetch context → create branch →
commit → push → open PR → link work item → return the link

## Where the rules live
| Topic               | File                        |
|---------------------|-----------------------------|
| Branch convention   | skills/create-branch        |
| Commit convention   | skills/commit               |
| PR rules            | skills/open-pr              |
| Guardrails          | steering/open-pr            |

The result in practice

Once this setup entered my workflow, opening a PR became a single sentence: "open a PR for work item X." The agent infers the branch, commits in the right format, opens the PR with the correct title and description, and links the work item — always the same way, without me having to remember each detail.

And looking at the repository's commit history, you can see the convention being followed consistently: type, scope, emoji, and a short English description, commit after commit. That consistency is exactly what I wanted — and it no longer depends on my memory on a tired day.

What I'd take to any project

If I had to boil the lessons down into reusable principles:

Separate configuration from knowledge. The agent says what it can do; the skill says how to do it.
Guardrails are their own layer. Prohibitions shouldn't be mixed with normal instructions.
Small, reusable skills. A complex agent is a composition of simple skills.
Always allowlist tools. Security by design, not by trust.
Say what NOT to do. It reduces unpredictable behavior more than any positive instruction.
Keep sensitive data out of skills. Inject it via configuration/MCP, never in versioned text.

In the end, I didn't just automate tasks — I standardized decisions. And that, more than the time saved, is what actually changed my workflow.

If you also find yourself repeating the same Git steps over and over, this pattern is worth a try. Start with a single skill, like the commit one, and compose from there.

🇧🇷 Versão em português: Como transformei tarefas repetitivas de Git em agentes de IA com o Kiro CLI

Como criei um tema para VS Code e terminal como projeto de estudo

Indiorlei de Oliveira — Wed, 09 Sep 2026 00:48:15 +0000

Temas parecem um projeto pequeno: escolher algumas cores e trocar o arquivo de configuração do editor. Foi exatamente com essa expectativa que comecei o Underground, um tema escuro para VS Code e Kiro IDE. No caminho, descobri que um tema bom não é uma coleção de cores bonitas; é um pequeno sistema de design aplicado a muitos contextos.

O Underground nasceu como projeto de estudo. A proposta era simples: uma interface escura, discreta, com contraste confortável e um verde quente como ponto de atenção. Depois, o projeto cresceu para incluir o terminal integrado do editor, o Windows Terminal e o Terminal.app do macOS — todos orientados pela mesma paleta.

Neste artigo, compartilho o processo, as decisões e os problemas que encontrei. O repositório está disponível em GitHub.

Comecei pela intenção, não pelas cores

Antes de escrever JSON, defini a sensação que queria criar:

fundo escuro sem ser preto absoluto;
pouca competição visual entre as áreas da interface;
cores de sintaxe que ajudem a escanear o código;
cores semânticas previsíveis para erro, aviso, Git e conflitos;
terminal e editor com a mesma identidade.

Essa primeira etapa evitou uma armadilha comum: atribuir cores isoladamente à medida que os elementos aparecem. Em vez disso, cada escolha deveria responder a uma função. O verde, por exemplo, não existe apenas porque eu gosto dele; ele marca elementos ativos e também palavras-chave, parâmetros e tags. Ele é uma cor de atenção moderada, não uma cor usada em todo lugar.

Uma paleta pequena, com papéis claros

O núcleo do tema é composto por poucos tons:

Papel	Cor	Uso principal
Fundo	`#222222`	editor, barra lateral e painéis
Superfície elevada	`#272727`	abas ativas, inputs e status bar
Texto principal	`#ffffffde`	conteúdo de maior prioridade
Texto secundário	`#ffffff99`	descrições e informações auxiliares
Acento verde	`#9bd4b2`	atividade, parâmetros e Git modificado
Azul	`#90aed3`	strings, funções e números
Roxo	`#ceb0d3`	tipos, interfaces e atributos
Comentários	`#8a8a8a`	conteúdo propositalmente secundário

Um detalhe importante é o de em #ffffffde. Em temas do VS Code, também podemos usar hex com canal alfa. Assim, em vez de inventar muitos cinzas diferentes, usei branco com transparências distintas para criar uma escala de hierarquia: texto principal, secundário e sutil.

Essa abordagem deixou as decisões mais fáceis de manter. Quando percebi que comentários estavam apagados demais, por exemplo, não precisei redesenhar o tema inteiro: subi seu tom de #6a6a6a para #8a8a8a, preservando seu papel visual e melhorando a legibilidade.

A estrutura mínima de uma extensão de tema

Uma extensão de tema do VS Code pode ser surpreendentemente pequena. No caso do Underground, os dois arquivos essenciais são:

editors/vscode/
├── package.json
└── themes/
    └── underground-color-theme.json

O package.json registra o tema na seção contributes:

{
  "contributes": {
    "themes": [
      {
        "label": "Underground",
        "uiTheme": "vs-dark",
        "path": "./themes/underground-color-theme.json"
      }
    ]
  }
}

O arquivo de tema contém duas partes que vale separar mentalmente:

colors: a interface do VS Code — editor, abas, listas, widgets, terminal e estado do Git.
tokenColors e semanticTokenColors: a aparência do código.

Essa separação parece óbvia, mas foi uma boa forma de organizar o trabalho. Primeiro deixei o ambiente confortável para navegar; depois cuidei da leitura do código.

Tokens de sintaxe: cor é uma ferramenta de leitura

Para a primeira camada de sintaxe, associei grupos de scopes a papéis visuais. Uma versão reduzida da configuração é esta:

{
  "scope": ["keyword", "storage", "variable.parameter", "entity.name.tag"],
  "settings": { "foreground": "#9bd4b2" }
},
{
  "scope": ["string", "support.function", "constant.numeric"],
  "settings": { "foreground": "#90aed3" }
},
{
  "scope": ["entity.name.type", "entity.other.attribute-name"],
  "settings": { "foreground": "#ceb0d3" }
}

O ponto não é decorar scopes, e sim testar em linguagens diferentes. A mesma categoria pode receber scopes diferentes em TypeScript, HTML, JSON ou Markdown. Por isso mantive uma amostra de código para abrir no editor enquanto ajustava o tema.

Também adicionei semanticTokenColors. Essa camada moderna permite ao editor informar significados como type, function, parameter e variable.readonly, especialmente útil em TypeScript e JavaScript. O resultado é mais consistente do que depender exclusivamente da gramática textual.

A parte que quase sempre fica esquecida: a interface inteira

Colorir strings e palavras-chave é só o começo. Um tema realmente utilizável precisa lidar com estados menos frequentes: busca, sugestões, mensagens de validação, diff, merge conflict, Peek Definition, foco por teclado e decoração de Git.

Esses casos revelam problemas que uma captura de tela comum não mostra. No Underground, encontrei dois exemplos marcantes:

os números de linha tinham contraste insuficiente e praticamente desapareciam;
o widget de Peek Definition não tinha cores próprias e usava um fundo claro inesperado.

Corrigi o primeiro caso elevando o tom dos números inativos e mantendo o número ativo em branco. Para o segundo, foi preciso definir as chaves peekView*, usando o fundo elevado e a seleção já existentes na paleta.

Essa experiência mudou meu critério de pronto: um tema não está pronto quando o arquivo de exemplo está bonito. Ele está pronto depois de passar por fluxos reais de edição, busca, autocomplete, Git e resolução de conflitos.

Diferenças e conflitos também comunicam significado

Para diffs, evitei blocos muito saturados. Linhas adicionadas usam verde com baixa opacidade; removidas usam vermelho com baixa opacidade. As palavras alteradas recebem uma opacidade um pouco maior que a linha inteira, para criar hierarquia.

Nos conflitos de merge, mantive uma convenção semântica:

versão atual: verde;
versão recebida: azul;
base comum: cinza;
conflito ainda não resolvido: borda amarela.

É uma decisão pequena, mas útil: as cores deixam de ser decoração e passam a explicar o estado da informação.

Um tema, mais de um ambiente

Eu queria que abrir o terminal não parecesse mudar de aplicação. Por isso, documentei a paleta em PALETTE.md e usei o tema do VS Code como fonte canônica. A partir dos valores terminal.ansi*, criei:

um esquema JSON para o Windows Terminal;
um perfil .terminal para o Terminal.app do macOS.

Há uma sutileza aqui: o fundo do editor é #222222, mas o preto ANSI é #1a1a1a. Isso preserva a convenção de cores do terminal sem transformar toda a interface em preto absoluto.

Ter uma fonte de verdade reduz divergências. Se eu alterar o amarelo de aviso, sei que preciso revisar o amarelo ANSI e a documentação da paleta. Esse cuidado é mais simples do que tentar descobrir, meses depois, por que o editor e o terminal usam cores quase iguais.

O que eu faria desde o início em um próximo tema

Se fosse começar novamente, eu adotaria estes hábitos desde o primeiro commit:

Criar uma paleta com nomes de papel, não apenas uma lista de hexadecimais.
Preparar arquivos de exemplo com várias linguagens e estados de interface.
Testar acessibilidade e contraste antes de considerar uma cor definitiva.
Documentar a relação entre editor e terminal desde cedo.
Registrar mudanças visuais no changelog, incluindo o motivo da alteração.

Também vale testar o tema localmente por meio de um link simbólico na pasta de extensões do VS Code. Esse ciclo curto — editar, recarregar a janela, observar — tornou os ajustes muito mais rápidos.

Conclusão

Criar o Underground foi uma forma excelente de estudar ferramentas de desenvolvimento por outro ângulo. Um tema não altera a lógica do programa, mas influencia diretamente a experiência de ler, navegar e depurar código por horas.

A maior lição foi esta: consistência é mais valiosa do que quantidade de cores. Quando fundo, contraste, estados e semântica contam a mesma história, o resultado é mais calmo e mais útil.

Se você quiser explorar a implementação, contribuir ou adaptar a paleta, o código está no repositório do Underground, sob licença MIT.