Transforme um guia em PDF numa `skill` — apagando quase tudo

A frase que deveria comandar qualquer conversão de documento em skill está na documentação do Claude Code, numa linha sobre o corpo do SKILL.md: "diga o que fazer em vez de narrar como ou por quê". E o motivo é mecânico — depois que uma skill carrega, o conteúdo dela fica na conversa até o fim da sessão, então "cada linha é um custo recorrente de tokens".

Agora abre o PDF que você ia converter e vê quanta coisa ali é narração de como e por quê. A introdução. O parágrafo dizendo que é mais fácil do que parece. A definição de um termo. O comentário lateral listando três ferramentas alternativas. É justamente esse material que faz dele um bom documento — e é justamente ele que transforma uma conversão fiel numa skill ruim.

Ou seja: converter é, na maior parte, apagar. E a taxa de compressão é o seu sinal de qualidade. Meu número de trabalho: se a skill sai com mais de um quarto do tamanho do original, eu não converti, eu só reformatei. Documento reformatado é exatamente o arquivo que fica parado em .claude/skills/ sem servir pra nada.

Leia o original uma vez — é a coisa mais cara da sessão

Antes de anexar qualquer coisa, saiba quanto custa um PDF. A documentação da Anthropic descreve o caminho sem rodeio: o sistema converte cada página em imagem e extrai o texto de cada página junto com essa imagem. Você paga pelos dois. A comparação entre os dois modos de processamento de documento no Bedrock coloca um PDF de 3 páginas em cerca de 1.000 tokens só com extração de texto e cerca de 7.000 tokens com entendimento visual completo — 7× de diferença pelas mesmas três páginas. Os tetos duros são 32 MB por requisição e 600 páginas (100 quando o context window da requisição está abaixo de 1M), e a documentação avisa que PDFs densos "podem encher o context window antes de chegar no limite de páginas", recomendando dividir o documento em partes.

Duas consequências práticas. Se as tabelas, os prints e os diagramas é que carregam o procedimento, anexe o PDF de verdade e pague pela visão. Se é texto corrido com dois ou três blocos de código, extraia o texto primeiro e gaste um sétimo do orçamento. E, nos dois casos: leia uma vez só. O sentido inteiro da conversão é que essa leitura cara nunca mais precise acontecer.

O gênero do documento decide o formato da skill

A documentação do Claude Code separa o conteúdo de uma skill em dois tipos, e o seu documento já é um deles. Conteúdo de referência acrescenta conhecimento que o Claude aplica no que você está fazendo — convenções, padrões, conhecimento de domínio. Conteúdo de tarefa dá instruções passo a passo pra uma ação específica. Ler o seu documento como o tipo errado é o erro de conversão mais comum que eu vejo.

• Um procedimento — runbook, checklist de deploy, guia de migração, o tutorial de cinco passos — vira conteúdo de tarefa: um fluxo numerado. Pra qualquer coisa com mais de uns poucos passos, o guia de autoria recomenda embutir um checklist literal que o Claude copia pra resposta e vai marcando conforme avança. É a correção mais barata que se conhece pro modelo pular a etapa de validação no meio do caminho.
• Um padrão — guia de estilo, especificação, rubrica de revisão, política — vira conteúdo de referência mais um ciclo de verificação. O exemplo sem código da documentação é o que vale copiar: rascunhe, revise contra a lista, anote cada problema apontando a seção, corrija, revise de novo e só siga adiante quando todos os requisitos estiverem atendidos. Como eles colocam: "o 'validador' é o STYLE_GUIDE.md, e o Claude faz a checagem lendo e comparando". O seu documento de padrões não vira as instruções — ele vira aquilo contra o que as instruções conferem.

Os quatro cortes

O post de engenharia da Anthropic descreve uma skill como "um guia de integração pra alguém recém-contratado". Leve isso ao pé da letra: você está escrevendo pra alguém competente que está a ponto de agir, não pra alguém decidindo se aquilo interessa.

1. A camada que orienta o leitor. Toda introdução, toda seção de motivação, todo parágrafo de "por que isso importa" cai fora. O guia de autoria parte do princípio de que o Claude já é muito inteligente, então "acrescente só o contexto que o Claude ainda não tem" — e te entrega o teste pra aplicar linha por linha: "esse parágrafo justifica o custo em tokens?"
2. Explicação de coisa que o modelo já sabe. Aqui a documentação coloca preço. Uma seção enxuta sobre extrair texto de PDF roda em torno de 50 tokens; a mesma seção inflada com o que é um PDF e por que aquela biblioteca foi escolhida roda em torno de 150. Três vezes o custo, zero instrução a mais.
3. Alternativas apresentadas de forma neutra. Um bom documento é justo com quem lê e lista as opções. Uma skill tem que escolher. A recomendação é "dar um padrão (com saída de emergência)" — um caminho recomendado, mais no máximo uma exceção nomeada, pro caso que realmente quebra a regra.
4. A ordem narrativa. Documento ensina em ordem de construção: conceito, depois contexto, depois passos. Agente executa. Reorganize na ordem de execução e rebaixe a seção de "pré-requisitos" pra checagens do passo zero.

O que sobrevive é a parte que um estranho competente ainda erraria: comandos exatos, limites e limiares exatos, as pegadinhas com nome, as regras de "sempre/nunca" e qualquer tabela com valores reais.

Defina o grau de liberdade por passo, não por documento

Essa é a coisa que texto corrido não consegue expressar: num documento, toda frase tem o mesmo peso. Numa skill, você escolhe. O guia de autoria chama isso de graus de liberdade, com uma analogia que vale roubar — uma ponte estreita com abismo dos dois lados pede instrução exata e guarda-corpo; um campo aberto sem obstáculo pede direção geral e confiança. O exemplo de baixa liberdade que eles dão é literalmente "rode exatamente este script", seguido de "não modifique o comando nem adicione outras flags".

Minha regra de bolso converte no automático: todo lugar onde o documento dizia "cuidado aqui" ou "certifique-se de" é um passo de baixa liberdade. Reescreva como um comando exato com a proibição explícita do lado. Onde o documento estava descrevendo discernimento, deixe quatro bullets e confie no modelo. Quem decide é a fragilidade, não a importância.

O que sai do corpo

A regra de roteamento é uma pergunta só: eu consultaria isso ou eu seguiria isso? Segue → corpo. Consulta → arquivo próprio, ao lado do SKILL.md. Tabelas de apêndice, a referência completa de opções, a coleção longa de exemplos, o template de preencher.

A economia disso é quase de graça. Arquivo empacotado não custa nada até ser lido, o Claude carrega só o arquivo que a tarefa precisa e o código de um script empacotado nunca entra no contexto — só a saída dele entra. Então aquele PDF de 40 páginas vira um SKILL.md que cabe numa tela mais dois ou três arquivos irmãos.

Três detalhes decidem se esses arquivos vão ser lidos de fato. Mantenha toda referência a um nível de distância do SKILL.md — a documentação avisa que o Claude pode ler só parte de um arquivo alcançado por uma cadeia de referências, dando uma espiada com algo como head -100. Nomeie os arquivos pelo conteúdo (form_validation_rules.md, não doc2.md) e organize por domínio (reference/finance.md, reference/sales.md), pra que uma tarefa de outro assunto nunca os carregue. E se o documento vinha com um template ou um script, empacote junto e aponte com ${CLAUDE_SKILL_DIR}, que expande pro diretório da própria skill — assim o caminho continua valendo, não importa onde a skill foi instalada nem de qual pasta você abriu o Claude.

O único campo que o seu documento não consegue te dar

Tudo o que veio até aqui é extração. A description é autoria — porque nenhuma frase do seu PDF foi escrita pra combinar com o jeito que você vai pedir essa tarefa às nove da noite numa terça. Ela precisa carregar o que a skill faz e quando usar, e o trabalho dela é real: o Claude usa a description pra escolher a skill certa entre potencialmente mais de 100 disponíveis. O formato que a documentação usa vale copiar — capacidade primeiro, gatilhos depois, mais ou menos assim: "extrai texto e tabelas de arquivos PDF, preenche formulários, junta documentos. Use quando estiver trabalhando com arquivos PDF ou quando o usuário mencionar PDFs, formulários ou extração de documentos."

Vale o mesmo pro name. Título de documento costuma virar um substantivo vago — documents, helper, guide — e esses estão justamente na lista de nomes a evitar da documentação. Prefira a forma em gerúndio inglês: processing-invoices, reviewing-migrations, writing-status-updates.

O prompt de conversão

Anexe o documento e cole isso. É de propósito mais duro com o original do que o original merece.

Você vai converter um documento numa skill do Claude. Leia o documento anexado uma vez,
inteiro, e depois trabalhe pelas suas anotações — não releia ele mais nesta sessão.

Regras que valem pra tudo:
- Um documento explica pra quem lê; uma skill instrui um agente onde cada linha é custo
  recorrente de tokens. Apague tudo que só serve pra orientar um humano.
- Assuma que quem lê é uma pessoa competente da área. Corte definições, contexto de
  fundo e qualquer justificativa de por que tal ferramenta foi escolhida.
- Onde o documento lista alternativas, escolha um padrão e cite no máximo uma exceção.
- Reorganize na ordem de execução, não na ordem em que o documento ensinou.

PASSO 1 — CLASSIFIQUE. Em uma linha: isso é um PROCEDIMENTO (faça estes passos) ou um
PADRÃO (produza algo que atenda a estas regras)? Procedimento vira fluxo numerado com
checklist. Padrão vira regras mais um ciclo de revisão que confere a saída contra elas.

PASSO 2 — ME ENTREVISTE, uma pergunta por vez, só sobre o que o documento deixa
ambíguo: escolhas que ele apresenta sem decidir, valores deixados como placeholder e
passos cujo modo de falhar depende do meu setup. Não me pergunte nada que o documento
já responde.

PASSO 3 — ESCREVA A SKILL.
- name: minúsculo com hifens, em gerúndio inglês quando soar natural.
- description: o que ela faz E quando usar, com frases de gatilho concretas. Me pergunte
  as palavras exatas que eu uso quando peço essa tarefa e monte o gatilho a partir delas,
  não a partir do título do documento.
- Corpo: passos numerados (procedimento) ou regras mais ciclo de revisão (padrão). Marque
  o grau de liberdade de cada passo — passo frágil recebe um comando exato mais um "não
  modifique isso" explícito; passo de discernimento recebe uma lista curta de heurísticas.
  Mais curto é sempre melhor.
- Mova tudo que eu consultaria em vez de seguir — tabelas, referência completa de opções,
  conjuntos longos de exemplo, templates — pra arquivos irmãos, referenciados a um nível
  de distância do SKILL.md. Liste cada arquivo com o que tem dentro.

PASSO 4 — REPORTE, nesta ordem:
1. Contagem de palavras do original x do SKILL.md, em proporção.
2. REGISTRO DO QUE FOI APAGADO: cada seção descartada, com uma linha de justificativa.
3. Tudo que o documento presumia e nunca dizia, e que você teve que adivinhar.
4. Três pedidos que DEVEM disparar essa skill e dois parecidos que NÃO devem.
5. Onde salvar e a primeira frase que eu devo digitar pra disparar.

Depois, coloque onde ela roda de verdade

No Claude Code é uma pasta no disco: ~/.claude/skills/<nome>/SKILL.md pra valer em todo lugar, ou o .claude/skills/ do projeto quando uma segunda pessoa precisa — essa é a versão que entra no git. No claude.ai você zipa a pasta e sobe em Configurações, nos planos Pro, Max, Team ou Enterprise com execução de código ligada. Um detalhe que a documentação diz sem meias palavras: skills personalizadas não sincronizam entre as superfícies. Converter o documento uma vez não coloca a skill em todo lugar; cada superfície é um upload separado.

Por que isso pesa mais de São Paulo do que de São Francisco

Se você é dev ou EM brasileiro num time distribuído nos EUA ou na Europa, o conhecimento real do seu time já está em documentos — um runbook no Notion, um PDF de integração, uma especificação que ninguém abre. Eles foram escritos pra um leitor que podia virar pro lado e perguntar a metade que faltava. Às três da manhã no seu fuso você não pode, e um agente também não. Converter um deles numa skill obriga a ambiguidade a aparecer, e uma pasta .claude/skills/ versionada é um dos poucos artefatos que mostram esse discernimento enquanto você dorme.

Hoje: pegue o documento que o seu time vive re-explicando, rode o prompt acima e leia só o registro do que foi apagado. Se ele descartou uma seção que importava, você acabou de achar a ambiguidade que o documento escondia — corrija aquela linha, não a skill.

Fontes

• Claude Code docs — Extend Claude with skills
• Claude Docs — Skill authoring best practices
• Claude Docs — Agent Skills overview
• Claude Docs — PDF support
• Anthropic Engineering — Equipping agents for the real world with Agent Skills