virgiliojr94/book-to-skill

Conversor Livro-para-Skill

Transforme conhecimento escrito em habilidades acionáveis para agentes, extraindo estrutura — não produzindo resumos.

Filosofia

Os livros contêm especialização cristalizada: frameworks, princípios e técnicas que levaram anos para ser desenvolvidos. Este skill extrai esse conhecimento para um formato que o GitHub Copilot CLI, Amp, Claude Code, Hermes Agent ou outro agente compatível possa aproveitar repetidamente.

Extraia estrutura, não resumos. Uma skill não é um relatório de livro. É um kit de ferramentas de:

• Frameworks nomeados (modelos mentais com aplicação clara)
• Princípios acionáveis (regras que guiam decisões)
• Técnicas (métodos passo a passo)
• Antipadrões (o que evitar e por quê)
• Calibração de voz (como o autor pensa e se comunica)

Preserve a precisão do autor. Frameworks geralmente têm nomes específicos por razões. "Os 5 Porquês" não é intercambiável com "pergunte por que várias vezes." Capture a formulação exata.

Camadas de profundidade apropriadas. Livros simples → skills simples. Livros complexos com 10+ frameworks → skills com arquivos de referência e capítulos sob demanda.

---

Modos de Operação

Quatro caminhos disponíveis. Roteie com base no que o usuário solicitar:

1. Conversão Completa (Padrão)

Gatilho: Usuário fornece um ou mais caminhos de documento/diretório/glob sem instruções especiais Ação: Execute todas as etapas abaixo (Etapas 0–9) Saída: Skill completa com SKILL.md, chapters/, glossary, patterns, cheatsheet

2. Apenas Analisar

Gatilho: Usuário diz "analisar", "apenas extrair" ou "quero revisar antes de gerar" Ação: Execute as Etapas 0–3 e, em seguida, produza um relatório de extração estruturado (frameworks, princípios, técnicas encontradas). Pare — NÃO gere arquivos de skill. Saída: Relatório de análise para revisão do usuário

3. Gerar a partir de Análise Prévia

Gatilho: Usuário possui notas de análise existentes ou executou apenas-análise anteriormente Ação: Pule as Etapas 0–3, use a análise fornecida como entrada, execute as Etapas 4–9 Saída: Arquivos de skill a partir da análise fornecida

4. Atualizar / Incorporar (Skill Existente)

Gatilho: Usuário fornece um ou mais novos caminhos de origem e indica que deseja atualizar uma skill existente (apontando para a pasta da skill existente, fornecendo um slug de skill que já existe em SKILLS_HOME, ou solicitando explicitamente uma atualização). Ação: Execute a Etapa 0 (verificação de escopo), Etapa 1 (validar entradas), Etapa 1.5 (identificar tipo de livro) e Etapa 2 (extrair novos arquivos). Em seguida, pule para a Etapa 5 (identificar/detectar caminho da skill existente) e execute o Fluxo de Trabalho de Atualização/Incorporação para mesclar o novo conteúdo nos arquivos de skill existentes. Saída: Skill existente atualizada com resumos de capítulos novos/revistos e índices/glossários mesclados.

---

Locais das Skills

Este conversor pode ser executado a partir de vários sistemas de skills. Ao procurar o script auxiliar deste conversor ou escrever a skill de livro gerada, prefira estas localizações nesta ordem:

1. Skills pessoais do GitHub Copilot CLI: ~/.copilot/skills/
2. Skills pessoais entre agentes (Copilot, Amp, Codex): ~/.agents/skills/
3. Skills pessoais do Claude Code: ~/.claude/skills/
4. Skills do Copilot local ao projeto: .github/skills/
5. Skills do Claude local ao projeto: .claude/skills/
6. Skills do Amp / Copilot local ao projeto: .agents/skills/
7. Skills globais do Amp: ~/.config/agents/skills/
8. Skills globais legadas do Amp: ~/.config/amp/skills/
9. Skills pessoais do Hermes Agent: $HERMES_HOME/skills/ (padrão para ~/.hermes/skills/)
10. Skills de projeto do Hermes Agent: .hermes/skills/ ou .agents/skills/

Para skills de livro geradas, prefira a raiz entre agentes ~/.agents/skills/ — uma cópia física atende todos os anfitriões suportados. Copilot CLI e Amp a descobrem nativamente; Claude Code precisa de um link simbólico de ~/.claude/skills/<nome_skill> (criado na Etapa 10, veja a Etapa 5 para as regras). Escolha uma raiz privada ao anfitrião ou local ao projeto apenas quando o usuário solicitar.

---

Etapa 0 — Verificação de escopo

Se nenhum argumento for fornecido, pare e responda:

"book-to-skill requer um caminho de documento suportado, pasta ou padrão glob. Uso: book-to-skill <caminho-para-pasta-documento-ou-glob>... [slug-nome-skill]"

Ao longo do fluxo de trabalho:

• Identifique os caminhos de entrada e o slug opcional da skill.
• Se o último argumento não for um arquivo, pasta ou glob que exista ou corresponda a algum arquivo, e parecer um slug de skill (ex. hífens minúsculos, alfanumérico), trate-o como SKILL_NAME.
• Trate todos os outros argumentos como a lista de INPUT_PATHS.
• Se qualquer caminho de entrada for um diretório de skill existente (contém SKILL.md e uma subpasta chapters/), ou se SKILL_NAME corresponder a um slug de skill existente em SKILLS_HOME, sinalize esta execução como uma operação de Atualização/Incorporação (Modo 4).

---

Etapa 1 — Validar entrada

Verifique se há pelo menos um arquivo suportado, diretório ou padrão glob entre os INPUT_PATHS. Para diretórios e globs, expanda-os para encontrar arquivos suportados correspondentes (.pdf, .epub, .docx, .txt, .md, .markdown, .rst, .adoc, .html, .htm, .rtf, .mobi, .azw, .azw3).

Se nenhum arquivo suportado for encontrado, pare com uma mensagem de erro clara.

---

Etapa 1.5 — Identificar tipo de conteúdo

Antes de extrair, pergunte ao usuário:

"Que tipo de conteúdo essas fontes têm? Isso me ajuda a escolher o melhor método de extração.

1. Técnico — tem blocos de código, tabelas, fórmulas, diagramas (ex. livros de programação, artigos acadêmicos, guias de arquitetura)
2. Texto denso — principalmente prosa, poucas ou nenhuma tabela/código (ex. gestão, produtividade, não-ficção narrativa)
3. Não sei — Usarei o método rápido e avisarei se a qualidade parecer limitada"

Armazene a resposta como BOOK_TYPE:

• Opção 1 → BOOK_TYPE=technical
• Opção 2 → BOOK_TYPE=text
• Opção 3 → BOOK_TYPE=text

Se BOOK_TYPE=technical, informe o usuário antes de prosseguir:

"📐 Modo técnico selecionado — usando Docling para extração ciente de estrutura (tabelas, blocos de código, fórmulas preservados como markdown). Isso leva ~1,5s por página, então espere alguns minutos para fontes mais longas. Começando agora…"

Se BOOK_TYPE=text, informe:

"📄 Modo texto selecionado — usando o extrator mais rápido adequado para cada tipo de arquivo. Texto simples/Markdown/HTML geralmente ficam prontos em segundos; PDFs usam pdftotext quando disponível."

---

Etapa 2 — Extrair texto dos documentos de origem

Execute o script de extração, passando os caminhos de entrada:

SCRIPT_PATH=""
HERMES_HOME_RESOLVED="${HERMES_HOME:-$HOME/.hermes}"
PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || true)"
HERMES_PROJECT_TRUSTED=false
if [ -n "$PROJECT_ROOT" ] && [ "${HERMES_AGENT:-}" = true ] && \
  command -v hermes >/dev/null 2>&1 && \
  command -v python3 >/dev/null 2>&1 && \
  hermes config get skills.trusted_project_dirs --json 2>/dev/null | PROJECT_ROOT="$PROJECT_ROOT" python3 -c 'import json, os, pathlib, sys; root=pathlib.Path(os.environ["PROJECT_ROOT"]).resolve(); sys.exit(not any(pathlib.Path(p).expanduser().resolve() == root for p in json.load(sys.stdin)))' 2>/dev/null
then
  HERMES_PROJECT_TRUSTED=true
fi

CANDIDATES=(
  "$HOME/.copilot/skills/book-to-skill/scripts/extract.py"
  "$HOME/.agents/skills/book-to-skill/scripts/extract.py"
  "$HOME/.claude/skills/book-to-skill/scripts/extract.py"
  "$HERMES_HOME_RESOLVED/skills/book-to-skill/scripts/extract.py"
  "$HERMES_HOME_RESOLVED"/skills/*/book-to-skill/scripts/extract.py
)
if [ "${HERMES_AGENT:-}" != true ]; then
  CANDIDATES+=(
    ".github/skills/book-to-skill/scripts/extract.py"
    ".claude/skills/book-to-skill/scripts/extract.py"
    ".agents/skills/book-to-skill/scripts/extract.py"
  )
fi
CANDIDATES+=(
  "$HOME/.config/agents/skills/book-to-skill/scripts/extract.py"
  "$HOME/.config/amp/skills/book-to-skill/scripts/extract.py"
)
if [ "$HERMES_PROJECT_TRUSTED" = true ]; then
  CANDIDATES=(
    "$PROJECT_ROOT/.hermes/skills/book-to-skill/scripts/extract.py"
    "$PROJECT_ROOT/.hermes/skills"/*/book-to-skill/scripts/extract.py
    "$PROJECT_ROOT/.agents/skills/book-to-skill/scripts/extract.py"
    "$PROJECT_ROOT/.agents/skills"/*/book-to-skill/scripts/extract.py
    "${CANDIDATES[@]}"
  )
fi
for candidate in "${CANDIDATES[@]}"
do
  if [ -f "$candidate" ]; then
    SCRIPT_PATH="$candidate"
    break
  fi
done

if [ -z "$SCRIPT_PATH" ]; then
  echo "Não foi possível encontrar scripts/extract.py para book-to-skill" >&2
  exit 1
fi

PYTHON_BIN="${PYTHON_BIN:-python3}"
if ! command -v "$PYTHON_BIN" >/dev/null 2>&1; then
  PYTHON_BIN="python"
fi

"$PYTHON_BIN" "$SCRIPT_PATH" $INPUT_PATHS --mode <BOOK_TYPE> --install-missing ask

Antes da extração, o script verifica pacotes Python opcionais necessários para o formato detectado. Se um extrator melhor estiver faltando, ele solicita ao usuário a alternativa disponível. Sessões não interativas usam a alternativa como padrão, a menos que o modo de instalação seja explicitamente yes.

Dica — pré-verifique o ambiente: execute "$PYTHON_BIN" "$SCRIPT_PATH" --check para imprimir um relatório por formato de quais extratores estão instalados e o comando exato para instalar o que está faltando, sem processar nenhum arquivo. Útil quando um usuário relata um problema de configuração ou qualidade.

Isso cria um diretório de trabalho por execução — <tempdir>/book_skill_work-<pid>/ por padrão, ou exatamente o caminho definido em BOOK_SKILL_WORKDIR — contendo:

• full_text.txt — texto extraído combinado de todas as fontes com limites visualmente demarcados claramente.
• metadata.json — tamanho total combinado, palavras, páginas, contagens de tokens, contagens de imagens descartadas de EPUB, o workdir resolvido e uma lista detalhada de sources processadas individualmente.

A execução imprime os três caminhos ao final (Workdir ->, Text ->, Meta ->). Pegue os caminhos dessa saída (ou do campo workdir do próprio metadata.json) em vez de assumir uma localização fixa — o nome do diretório difere por execução para que extrações simultâneas em uma mesma máquina não possam sobrescrever os resultados umas das outras.

Leia o metadata.json dessa execução para inspecionar os resultados.

Sempre confirme que a extração é do documento que você solicitou antes de gerar qualquer coisa: verifique filename / source_file em metadata.json, ou o cabeçalho SOURCE: na primeira linha do full_text.txt. Se você estiver aguardando uma execução em segundo plano, aguarde o workdir específico dela — pesquisar em um caminho compartilhado pode exibir a saída de uma execução diferente.

---

Etapa 2.5 — Estimativa de custo pré-execução

Leia o metadata.json desta execução (o caminho Meta -> da saída da extração) e apresente ao usuário uma estimativa antes de fazer qualquer geração:

📖 Fontes detectadas: <total_sources> fonte(s)
<lista cada nome de arquivo fonte e formato da lista de fontes no metadata>
<se images_dropped > 5: avisa que N imagens fonte não foram lidas>
📄 Páginas/Seções combinadas: ~<N> | Palavras: ~<N> | Total de tokens: ~<N>K

💰 Custo estimado de tokens (Conversão Completa / Atualização):
   Entrada  (leitura + prompts): ~<N>K tokens
   Saída (arquivos de skill gerados/atualizados):  ~<N>K tokens
   Total:                           ~<N>K tokens

   Custo: multiplique as contagens de tokens acima pelas taxas atuais
   de entrada/saída por 1M-tokens do seu modelo (preços e nomes de modelos mudam
   frequentemente — não os codifique; cite a taxa de hoje e rotule como uma estimativa).

   ⏱  Tempo estimado: ~<N> minutos

📁 Arquivos a serem gerados/atualizados:
   SKILL.md + arquivos de capítulo + glossário + padrões + cheatsheet

➡  Prosseguir com Conversão Completa / Atualização? (ou digite "apenas analisar" para visualizar primeiro)

Como estimar:

• Tokens de entrada ≈ estimated_tokens do metadata × 1.3 (sobrecarga de prompts por passagem de capítulo)
• Tokens de saída ≈ capítulos × orçamento por capítulo + 4.000 (SKILL.md) + 4.500 (glossário + padrões + cheatsheet)
  • Ponto médio do orçamento por capítulo por BOOK_TYPE (PROFUNDIDADE é decidida depois na Etapa 4 e pode aumentá-lo): text ≈ 1.000, technical ≈ 1.800. Se o usuário já indicou apenas-referência vs estudo aprofundado, use a linha correspondente da matriz da Etapa 7.
• Custo: informe as contagens de tokens e multiplique pelas taxas atuais de entrada/saída por 1M-tokens do usuário. NÃO codifique valores em dólar — nomes e preços de modelos mudam; se você mostrar um, rotule-o como uma estimativa e date-o.

Aguarde a confirmação do usuário antes de prosseguir. Se ele disser "apenas analisar", mude para o Modo 2.

---

Etapa 2.6 — Acesso estilo REPL para livros grandes (> 50k tokens)

Inspirado no paradigma Recursive Language Model (RLM): trate full_text.txt como um corpus consultável, não como uma única leitura. Carregar o arquivo inteiro no contexto queima o orçamento que você precisará depois para a geração.

Para livros com mais de ~50k tokens, prefira sondas programáticas em vez de Read(full_text.txt) sem limites:

# Verificação de tamanho antes de qualquer Read
wc -w "$FULL_TEXT_PATH"

# Encontrar deslocamentos de capítulo sem carregar o arquivo inteiro
grep -n -E "^\s*(Chapter|CHAPTER)\s+[0-9]+" "$FULL_TEXT_PATH" | head -40

# Puxar apenas o capítulo que você precisa (linhas início..fim inclusive)
sed -n '<start>,<end>p' "$FULL_TEXT_PATH"

# Verificar se um framework é realmente mencionado antes de reivindicá-lo no SKILL.md
grep -c -i "westrum\|dora" "$FULL_TEXT_PATH"

# Read direcionada com offset/limit evita despejar o arquivo inteiro
# Read(file_path=full_text.txt, offset=<linha>, limit=<linhas>)

Use esta abordagem para a Etapa 3 (análise de estrutura), Etapa 7 (resumos por capítulo) e Etapa 8 (extração de glossário / padrões). Em livros com menos de 50k tokens, um único Read é suficiente.

Por que isso importa: um livro de 200 páginas tem ~75k tokens. Relê-lo uma vez por capítulo (28 passagens) causa...