Skill ou subagente: qual formato usar para encapsular um fluxo com Jev no Claude Code?

O Jev decide, beleza

Mas quem carrega essa decisão dentro do Claude Code?

Essa é a pergunta que trava muita gente na hora de montar o primeiro fluxo tipado: o modelo responde em milissegundos, o código consome a resposta e tudo funciona no script solto, aí você quer transformar isso num pacote reutilizável e descobre que existem dois formatos possíveis

Skill e subagente resolvem problemas DIFERENTES

E escolher errado sai caro de um jeito bem específico: ou você entope a janela de contexto com coisa que não devia estar lá, ou perde previsibilidade num fluxo que deveria ser burro e determinístico…

O que o Jev faz e por que isso muda o formato do pacote

Antes de decidir a embalagem, tem que entender o conteúdo

O Jev é o modelo System One da TypeSafe AI, e ele é estranho de propósito: não escreve texto, não escreve código e não mantém conversa

Ele avalia perguntas tipadas sobre um estado e devolve resultados estruturados que o teu código usa direto

São três tipos de pergunta (as primitivas):

• Choice: escolhe uma opção da lista e devolve a distribuição de probabilidades
• Score: dá uma nota numa rubrica definida por você
• Noul: uma declaração verdadeiro/falso numa escala de 0 a 1

Choice e Score ainda voltam com um valor de confiança, também numa escala de 0 a 1

Se você conhece a diferença entre chamar uma função e conversar com alguém, é isso: o Jev é chamada de função, não papo

E os números reforçam essa natureza

A TypeSafe informa latência de ponta a ponta de 70 a 500 ms

Na OpenRouter, o jev-1.13 está listado a US$ 0,042 por 1 milhão de tokens de entrada e US$ 0 por 1 milhão de tokens de saída, com janela de contexto de 32.000 tokens

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

Na documentação da TypeSafe, os limites de taxa do jev-1.13 são de 250.000 tokens por segundo e 1.200 requisições por minuto

Ou seja: é uma chamada barata, rápida e que cabe DENTRO de um passo do teu fluxo

Isso muda tudo no debate de formato, porque você não está empacotando um agente conversacional, você está empacotando uma decisão

E o acesso hoje?

Aqui vale o aviso, porque muita gente tropeça nisso

O Jev foi lançado publicamente em 15 de setembro de 2026, no começo só com lista de espera

Em 20 de setembro a TypeSafe anunciou no X que a waitlist tinha caído ("Jev is now available to everyone. No waitlist.")

E em 22 de setembro vieram os novos cadastros pausados por excesso de demanda, com as contas já existentes seguindo operando normalmente

Até 27/09/2026 não teve anúncio de reabertura

A via alternativa é a OpenRouter, que lista 3 modelos da TypeSafe (Jev Router, Jev Latest e Jev 1.13) pra qualquer chave da plataforma

A TypeSafe também distribui uma agent skill oficial que dá ao agente o contexto completo da API (os três tipos de pergunta e os padrões de arquitetura), com instalação específica pro Claude Code:

claude plugin marketplace add typesafe-ai/skills
claude plugin install typesafe@typesafe-ai

Em outros agentes, a instalação documentada é outra:

npx skills add typesafe-ai/skills --skill typesafe-ai

Sacou onde isso já entrega uma pista? O formato oficial de distribuição do conhecimento do Jev é uma skill

Mas o SEU fluxo pode pedir outra coisa

Skill x subagente no Claude Code: comparação lado a lado

Antes da tabela, o de sempre: se você ainda está mapeando as diferenças entre skills, comandos e subagentes, vale ter isso fresco na cabeça

Agora o lado a lado, com os critérios que realmente decidem:

Repara numa assimetria que a tabela deixa clara: skill é sobre o que o agente sabe fazer, subagente é sobre onde o trabalho acontece

Quando o fluxo com Jev pede skill

Skill é o formato certo quando o fluxo é curto, previsível e você quer poder chamar pelo nome

Os cenários que se encaixam:

1. Uma pergunta tipada única que decide um ramo do fluxo: um Noul pra dizer se o texto viola a política, um Choice pra rotear pra fila A, B ou C
2. Script empacotado que chama o Jev e devolve a distribuição: a skill guarda o script e as instruções de quando rodar, com o caminho resolvido por ${CLAUDE_SKILL_DIR} pra funcionar igual em skill pessoal, de projeto ou de plugin
3. Rotina que você quer invocar digitando o nome, sem depender do humor do modelo
4. Fluxo que precisa estar em todos os projetos: aí é skill pessoal em ~/.claude/skills/, sem duplicar em cada repo

O exemplo oficial mais interessante desse formato é o cookbook Skill suggestion da TypeSafe

O padrão é o Jev escolher qual skill carregar: uma pergunta Choice sobre 182 nomes de skills (a description do índice funciona como critério de cada opção) mais três perguntas Noul cuja média decide se vale sugerir algo, com corte em 0,30 (abaixo disso, não sugere nada)

Duas requisições por turno e pronto

E tem versão de comunidade rodando isso no Claude Code: o mod jev-skill-suggestion, adicionado por davila7 ao repositório claude-code-templates via PR #944

npx claude-code-templates@latest --mod productivity/jev-skill-suggestion

O setup marca as skills como user invocable only e injeta só o SKILL.md escolhido, mantendo a lista inteira fora do contexto

Isso é a essência do formato skill bem usado: decisão barata na frente, contexto limpo atrás

O mesmo raciocínio vale fora do Claude Code, por exemplo quando você usa o Jev pra qualificar e priorizar leads no funil: a pergunta tipada é o passo, o resto é encanamento

Quando o fluxo com Jev pede subagente

Agora vira o jogo

Subagente é pra quando antes da pergunta tipada existe trabalho sujo

Os cenários:

1. Coleta que gera muito lixo de contexto: ler 40 arquivos, grepar o projeto todo, listar diretórios… tudo isso pra montar o estado que vai virar um Score ou um Noul
2. Varredura de repositório: o subagente investiga, monta o resumo do estado, faz a pergunta tipada e devolve só o veredito
3. Necessidade de limitar ferramentas: tools: Read, Glob, Grep e acabou, o passo não escreve nada
4. Vontade de trocar o modelo daquele passo específico: o campo model aceita alias, ID completo ou inherit pra usar o mesmo da conversa principal

O ponto forte aqui é o isolamento: cada subagente roda em janela própria e limpa, não vê o histórico da conversa nem os arquivos já lidos, e as chamadas de ferramenta intermediárias não aparecem no pai

Só o resultado final volta

Pra um fluxo com Jev isso é ouro, porque a parte caótica (a coleta) morre lá dentro e o pai recebe a resposta estruturada

Um esqueleto de subagente fica mais ou menos assim:

---
name: jev-triagem
description: Monta o estado de um repositorio e devolve o veredito de uma pergunta tipada do Jev
tools: Read, Glob, Grep
model: haiku
skills:
  - <nome-da-skill-do-jev>
---

Voce coleta o estado, formula a pergunta tipada e devolve APENAS o resultado estruturado

Esse campo skills do frontmatter é o detalhe que muita gente não conhece: ele pré-carrega o conteúdo completo das skills no contexto do subagente já no startup

É assim que você coloca a skill oficial da TypeSafe (com os três tipos de pergunta e os padrões de arquitetura) dentro do subagente sem ele ter que ir buscar

Duas ressalvas importantes:

• o campo controla o que é pré-carregado, não o que ele pode acessar: sem o campo, ele ainda consegue invocar skills pela ferramenta Skill
• skill marcada com disable-model-invocation: true não pode ser pré-carregada, então se você escondeu a skill do modelo, ela não entra por aqui

Já me ferrei uma vez com combinação desse tipo, vale conferir antes de jurar que "não funciona" 😛

O que a prática com skills mostra antes de você escolher

Agora saindo da teoria

No vídeo eu mostro uma skill que lê código e desenha a arquitetura do sistema, e a parte que mais importa pra esta discussão de formato não é o diagrama: é o COMPORTAMENTO de invocação

Eu instalei pelo terminal, escolhi a opção de instalar pro Claude Code e segui a recomendação de instalação via symlink, que deixa o pacote acessível de forma universal pra qualquer IA

Depois pedi, em português mesmo, pra IA usar a skill e criar um diagrama de arquitetura completo de um e-commerce integrado a um gateway de pagamento

E aqui está a lição: a IA localizou a skill sozinha e passou a gerar o resultado

Isso é a description fazendo o trabalho dela

Quando testei em um repositório já existente (a Evolution API), pedi pra clonar o projeto, analisar o código e gerar um diagrama de runtime com componentes principais, fluxo de dados, dependências externas e fronteiras de segurança

O diagrama saiu mostrando a complexidade real do projeto: mensageria, API, banco de dados e filas

Depois expandi o diagrama do e-commerce numa segunda rodada, pedindo funcionalidades novas (marketplace), e ele evoluiu de forma incremental sobre o que já existia

O que eu achei mais massa foi a etapa de revisão/validação antes de entregar o resultado final, que na minha visão deixa a coisa muito mais confiável do que só pedir uma imagem pra uma IA genérica

Abri o HTML gerado no navegador e consegui seguir o fluxo inteiro: cliente entra na loja, faz checkout, o pagamento passa pela integração externa e o webhook volta pra API, que grava o pedido no banco

Pretendo usar isso em sistemas futuros, tanto pra planejar um sistema do zero quanto pra entender a arquitetura de um projeto open source já pronto

Traduzindo pro nosso dilema: skill bem descrita é acionada sem você pedir explicitamente, e isso é uma faca de dois lados

É ótimo quando o fluxo é útil em vários contextos, e é ruim quando você quer controle total de quando aquele passo roda (aí entra o disable-model-invocation: true)

Tome cuidado com este detalhe:

Skills em .claude/skills abaixo do diretório onde a sessão começou NÃO carregam no startup

Elas carregam na primeira vez que o Claude lê ou edita um arquivo daquele subdiretório, e daí ficam disponíveis pelo resto da sessão

Se você tem um monorepo e colocou a skill do Jev num pacote interno, é exatamente esse o motivo dela "não existir" no começo da conversa

Veredito: o critério que decide em 30 segundos

Três perguntas de corte, sem enrolação

1. O fluxo é um passo ou uma investigação?

Um passo (uma pergunta tipada, um script curto, uma decisão): skill

Investigação (varrer, ler, cruzar arquivos antes de perguntar): subagente

2. Ele precisa esquecer o histórico?

Se a resposta do Jev fica melhor com o estado montado de forma limpa, sem contaminação do papo anterior, subagente, pela janela própria

Se o fluxo se beneficia de continuar na mesma conversa, skill

3. Quem dispara: você, o modelo ou os dois?

Só você: skill com disable-model-invocation: true

O modelo, por contexto: skill com description afiada, ou subagente por delegação automática

Os dois: subagente resolve bem, porque citar o nome no prompt força o uso e a description cobre o automático

E existe o caminho híbrido, que na prática é o mais elegante pra Jev: subagente que pré-carrega a skill

O subagente dá o isolamento e o controle de tools e model, a skill dá o conhecimento da API e o script

Agora o veredito honesto do que cada um NÃO resolve

Skill não te protege de contexto poluído: se o passo anterior encheu a janela, a skill vai trabalhar naquele lixo junto

Subagente não te dá previsibilidade de disparo garantida por description, e ele também não devolve o caminho do raciocínio: se você precisa auditar o meio do processo na conversa principal, o isolamento vira desvantagem

Nenhum dos dois conserta pergunta tipada mal escrita, e isso é o principal: rubrica ruim no Score, opção ambígua no Choice e a confiança que volta não significa nada

Conclusão

A régua é curta: passo curto e previsível vira skill, investigação suja vira subagente, e quando você precisa dos dois, subagente que pré-carrega a skill

O próximo passo concreto, na ordem:

1. instalar a skill oficial da TypeSafe no Claude Code com claude plugin marketplace add typesafe-ai/skills e claude plugin install typesafe@typesafe-ai
2. ler os três tipos de pergunta (Choice, Score e Noul) e entender o que a confiança de 0 a 1 está te dizendo
3. escrever a PRIMEIRA pergunta tipada do teu fluxo antes de decidir o empacotamento

Esse terceiro item é o que mais economiza tempo, sério: depois de escrever a pergunta, o formato geralmente se escolhe sozinho

E se você está fora do acesso direto (os novos cadastros seguem pausados desde 22 de setembro de 2026), a OpenRouter lista os modelos da TypeSafe pra qualquer chave da plataforma, então dá pra começar a testar por lá

Até o próximo post! 🙂