name: gerar-quiz-rag description: "Gerador e executor de quiz sobre conhecimento RAG. Comandos: '/gerar-quiz-rag gerar' para gerar perguntas do banco RAG e salvar em JSON, '/gerar-quiz-rag iniciar' para executar quiz de 10 perguntas, '/gerar-quiz-rag status' para ver progresso. Claude consulta o banco SQLite RAG e gera perguntas diretamente."

Quiz RAG - Skill do Claude Code

⚠️ IMPORTANTE: Nome Completo Qualificado

Ao invocar este skill via Skill tool (não via comando do usuário), você DEVE usar o nome completo qualificado:

✅ CORRETO: skill: "gerar-quiz-rag:gerar-quiz-rag"
❌ ERRADO:  skill: "gerar-quiz-rag"

Por quê?

O nome curto gerar-quiz-rag pode causar erro: Unknown skill: gerar-quiz-rag
O sistema requer o formato completo: <namespace>:<skill-name>
Para este skill: gerar-quiz-rag:gerar-quiz-rag

Quando usar:

Quando Claude invoca o skill programaticamente via Skill tool
Quando há necessidade de desambiguação entre skills com nomes similares

Comandos do usuário (continuam funcionando normalmente):

/gerar-quiz-rag gerar 30 ✅
/gerar-quiz-rag iniciar ✅
/gerar-quiz-rag status ✅

Visão Geral

Esta skill permite ao Claude:

Gerar perguntas consultando o banco de dados RAG (SQLite) e salvando em JSON
Executar quizzes de 10 perguntas com feedback imediato
Gerenciar banco de perguntas em formato JSON puro

IMPORTANTE: Claude gera as perguntas consultando o banco RAG SQLite diretamente.

Comandos da Skill

`/gerar-quiz-rag gerar [quantidade]`

Gera perguntas consultando o banco RAG e salva no JSON.

MÉTODO PADRÃO: SUBAGENTS EM PARALELO ⚡

IMPORTANTE: SEMPRE usar subagents para máxima velocidade e qualidade!

Exemplos:

/gerar-quiz-rag gerar → 10 perguntas (1 subagent)
/gerar-quiz-rag gerar 50 → 50 perguntas (5 subagents paralelos)
/gerar-quiz-rag gerar 100 → 100 perguntas (10 subagents paralelos)
/gerar-quiz-rag gerar 200 → 200 perguntas (20 subagents paralelos) ⚡
/gerar-quiz-rag gerar completo → Máximo possível (~250 perguntas, 25 subagents)

Processo com Subagents (PADRÃO):

CRIAR PASTA (se não existir): mkdir -p temp-lotes/
Calcular número de lotes: quantidade / 10 (10 perguntas por lote)
Distribuir chunks entre lotes (59 chunks / N lotes)
Lançar N subagents EM PARALELO usando Task tool
Cada subagent: a. Consulta SQLite: regulamento.db chunks específicos b. Gera 10 perguntas REAIS do conteúdo c. ⚠️ CRÍTICO: Salva em /Users/2a/.claude/skills/gerar-quiz-rag/temp-lotes/temp-lote-N.json
- ❌ NUNCA salvar na raiz da skill!
- ✅ SEMPRE em temp-lotes/temp-lote-N.json
Aguardar todos os subagents concluírem (~1-2 minutos)
Executar python3 coletar-e-merge-final.py para merge automático
Resultado em banco-perguntas.json (validado, sem duplicatas)
Limpar temp-lotes/ (opcional)

`/gerar-quiz-rag iniciar [modo]`

Executa quiz de 10 perguntas.

Modos:

novo - Gera 10 perguntas novas do banco RAG
aleatorio - Sorteia 10 do banco JSON existente
teste - Modo teste com respostas marcadas (⭐)

`/gerar-quiz-rag status`

Mostra progresso atual do banco de perguntas.

Banco de Perguntas (JSON Local)

As perguntas são armazenadas em arquivo JSON local na própria skill.

Arquivo Principal

Localização: /Users/2a/.claude/skills/gerar-quiz-rag/banco-perguntas.json
Formato: JSON estruturado com metadata e array de perguntas
Gerenciado por: Claude diretamente (lê e escreve via ferramentas Read/Write)

Arquivos Temporários

Localização: /Users/2a/.claude/skills/gerar-quiz-rag/temp-lotes/
Arquivos: temp-lote-1.json, temp-lote-2.json, etc.
Uso: Lotes individuais quando gerado com subagents paralelos
Limpeza: Podem ser apagados após merge em banco-perguntas.json

Schema do JSON (OBRIGATÓRIO)

CAMPOS PERMITIDOS (apenas estes):

{
  "metadata": {
    "total_perguntas": 10,
    "ultima_atualizacao": "2026-01-04T20:00:00.000000",
    "fonte": "regulamento.db"
  },
  "perguntas": [
    {
      "numero": 1,
      "texto": "Qual a idade mínima para participar?",
      "alternativas": {
        "A": {
          "texto": "16 anos",
          "correta": false,
          "explicacao": "Incorreto. Idade mínima é 18 anos."
        },
        "B": {
          "texto": "18 anos",
          "correta": true,
          "explicacao": "Correto! Conforme regulamento."
        },
        "C": { "texto": "...", "correta": false, "explicacao": "..." },
        "D": { "texto": "...", "correta": false, "explicacao": "..." }
      },
      "dificuldade": "facil",
      "topico": "Elegibilidade",
      "fonte_chunk": "chunk_0"
    }
  ]
}

⚠️ CAMPOS PROIBIDOS (NUNCA incluir):

❌ item_regulamento (dentro de pergunta)
❌ referencia_fonte (dentro de pergunta)
❌ secao (dentro de pergunta)
❌ regulamento_ref (dentro de alternativas)

✅ FORMATO CORRETO do fonte_chunk:

✅ "chunk_0" - índice do chunk no banco RAG
✅ "chunk_5" - outro exemplo
❌ Não usar regulamento_ref aqui

🚀 Geração com Subagents (MÉTODO PADRÃO)

Por Que Subagents?

✅ 10-15x mais rápido que método sequencial ✅ Máxima qualidade - Perguntas reais e específicas ✅ Paralelização - Múltiplos agentes trabalhando ao mesmo tempo ✅ Validação automática - Merge detecta e remove duplicatas

Template de Prompt para Cada Subagent:

Gere 10 perguntas de MÚLTIPLA ESCOLHA (A,B,C,D) do banco RAG.

**Banco**: /Users/2a/.claude/skills/gerar-quiz-rag/fonte-da-verdade-rag/regulamento.db
**Chunks**: X a Y
**Numeração**: N a N+9
**Arquivo**: /Users/2a/.claude/skills/gerar-quiz-rag/temp-lotes/temp-lote-Z.json

⚠️ CRÍTICO: Use caminho COMPLETO e ABSOLUTO para o arquivo!
   CORRETO: /Users/2a/.claude/skills/gerar-quiz-rag/temp-lotes/temp-lote-Z.json ✅
   ERRADO: temp-lote-Z.json (vai salvar na raiz!) ❌

FORMATO EXATO (array JSON):
[
  {
    "numero": N,
    "texto": "Pergunta específica baseada no chunk?",
    "alternativas": {
      "A": {"texto": "Opção", "correta": false, "explicacao": "Razão"},
      "B": {"texto": "Opção", "correta": true, "explicacao": "Razão"},
      "C": {"texto": "Opção", "correta": false, "explicacao": "Razão"},
      "D": {"texto": "Opção", "correta": false, "explicacao": "Razão"}
    },
    "dificuldade": "facil|media|dificil",
    "topico": "Tópico Específico",
    "fonte_chunk": "chunk_X"
  }
]

PASSOS:
1. sqlite3 regulamento.db "SELECT conteudo FROM chunks WHERE chunk_index BETWEEN X AND Y;"
2. Leia conteúdo REAL
3. Gere 10 perguntas ESPECÍFICAS
4. Salve array JSON em temp-lotes/

Distribuição de Chunks (para 200 perguntas):

Lote	Chunks	Perguntas	Arquivo
1-20	0-58 (~3 chunks cada)	10 cada	temp-lotes/temp-lote-N.json

Após Gerar os Lotes:

python3 coletar-e-merge-final.py

Resultado: banco-perguntas.json com todas as perguntas validadas e sem duplicatas!

Instruções para o Claude

⚠️ LEMBRETE: Se você precisar invocar este skill via Skill tool, use o nome completo qualificado: gerar-quiz-rag:gerar-quiz-rag (não apenas gerar-quiz-rag).

Quando `/gerar-quiz-rag gerar` for invocado:

⚡ IMPORTANTE: SEMPRE USE SUBAGENTS EM PARALELO!

PASSO 0: Usar Subagents (OBRIGATÓRIO)

CRIAR PASTA: mkdir -p temp-lotes/
Calcular distribuição:
- Lotes: quantidade_solicitada / 10
- Chunks por lote: 59 / num_lotes (normalmente 3 chunks/lote)
Para CADA lote (1 a N), lançar subagent com este prompt COMPLETO:

Gere 10 perguntas de múltipla escolha do banco RAG.

BANCO: /Users/2a/.claude/skills/gerar-quiz-rag/fonte-da-verdade-rag/regulamento.db
CHUNKS: X, X+1, X+2
PERGUNTAS: N a N+9
SALVAR EM: /Users/2a/.claude/skills/gerar-quiz-rag/temp-lotes/temp-lote-Z.json

EXEMPLO DE 1 PERGUNTA (siga EXATAMENTE este formato):
{
  "numero": 1,
  "texto": "Qual idade mínima para pessoa física no Renda Extra conforme item 3.1?",
  "alternativas": {
    "A": {
      "texto": "16 anos",
      "correta": false,
      "explicacao": "Incorreto. Item 3.1 estabelece 18 anos."
    },
    "B": {
      "texto": "18 anos",
      "correta": true,
      "explicacao": "Correto! Item 3.1 define idade mínima de 18 anos."
    },
    "C": {
      "texto": "21 anos",
      "correta": false,
      "explicacao": "Incorreto. É 18 anos conforme item 3.1."
    },
    "D": {
      "texto": "25 anos",
      "correta": false,
      "explicacao": "Incorreto. Idade mínima é 18 anos."
    }
  },
  "dificuldade": "facil",
  "topico": "Elegibilidade",
  "fonte_chunk": "chunk_0"
}

REGRAS CRÍTICAS:
✅ Use "alternativas" (NÃO "opcoes", NÃO "options")
✅ Cada alternativa: {"texto": "...", "correta": boolean, "explicacao": "..."}
✅ Apenas 1 alternativa com correta: true
✅ Retorne array: [ {pergunta1}, {pergunta2}, ... ]
✅ NÃO envolva em {"perguntas": [...]}

PASSOS:
1. cd /Users/2a/.claude/skills/gerar-quiz-rag
2. Consulte chunks: sqlite3 fonte-da-verdade-rag/regulamento.db "SELECT conteudo FROM chunks WHERE chunk_index BETWEEN X AND X+2;"
3. Gere 10 perguntas REAIS
4. Write("temp-lotes/temp-lote-Z.json", array_json)

Aguardar todos terminarem (~2 min)
Executar merge: python3 coletar-e-merge-final.py
- Move automaticamente JSONs soltos para temp-lotes/
- Valida formato
- Remove duplicatas
- Gera banco-perguntas.json final
Validar: jq '.metadata' banco-perguntas.json

NÃO USE MÉTODO MANUAL/SEQUENCIAL (lento e ineficiente)

PASSO 1 (Apenas para referência): Consultar banco RAG

Subagents farão isso automaticamente com sqlite3 em regulamento.db

Comando SQL para ler chunks:

SELECT chunk_index, conteudo FROM chunks WHERE doc_id = 1 ORDER BY chunk_index;

Usar ferramenta Read para ler /Users/2a/.claude/skills/gerar-quiz-rag/banco-perguntas.json (se existir)
Analisar perguntas existentes para evitar duplicatas

PASSO 1.5: Pré-processar texto dos chunks 🧹 LIMPEZA OBRIGATÓRIA

PROBLEMA: Chunks do RAG contêm formatação com ruído (espaços duplos, caracteres especiais).

SOLUÇÃO: Antes de gerar perguntas, SEMPRE normalizar o texto:

# Aplicar estas transformações NO TEXTO DOS CHUNKS:
1. Remover espaços múltiplos → espaço único
   "Renda  Extra" → "Renda Extra"

2. Normalizar aspas especiais → aspas normais
   "ˮ" → '"'

3. Remover espaços antes de pontuação
   " ." → "."
   " ," → ","

4. Normalizar quebras de linha
   Múltiplas → única

5. Remover caracteres de controle/unicode indesejados

EXEMPLO de limpeza:

ANTES (chunk bruto):
"O  Programa  Renda  Extra  (" Renda  Extra ˮ)  consiste  em..."

DEPOIS (chunk limpo):
"O Programa Renda Extra ("Renda Extra") consiste em..."

IMPORTANTE:

Aplicar limpeza MENTALMENTE ao interpretar chunks
Usar texto limpo para gerar perguntas
Não modificar o banco de dados original
Apenas processar em memória durante geração

PASSO 2: Gerar perguntas novas 🚨 LIMITE DE TOKENS

REGRA CRÍTICA - Gerar em LOTES PEQUENOS:

Se quantidade solicitada > 5:

❌ ERRADO: gerar_20_perguntas() de uma vez
✅ CORRETO:
   - gerar_5_perguntas() → salvar
   - gerar_5_perguntas() → salvar
   - gerar_5_perguntas() → salvar
   - gerar_5_perguntas() → salvar

LIMITE MÁXIMO POR LOTE: 5 PERGUNTAS

Processo para cada lote de 5:

Ler banco atual
Consultar conteúdo dos chunks via SQL
Gerar EXATAMENTE 5 perguntas completas baseadas nos chunks
Adicionar ao banco
Salvar imediatamente
Validar que salvou correto
Continuar próximo lote

Motivo: Evitar JSON truncado por limite de tokens

Requisitos por pergunta:

Baseado no conteúdo dos chunks do RAG
Estrutura JSON validada (ver schema acima)
Garantir que é DIFERENTE das já existentes
Variar tópicos e dificuldade
Referenciar o fonte_chunk de origem

PASSO 3: Salvar no JSON 🚨 ANTI-CORRUPÇÃO

TÉCNICA OBRIGATÓRIA - Gerar por Partes:

Ler banco existente (se houver)
Para cada nova pergunta:
- Criar dict completo da pergunta
- Adicionar ao array perguntas
Atualizar metadata (total_perguntas, ultima_atualizacao)

VALIDAÇÃO CRÍTICA antes de Write:

CHECKLIST PRÉ-SAVE:
[ ] Todas as perguntas têm 4 alternativas (A, B, C, D)?
[ ] Todas alternativas têm texto, correta, explicacao?
[ ] Nenhum campo está truncado (ex: "explicac", "tex", "corr")?
[ ] fonte_chunk no formato "chunk_X"?
[ ] SEM campos proibidos?
[ ] JSON completo, sem "..." ou placeholders?

Usar ferramenta Write com JSON validado
VERIFICAÇÃO PÓS-SAVE (OBRIGATÓRIA):
- Usar Read para ler arquivo salvo
- Confirmar que JSON é válido e completo
- Se corrompido: regerar
Mostrar resumo do que foi gerado

Quando `/gerar-quiz-rag iniciar` for invocado:

PASSO 1: Escolher perguntas

Se modo novo: Gerar 10 perguntas consultando RAG
Se modo aleatorio: Ler JSON e sortear 10 existentes
Se modo teste: Marcar resposta correta com ⭐

PASSO 2: Executar quiz

Apresentar 1 pergunta por vez
Aguardar resposta do usuário
Dar feedback imediato (correto/incorreto + explicação)
Avançar para próxima
Ao final, mostrar pontuação e análise

Critérios para criação das perguntas:

Criar perguntas baseadas no conteúdo dos chunks do banco RAG
Cada pergunta deve testar compreensão de pontos importantes
Variar a dificuldade (fácil, média, difícil)
Explorar diferentes tipos de informação do conteúdo
NÃO repetir perguntas que já estão no banco
Referenciar o chunk de origem: Cada pergunta deve indicar de qual chunk veio (ex: "chunk_0")

Formato das Perguntas no Quiz

Cada pergunta deve seguir este formato:

**Pergunta X/10**

[Enunciado da pergunta]

A) [Alternativa A]
B) [Alternativa B]
C) [Alternativa C]
D) [Alternativa D]

Qual é a sua resposta? (A, B, C ou D)

Regras para as alternativas:

Exatamente 4 alternativas (A, B, C, D)
Apenas UMA alternativa correta
Três alternativas incorretas mas plausíveis
Randomizar a posição da resposta correta
[TESTE] Em modo teste, destacar alternativa correta com ⭐

Avaliação de Respostas

Após o usuário responder:

Se CORRETA:

✅ Correto! A resposta é [letra]: [texto da alternativa]

[Breve explicação do porquê está correto]

Pontuação atual: X/Y

Se INCORRETA:

❌ Incorreto. Você respondeu [letra], mas a resposta correta é [letra correta].

**Por que sua resposta está errada:**
[Explicação clara do erro]

**Resposta correta:**
[Texto da alternativa correta] - [Explicação]

Pontuação atual: X/Y

Pontuação Final

Após a 10ª pergunta:

===========================================
           RESULTADO DO QUIZ
===========================================

Pontuação: X/10 (XX%)

[Avaliação baseada na pontuação:]
- 10/10: Excelente! Domínio completo.
- 8-9/10: Muito bom! Conhecimento sólido.
- 6-7/10: Bom. Alguns pontos precisam de revisão.
- 4-5/10: Regular. Recomenda-se revisar.
- 0-3/10: Precisa estudar mais.

DESEMPENHO POR TÓPICO:
===========================================
✓ Tópico A: 2/2 (100%)
✗ Tópico B: 1/2 (50%)
...

TÓPICOS PARA REVISÃO:
- [Lista de tópicos com desempenho < 70%]
===========================================

Regras de Interação

Uma pergunta por vez - Nunca mostrar múltiplas perguntas de uma vez
Aguardar resposta - Não avançar até o usuário responder
Aceitar formatos flexíveis - Aceitar "A", "a", "1", "primeira" etc.
Feedback imediato - Sempre explicar o resultado após cada resposta
Manter contexto - Lembrar a pontuação ao longo do quiz
Tom educativo - Ser construtivo nas correções, não punitivo

Comandos do Usuário

Durante o quiz:

"pular" ou "próxima" - Conta como erro e avança
"desistir" ou "parar" - Encerra e mostra pontuação parcial
"repetir" - Repete a pergunta atual
"pontuação" - Mostra pontuação atual

Validação de Duplicatas (CRÍTICO)

PARA GARANTIR QUIZ COMPLETO SEM DUPLICATAS:

Algoritmo de Detecção:

Match Exato (100% similiar):
- Comparar texto da pergunta (ignorando case)
- Se idêntico: ❌ DUPLICATA - gerar outro
Similaridade de Texto (>60% similar):
- Extrair palavras-chave principais
- Contar palavras em comum
- Se palavras_em_comum / total_palavras > 60%: ❌ DUPLICATA
Match de Padrão:
- Mesmos itens/seções mencionadas?
- Mesma pergunta, apenas redação diferente?
- Se sim: ❌ DUPLICATA

Implementação:

ANTES DE GERAR CADA PERGUNTA:

Para cada pergunta nova:
  1. Extrair palavras-chave do texto
  2. Para cada pergunta existente no banco:
     a. Comparar texto (case-insensitive)
     b. Se 100% igual: DUPLICATA
     c. Contar palavras em comum
     d. Se similaridade > 60%: DUPLICATA
  3. Se não for duplicata:
     a. ACEITAR pergunta
     b. Adicionar ao banco
  4. Se for duplicata:
     a. GERAR nova pergunta diferente
     b. Voltar ao passo 1
     c. Máximo 3 tentativas

Critérios de Duplicata (CONCRETOS):

✅ ACEITAR: "Qual é a idade mínima?" + "Qual idade mínima?" → Texto diferente, mesmo conceito ✓
❌ REJEITAR: "Qual é a idade mínima?" + "Qual é a idade mínima?" → Idêntico
❌ REJEITAR: "Qual é a idade mínima para participar?" + "Qual é a idade mínima para o programa?" → >60% similar

Estratégia para 200+ Perguntas:

Variar enfoques:
- "O Pagar.me pode fazer X?" (verdadeiro/falso)
- "Qual é a consequência de X?" (resultado)
- "O artigo Y menciona qual ponto?" (citação)
- "Em qual situação Z se aplica?" (aplicação)
Variar tópicos:
- Nunca gerar 2 perguntas sobre mesmo item consecutivamente
- Alternar entre seções
Monitorar duplicatas:
- A cada 50 perguntas: avisar se taxa de duplicatas > 10%
- Se atingir 3 duplicatas seguidas: PARAR (banco completo)
- Se quantidade solicitada > máximo estimado: ALERTAR usuário

Início do Quiz

Ao iniciar, apresentar:

===========================================
        QUIZ DO CONHECIMENTO RAG
===========================================

Este quiz contém 10 perguntas de múltipla escolha
baseadas no conhecimento armazenado no banco RAG.

- Cada pergunta tem 4 alternativas (A, B, C, D)
- Apenas uma alternativa está correta
- Você receberá feedback após cada resposta

Preparado? Vamos começar!

---

gerar-quiz-rag

$ Installieren

Quiz RAG - Skill do Claude Code

⚠️ IMPORTANTE: Nome Completo Qualificado

Visão Geral

Comandos da Skill

`/gerar-quiz-rag gerar [quantidade]`

`/gerar-quiz-rag iniciar [modo]`

`/gerar-quiz-rag status`

Banco de Perguntas (JSON Local)

Arquivo Principal

Arquivos Temporários

Schema do JSON (OBRIGATÓRIO)

🚀 Geração com Subagents (MÉTODO PADRÃO)

Por Que Subagents?

Template de Prompt para Cada Subagent:

Distribuição de Chunks (para 200 perguntas):

Após Gerar os Lotes:

Instruções para o Claude

Quando `/gerar-quiz-rag gerar` for invocado:

Quando `/gerar-quiz-rag iniciar` for invocado:

Formato das Perguntas no Quiz

Avaliação de Respostas

Pontuação Final

Regras de Interação

Comandos do Usuário

Validação de Duplicatas (CRÍTICO)

Algoritmo de Detecção:

Implementação:

Critérios de Duplicata (CONCRETOS):

Estratégia para 200+ Perguntas:

Início do Quiz

Repository

Actions

Related Skills

gerar-quiz-rag

$ Installieren

Quiz RAG - Skill do Claude Code

⚠️ IMPORTANTE: Nome Completo Qualificado

Visão Geral

Comandos da Skill

/gerar-quiz-rag gerar [quantidade]

/gerar-quiz-rag iniciar [modo]

/gerar-quiz-rag status

Banco de Perguntas (JSON Local)

Arquivo Principal

Arquivos Temporários

Schema do JSON (OBRIGATÓRIO)

🚀 Geração com Subagents (MÉTODO PADRÃO)

Por Que Subagents?

Template de Prompt para Cada Subagent:

Distribuição de Chunks (para 200 perguntas):

Após Gerar os Lotes:

Instruções para o Claude

Quando /gerar-quiz-rag gerar for invocado:

Quando /gerar-quiz-rag iniciar for invocado:

Formato das Perguntas no Quiz

Avaliação de Respostas

Pontuação Final

Regras de Interação

Comandos do Usuário

Validação de Duplicatas (CRÍTICO)

Algoritmo de Detecção:

Implementação:

Critérios de Duplicata (CONCRETOS):

Estratégia para 200+ Perguntas:

Início do Quiz

Repository

Actions

Related Skills

`/gerar-quiz-rag gerar [quantidade]`

`/gerar-quiz-rag iniciar [modo]`

`/gerar-quiz-rag status`

Quando `/gerar-quiz-rag gerar` for invocado:

Quando `/gerar-quiz-rag iniciar` for invocado: