SSD Nodes Learn Hosting plans →
Guias Matt ConnorPor Matt Connor

Como transformar um livro técnico em skill de agente

Converta PDF, EPUB, DOCX ou documentos internos em uma skill carregada sob demanda, com instalação local, limite de tokens, execução headless e licença.

Transformar um livro técnico numa skill de agente: o que obtém

Para transformar um livro técnico numa skill de agente, indique ao conversor um PDF, um EPUB, uma exportação DOCX ou uma pasta com documentos internos que já possui. A ferramenta cria um diretório de skill: um ficheiro de entrada com os frameworks nomeados e um índice dos capítulos, além de um ficheiro por capítulo, que o agente lê apenas quando a sua pergunta o exige. O livro nunca entra na janela de contexto. O índice entra.

Este é o trabalho oposto a escrever uma skill de agente de raiz, em que codifica um procedimento que já conhece. Aqui, o conhecimento existe, mas ninguém consegue aceder-lhe: um PDF de 800 páginas de um fornecedor ou um manual que não é aberto desde que a pessoa que o escreveu saiu da empresa. O trabalho consiste em comprimir e indexar o conteúdo. Se o termo skill é novo para si, leia primeiro o que é realmente uma skill de agente.

O conversor usado aqui é book-to-skill, uma skill com licença MIT que é executada na sua própria máquina. A tag atual, em outubro de 2026, é v1.4.0. A estrutura que produz é mais importante do que a própria ferramenta, e a última secção antes do FAQ mostra como criar a mesma estrutura manualmente.

Por que o orçamento de tokens é a base de todo o design

Um livro colado numa janela de contexto custa o seu tamanho total em todas as conversas que precisam dele. Uma skill custa o seu ficheiro de entrada uma vez, além dos capítulos que a pergunta realmente utiliza. O projeto define um orçamento para cada ficheiro que gera.

GráficoDocumented token budget per generated file, book-to-skill v1.4.0
Os dados por trás deste gráfico
[
  {
    "label": "SKILL.md entry file",
    "tokens": "4,000"
  },
  {
    "label": "One chapter file",
    "tokens": "1,000"
  },
  {
    "label": "glossary.md",
    "tokens": "1,500"
  },
  {
    "label": "patterns.md",
    "tokens": "2,000"
  },
  {
    "label": "cheatsheet.md",
    "tokens": "1,000"
  }
]

O ficheiro de entrada, SKILL.md, é limitado a 4,000 tokens e contém os frameworks identificados e o índice dos capítulos. Cada ficheiro de capítulo tem cerca de 1,000 tokens e permanece no disco até que algo o solicite. Os ficheiros de suporte são semelhantes: 1,500 tokens para glossary.md, 2,000 para patterns.md e 1,000 para cheatsheet.md.

Esses orçamentos correspondem à forma como o Claude Code utiliza efetivamente o contexto. O description de uma skill permanece na lista de skills para que o modelo saiba que a skill existe. O corpo é carregado quando a skill é invocada e, depois de carregado, permanece no contexto durante o resto da sessão. Por isso, cada linha do ficheiro de entrada representa um custo recorrente. Os ficheiros de suporte só são carregados quando o agente os lê, o que torna os ficheiros separados por capítulo económicos.

Existe um limite mais rigoroso por trás desse valor do ficheiro de entrada. Quando a compactação automática resume uma conversa longa, o Claude Code volta a anexar, depois do resumo, a invocação mais recente de cada skill e mantém os primeiros 5,000 tokens de cada uma, dentro de um orçamento combinado de 25,000 tokens para todas as skills novamente anexadas. Um ficheiro de entrada que caiba em 5,000 tokens sobrevive integralmente à compactação. Um ficheiro de entrada com 20,000 tokens regressa apenas com o seu primeiro quarto, sem qualquer indicação dos três quartos que desapareceram.

Isto é divulgação progressiva: um índice pequeno cujo custo compensa sempre e a maior parte do material atrás de uma porta que o agente abre deliberadamente. Como o Claude Code gere a sua janela de contexto explica o restante desse cálculo.

Instale o conversor no seu VPS, fixado numa versão

A skill é um repositório git. Clone-a no diretório de skills do agente que utiliza. O nome do diretório torna-se o comando slash, por isso o caminho do clone não é uma escolha meramente estética.

git clone --depth 1 --branch v1.4.0 \
  https://github.com/virgiliojr94/book-to-skill.git \
  ~/.claude/skills/book-to-skill

--branch aceita uma tag, por isso este comando faz checkout de v1.4.0 e de nenhuma versão posterior. Fixe a versão, porque uma skill é um conjunto de instruções que o agente segue, e uma alteração não revista nessas instruções altera o que é executado no seu servidor. O GitHub Copilot CLI lê ~/.copilot/skills/, enquanto o Amp lê ~/.agents/skills/.

Também existe uma instalação numa única linha, npx skills add virgiliojr94/book-to-skill, que obtém a versão atual. Use-a para testar a ferramenta. Use o clone fixado para tudo o que executar novamente.

Agora confirme quais extratores estão instalados no servidor:

cd ~/.claude/skills/book-to-skill
python3 scripts/extract.py --check

--check informa quais extratores estão instalados e mostra o que deve ser instalado para os que estiverem em falta: um único comando pip combinado para os pacotes Python em falta e uma indicação para cada ferramenta de sistema em falta. O pacote requer Python 3.9 ou posterior.

Se /book-to-skill não aparecer no preenchimento automático depois do clone, execute /reload-skills ou reinicie o agente. O Claude Code monitoriza os diretórios de skills que existiam quando a sessão foi iniciada. Por isso, um ~/.claude/skills/ criado há dois minutos ainda não está a ser monitorizado.

De que extratores precisa realmente?

Além do Python, nada é obrigatório, porque todos os formatos têm uma alternativa na biblioteca padrão. As alternativas são piores, e num servidor pequeno o tempo desperdiçado está em instalar extratores que não vai utilizar.

  • pdftotext, do pacote poppler-utils, processa PDFs com muito texto e é quase instantâneo. Instale-o com sudo apt install poppler-utils.
  • pypdf e pdfminer.six são as alternativas Python para PDF.
  • docling destina-se a PDFs técnicos cujo conteúdo importante está nas tabelas e nas listagens de código. O projeto mede um tempo de aproximadamente 1.5 segundos por página.
  • ebooklib com beautifulsoup4 lê EPUB corretamente. Sem eles, a ferramenta recorre ao leitor zipfile da biblioteca padrão.
  • python-docx lê DOCX e striprtf lê RTF.
  • O ebook-convert do Calibre é necessário para ficheiros MOBI e AZW.
  • ocrmypdf executa OCR (reconhecimento ótico de carateres) sobre um livro digitalizado que não tem qualquer camada de texto.

No Ubuntu 24.04, um pip3 install pypdf simples termina com isto:

error: externally-managed-environment

Isto não significa que o pip esteja avariado. O Ubuntu e o Debian marcam o Python do sistema como gerido pelo apt, por isso o pip recusa-se a escrever nele. Há duas soluções. sudo apt install poppler-utils instala um binário e não precisa do pip, e pdftotext processa a maioria dos PDFs de prosa sem ajuda adicional. Para os extratores Python, crie um ambiente virtual e inicie o seu agente a partir dele, para que o python3 chamado pela skill seja o interpretador que tem os pacotes instalados.

python3 -m venv ~/.venvs/book-to-skill
source ~/.venvs/book-to-skill/bin/activate
pip install "$HOME/.claude/skills/book-to-skill[pdf,epub,docx]"
claude

O checkout v1.4.0 fixado declara os extras pdf, epub, docx, rtf, technical e all, sendo technical docling. A página de instalação do projeto também documenta uma instalação autónoma pela linha de comandos diretamente do GitHub, pip install "book-to-skill[pdf,epub,docx] @ git+https://github.com/virgiliojr94/book-to-skill.git", seguida de book-to-skill --check para listar os extratores instalados. Isto não precisa de uma versão publicada no PyPI, mas instala o branch predefinido do projeto em vez de v1.4.0 e fornece apenas o comando do extrator, não a skill /book-to-skill. Para uma configuração fixada, instale a partir do seu próprio checkout, como acima. Um pip install book-to-skill simples não funciona, porque esse nome não está publicado no PyPI em outubro de 2026.

Deixe docling de fora até que algum livro precise dele. Este pacote instala uma stack de machine learning, por isso verifique o espaço livre em disco num plano pequeno antes de o instalar.

Execute em uma pasta de documentos, inclusive sem interação

O comando aceita um ficheiro, uma pasta, um glob entre aspas ou vários caminhos de uma vez, seguidos de um nome de skill opcional. Qualquer conteúdo que possa colocar num diretório funciona, incluindo um conjunto de RFCs (request for comments, os documentos que definem os protocolos da Internet).

/book-to-skill ~/library/platform-docs/ platform-handbook
/book-to-skill "~/books/*.epub" my-library
/book-to-skill ~/papers/paper1.pdf ~/notes/export.txt unified-research

Coloque o glob entre aspas para que a sua shell não o expanda antes de a skill o receber. Apontar o comando para um diretório de skill existente incorpora as novas fontes nessa skill, em vez de criar uma segunda.

Uma execução interativa faz perguntas. O material é técnico ou contém sobretudo texto? Isso determina o extractor. Para que deve servir a skill? Isso define a profundidade de referência ou estudo e, com ela, o orçamento por capítulo. Qual deve ser o nome da skill e, quando ainda não existe uma skills root ou existe mais de uma, em que root deve ser colocada? O comando também mostra uma estimativa de tokens e tempo antes da geração e aguarda a sua confirmação.

Uma execução sem interação não tem ninguém para responder a essas perguntas. As skills invocáveis pelo utilizador funcionam em claude -p: coloque o comando slash na string do prompt e o Claude Code expande-o antes de a execução começar. Por isso, responda às perguntas no mesmo prompt.

claude -p "/book-to-skill ~/library/platform-docs/ platform-handbook
The sources are technical. Use reference depth. Write the skill to
~/.claude/skills/. Do not publish it to GitHub. Proceed without asking me." \
  --allowedTools "Bash,Read,Write,Edit"

--allowedTools aprova previamente as ferramentas de que a execução precisa, porque um pedido de permissão sem um terminal ligado é uma execução que nunca termina. Adicionar --output-format json inclui total_cost_usd no resultado. Trata-se de uma estimativa do lado do cliente, não do valor cobrado.

A extração consolida todas as fontes num diretório de trabalho temporário em /tmp antes de qualquer leitura pelo modelo. O último passo da execução elimina esse diretório. Uma fonte cuja extração falhe é ignorada para que o lote continue. Por isso, uma execução pode indicar sucesso depois de ler menos ficheiros do que os fornecidos. Compare o inventário de ficheiros do relatório final com o conteúdo da pasta. Um capítulo em falta normalmente indica uma fonte em falta.

Dê à execução um servidor que se sinta confortável em disponibilizar a um agente. Executar o Claude Code com segurança num VPS aborda o controlo de permissões.

Para onde vai a saída para que o seu agente de programação a encontre

A skill gerada é instalada numa raiz de skills. Duas são importantes.

  • ~/.claude/skills/<skill-name>/ é pessoal e está disponível em todos os projetos dessa máquina.
  • .claude/skills/<skill-name>/ fica dentro de um repositório e é transportada com ele.

Dentro de qualquer uma delas, encontra SKILL.md, um diretório chapters/ com um ficheiro por capítulo e os ficheiros de suporte. O nome do diretório é o comando, portanto ~/.claude/skills/platform-handbook/ fornece /platform-handbook, que pode ser seguido por um tópico ou por uma pergunta simples.

Escolha a raiz com base na licença, não na conveniência. Uma skill criada a partir de um livro que comprou pertence ao seu diretório pessoal. Uma skill criada a partir de documentação escrita pela sua própria equipa pertence ao repositório. Nesse caso, partilhar uma skill entre vários repositórios passa a ser o próximo problema a resolver.

Existe um custo que aumenta a cada skill adicionada. A descrição de cada skill permanece na listagem de skills para que o modelo possa decidir se deve utilizá-la. O texto combinado das descrições é truncado em 1,536 caracteres por entrada, e a listagem inteira tem um limite. Dez skills de livros significam dez descrições a competir por esse limite. Para as skills que chama sempre pelo nome, adicione uma linha ao frontmatter gerado:

---
name: platform-handbook
description: Frameworks and chapter index from the internal platform handbook.
disable-model-invocation: true
---

Com disable-model-invocation: true, a descrição permanece completamente fora do contexto, e a skill continua a ser carregada integralmente quando escreve /platform-handbook. Deixa de ter descoberta automática, mas obtém uma janela de contexto com menos ruído.

Licenciamento: o MIT abrange o conversor, não o livro

Seja exato sobre isto, porque o problema aqui não é técnico.

  • A licença MIT abrange o código do conversor e a definição da sua skill. Não diz nada sobre o documento que lhe fornece.
  • Executar o conversor sobre um livro que comprou, num equipamento que controla, significa fazer anotações a partir da sua própria cópia.
  • Publicar o resultado é distribuição, e a licença MIT da ferramenta não lhe concede o direito de distribuir nada derivado do livro de outra pessoa.
  • O resultado é uma obra derivada. As estruturas e as conclusões dos capítulos continuam moldadas pela fonte, e uma obra derivada continua sujeita aos direitos de autor da fonte.
  • Uma skill criada a partir de material que não pode redistribuir permanece na máquina que a criou. Não deve ficar num repositório público nem num marketplace partilhado pela equipa.
  • Publique quando a fonte for sua ou tiver uma licença aberta: documentação escrita pela sua equipa ou uma norma cujos termos permitam a redistribuição.

A ferramenta foi concebida com isto em mente. Não inclui conteúdo de livros, e a extração é executada localmente. O v1.4.0 fixado apenas imprime uma linha gh skill publish opcional e nunca pergunta sobre a visibilidade. Nesse caso, a decisão depende inteiramente de si. Desde então, o branch predefinido do projeto adicionou uma etapa de publicação que pergunta a visibilidade do repositório como uma pergunta separada de uma palavra e cria um repositório público apenas quando a resposta é a palavra isolada public; qualquer outra resposta resulta num repositório privado. Trate essa etapa como a decisão de licenciamento, porque é isso que ela representa.

Os manuais internos trazem um segundo problema. Contêm credenciais com mais frequência do que se admite, e um conversor transforma um PDF que ninguém abre num ficheiro que o seu agente lê quando necessário. Leia os ficheiros gerados uma vez antes de os versionar e consulte manter segredos fora dos seus agentes de IA.

Quanto custa uma conversão?

Os números abaixo são medições publicadas pelo próprio projeto, não medições nossas.

GráficoCost to convert one full-length book, as published by the project
Os dados por trás deste gráfico
[
  {
    "label": "Think Python 2",
    "cost_usd": 0.88
  },
  {
    "label": "Working Backwards",
    "cost_usd": 0.96
  },
  {
    "label": "Pro Git",
    "cost_usd": 1.23
  },
  {
    "label": "Moby-Dick",
    "cost_usd": 1.42
  }
]

Nas 4 obras que o projeto mediu, uma conversão custou entre 0.88 e 1.42 dólares americanos, com o Pro Git em 1.23. Os valores foram medidos no Claude Sonnet 4.5, com contagens de tokens de tiktoken usando cl100k_base, e estão publicados no docs/performance.md do projeto desde outubro de 2026. O seu valor varia consoante o modelo e os preços que utiliza.

O projeto também documenta entre 24 e 51 vezes menos tokens para responder a uma única pergunta a partir da competência do que a partir do livro completo colado no contexto. Interprete isto como a dimensão da poupança, não como uma garantia, porque o resultado depende do livro e da pergunta. O ponto estrutural mantém-se: a conversão é paga uma vez, enquanto um despejo de contexto é pago novamente em cada conversa que precisa do livro.

Por que não colar o PDF ou criar um índice RAG?

Colar o conteúdo funciona e é a resposta certa para uma pergunta sobre um documento. Deixa de ser a resposta certa quando o mesmo livro é necessário na terça-feira e novamente na sexta-feira, porque o tamanho completo é cobrado a cada utilização.

A recuperação, ou RAG (retrieval augmented generation), pesquisa no momento da consulta e devolve as passagens que correspondem às suas palavras. Isso é útil quando precisa da frase exata. É menos útil quando o conteúdo necessário é uma estrutura distribuída por um capítulo, porque nenhuma passagem isolada a contém. Uma skill faz essa extração uma vez, durante a conversão, e armazena a estrutura em vez das passagens.

O limite deve ser claro: uma skill gerada é um resumo com perda de informação, escrito por um modelo. É um auxiliar de estudo, e a fonte continua a ser a fonte. Quando a redação exata tem peso jurídico ou protocolar, mantenha o PDF e faça a citação a partir dele. Skills comparadas com servidores MCP e ficheiros de regras explica onde cada abordagem deve ser utilizada.

Modos de falha e as mensagens que verá

Um PDF digitalizado não produz nada. O extrator verifica as páginas iniciais à procura de uma camada de texto e termina com uma explicação, em vez de processar 400 páginas de imagens. Execute ocrmypdf input.pdf output.pdf primeiro e, depois, forneça o ficheiro de saída.

O pip recusa-se a instalar. O error: externally-managed-environment no Ubuntu 24.04 é o Python do sistema protegido pelo apt. Use o ambiente virtual acima ou instale poppler-utils e não use o pip.

Os capítulos ficam incorretos. A deteção de capítulos procura títulos explícitos, como Chapter 7 e as respetivas variantes linguísticas. Também reconhece algarismos romanos, como Chapter IV ou IV. Title. Um livro que use títulos de secção simples e sem numeração produz uma divisão incorreta. A solução é indicar à execução onde começam os capítulos, em vez de esperar que a deteção acerte.

O comando não existe. Se /book-to-skill não aparecer no preenchimento automático, o diretório de skills foi criado depois do início da sessão. Execute /reload-skills ou reinicie o agente.

O Docling demora demasiado. A cerca de 1.5 segundos por página, um livro longo consome vários minutos de CPU. Num servidor partilhado, essa execução concorre com os restantes serviços alojados. Responda "text-heavy" quando a execução perguntar pelo tipo de conteúdo ou forneça --mode text quando executar scripts/extract.py manualmente. --mode technical é a resposta que seleciona o docling.

Uma fonte desaparece sem aviso. Um ficheiro que não possa ser lido é ignorado para que o processamento em lote termine. A execução indica então sucesso para menos fontes do que as fornecidas. O único local onde isso fica visível é o inventário de ficheiros do relatório final. Comparar uma execução concluída com aquilo que foi efetivamente fornecido é uma prática útil para além desta ferramenta. O método Depth Tree da skill unlazy é uma forma de levar o agente a seguir o mesmo padrão, em vez de declarar o trabalho concluído prematuramente.

Aplicar o mesmo padrão manualmente

A ferramenta é apenas uma conveniência. A estrutura é a parte reutilizável, e um editor de texto pode criá-la para qualquer material de referência que você possua.

  1. Escreva um arquivo de entrada e mantenha-o próximo dos tokens 4,000 que o conversor utiliza como objetivo. Inclua nele os conceitos nomeados com as formulações exatas e também um índice com todos os arquivos de detalhes e os tópicos abordados por cada arquivo.
  2. Divida o material em arquivos com aproximadamente 1,000 tokens, um tópico por arquivo. Dê nomes que permitam identificar o conteúdo apenas pelo nome do arquivo.
  3. Descreva cada um desses arquivos no arquivo de entrada, na frase que informa quando ele deve ser lido.

O passo 3 é o que as pessoas costumam ignorar, mas é ele que faz o padrão funcionar. O agente decide o que abrir lendo o índice. Portanto, um arquivo que o índice não descreve nunca é aberto pelo agente. O índice é o produto, e os arquivos de capítulos são o armazenamento.

Mantenha o arquivo de entrada dentro do orçamento de compactação para que toda a estrutura sobreviva a uma sessão longa. Essa regra vale tanto se um conversor criou os arquivos quanto se você os criou.

FAQ

Posso publicar uma skill criada a partir de um livro que comprei?

Não, exceto se a licença do livro permitir a redistribuição. A licença MIT do conversor abrange o código do conversor, não o material que lhe fornece, e a skill gerada é uma obra derivada do livro. Mantenha-a em ~/.claude/skills/ na sua própria máquina. Pode publicar documentação escrita por si ou baseada em fontes com licença aberta. O v1.4.0 fixado nunca pergunta sobre visibilidade, enquanto o branch predefinido do projeto agora faz essa pergunta separadamente e torna o conteúdo público apenas com um public vazio. Em qualquer dos casos, a decisão deve ser tomada deliberadamente.

Preciso do docling ou o pdftotext é suficiente?

pdftotext de poppler-utils é suficiente para prosa e é praticamente instantâneo. Instale docling quando o valor do livro estiver nas tabelas e nas listagens de código, porque um extrator de texto simples elimina precisamente esses elementos. A contrapartida é a velocidade: o projeto mede o docling em cerca de 1.5 segundos por página, portanto um manual com 300 páginas consome vários minutos de CPU numa VPS.

Por que motivo o pip falha com externally-managed-environment na minha VPS?

O Ubuntu 24.04 e as versões atuais do Debian marcam o Python do sistema como gerido pelo apt. Por isso, o pip recusa-se a instalar pacotes nesse ambiente e apresenta error: externally-managed-environment. Crie um ambiente virtual com python3 -m venv ~/.venvs/book-to-skill, ative-o, instale aí os extratores e inicie o seu agente a partir dessa mesma shell. A skill chama python3, por isso utiliza o interpretador que estiver no seu PATH. Esse interpretador é agora o do ambiente virtual.

Por que motivo a skill gerada não aparece como comando de barra?

Há duas causas. O nome do comando vem do nome do diretório, portanto a skill tem de estar em ~/.claude/skills/<name>/SKILL.md ou .claude/skills/<name>/SKILL.md, com SKILL.md escrito exatamente dessa forma. Se o caminho estiver correto, execute /reload-skills ou reinicie o agente. O Claude Code deteta alterações dentro dos diretórios de skills que já monitoriza, mas um diretório de skills criado depois do início da sessão não é monitorizado até executar uma dessas ações.

Este artigo foi útil?