Como transformar um livro técnico em skill de agente

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. O conversor cria um diretório de skill: um ficheiro de entrada com os frameworks identificados e um índice dos capítulos, além de um ficheiro por capítulo, que o agente só lê quando a pergunta o exige. O livro nunca entra na janela de contexto. O índice entra.

Esta é a tarefa oposta a escrever uma skill de agente de raiz, na qual codifica um procedimento que já conhece. Aqui, o conhecimento existe, mas ninguém consegue aceder-lhe: um PDF de fornecedor com 800 páginas 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 agosto 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.

[
  {
    "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 release

A skill é um repositório Git. Clone-a para o diretório skills do agente que utiliza. O nome do diretório torna-se o comando de barra, por isso o caminho do clone não é uma questão de preferência.

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 linha, npx skills add virgiliojr94/book-to-skill, que obtém a versão atual. Utilize-a para experimentar a ferramenta. Use o clone fixado para qualquer execução posterior.

Agora confirme quais extratores estão disponíveis no servidor:

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

--check mostra quais extratores estão instalados e imprime o comando de instalação de cada extrator em falta. O pacote requer Python 3.9 ou posterior.

Se /book-to-skill não aparecer no autocomplete depois do clone, reinicie o agente. O Claude Code monitoriza os diretórios de skills que existiam quando a sessão foi iniciada. Por isso, uma ~/.claude/skills/ criada há dois minutos ainda não está a ser monitorizada.

Quais extratores são realmente necessários?

Não é necessário instalar nada além do Python, porque todos os formatos têm uma alternativa baseada na biblioteca padrão. Essas alternativas são piores. Num servidor pequeno, o tempo desperdiçado está em instalar extratores que não serão utilizados.

• 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 relevante está nas tabelas e nas listagens de código. O projeto indica 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 caracteres) sobre um livro digitalizado que não tem qualquer camada de texto.

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

error: externally-managed-environment

O problema não está num pip avariado. O Ubuntu e o Debian marcam o Python do sistema como gerido pelo apt, por isso o pip recusa escrever nele. Há duas soluções. sudo apt install poppler-utils instala um binário e não precisa do pip, e pdftotext processa por si só a maioria dos PDFs em prosa. Para os extratores Python, crie um ambiente virtual e inicie o seu agente a partir dele. Assim, o python3 chamado pela skill é 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 repositório declara os extras pdf, epub, docx, rtf, technical e all, sendo technical o docling. A página de instalação do projeto também apresenta pip install "book-to-skill[pdf,epub,docx]", mas esse nome não está publicado no PyPI em agosto de 2026. Por isso, instale-o a partir da sua própria cópia de trabalho, como indicado acima.

Deixe docling de fora até que um livro precise dele. Esse 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 só vez, seguidos por um nome de skill opcional. Pode indicar qualquer conteúdo que esteja num diretório, 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. Se indicar um diretório de skill existente, as novas fontes serão incorporadas nessa skill em vez de ser criada uma segunda.

Uma execução interativa faz perguntas. O material é técnico ou contém sobretudo texto, o que determina o extractor? Pretende profundidade de referência ou de estudo, o que determina o orçamento por capítulo? Qual deve ser o nome da skill e em que skills root deve ser colocada? Antes de gerar o resultado, também apresenta uma estimativa de tokens e tempo 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 do início da execução. 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 pré-aprova as ferramentas de que a execução necessita, porque um pedido de permissão sem um terminal associado é 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 cada fonte num diretório de trabalho temporário em /tmp antes de qualquer leitura pelo modelo, e a última etapa da execução elimina esse diretório. Uma fonte cuja extração falhe é ignorada para que o lote continue, o que significa que 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 uma fonte em falta.

Execute isto num servidor que aceite disponibilizar a um agente. Executar o Claude Code com segurança numa 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: MIT abrange o conversor, não o livro

Seja preciso sobre este ponto, porque a falha aqui não é técnica.

• 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 hardware que controla, significa tirar notas a partir do seu próprio exemplar.
• Publicar o resultado é distribuição, e a licença MIT da ferramenta não lhe concede qualquer direito de distribuir conteúdo derivado do livro de outra pessoa.
• O resultado é uma obra derivada. Os frameworks e as conclusões dos capítulos continuam moldados 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 deve permanecer na máquina onde foi criada. Não num repositório público. Não num marketplace partilhado pela equipa.
• Publique quando a fonte lhe pertencer 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 base nisto. Não inclui conteúdo de livros, a extração é executada localmente e a etapa de publicação pergunta separadamente pela visibilidade do repositório. Essa pergunta aceita apenas a palavra isolada public ou private, sem inferir uma opção. Trate essa pergunta como a decisão de licenciamento, porque é isso que ela representa.

Os manuais internos têm 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 enviar para o repositório 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, e não medições nossas.

[
  {
    "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
  }
]

Nos 4 livros medidos pelo projeto, cada conversão custou entre 0.88 e 1.42 dólares americanos, com o Pro Git a 1.23. Os valores foram medidos no Claude Sonnet 4.5, com contagens de tokens obtidas a partir de tiktoken usando cl100k_base, e estão publicados no docs/performance.md do projeto em agosto de 2026. O seu valor varia consoante o modelo e os preços aplicados.

O projeto também documenta entre 24 e 51 vezes menos tokens para responder a uma única pergunta a partir da skill do que a partir do livro completo colado no contexto. Interprete isto como a ordem de grandeza da poupança, e 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 despejar o contexto é pago novamente em cada conversa que precise 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 mensagens que verá

Um PDF digitalizado não produz nada. O extrator verifica as primeiras páginas à procura de uma camada de texto e interrompe o processamento 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 como entrada.

O pip recusa-se a instalar. error: externally-managed-environment no Ubuntu 24.04 é a proteção do apt para o Python do sistema. Utilize o ambiente virtual acima ou instale poppler-utils e ignore o pip.

Os capítulos ficam incorretos. A deteção de capítulos procura cabeçalhos explícitos, como Chapter 7, e as respetivas variantes linguísticas. Um livro que utiliza títulos de secção simples ou algarismos romanos pode ser dividido incorretamente. A solução é indicar à execução onde começam os capítulos, em vez de depender de uma deteção automática.

O comando não existe. A ausência de /book-to-skill no preenchimento automático significa que o diretório de skills foi criado depois do início da sua sessão. Reinicie o agente.

O Docling demora demasiado. A cerca de 1.5 segundos por página, o processamento de 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 ao executar scripts/extract.py manualmente. --mode technical é a resposta que seleciona o docling.

Uma fonte desaparece silenciosamente. Um ficheiro que não pode ser lido é ignorado para permitir a conclusão do processamento em lote. A execução comunica então sucesso para menos fontes do que as fornecidas. O único local onde isso é indicado é o inventário de ficheiros do relatório final.

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, a menos que a licença do livro permita 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. A ferramenta também pergunta separadamente sobre a visibilidade do repositório e aceita apenas um public ou private simples, para que a decisão seja deliberada.

Preciso de docling ou pdftotext é suficiente?

pdftotext de poppler-utils é suficiente para prosa e é quase 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 de 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 os extratores nesse ambiente e inicie o seu agente a partir da mesma shell. A skill chama python3, portanto usa o interpretador que estiver no seu PATH. Esse interpretador passa a ser o do ambiente virtual.

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

Há duas causas. O nome do comando vem do nome do diretório. Por isso, 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, reinicie o agente. O Claude Code deteta alterações dentro de diretórios de skills que já esteja a monitorizar, mas um diretório de skills criado depois do início da sessão não está a ser monitorizado.