Skills e Jev: qual é o papel de cada um no seu fluxo de trabalho?

Fala aí, beleza? A confusão mais comum de quem começa a mexer nessas duas coisas é tentar fazer a skill decidir e o Jev explicar

E aí nada funciona muito bem

São duas camadas com papéis bem distintos: uma carrega procedimento (o como fazer, o contexto, os arquivos de apoio), a outra devolve um veredito tipado e pronto. Quando você entende onde uma termina e a outra começa, para de escrever regra de decisão em Markdown e para de pedir texto pra um modelo que não gera texto

Bora separar isso direito?

O que é o Jev e por que ele não faz o trabalho da skill

O Jev foi lançado pela TypeSafe AI em 15/09/2026, como primeiro modelo público da categoria que eles chamam de System One

E o acesso teve uma virada rápida: a TypeSafe abriu o cadastro pra todo mundo sem waitlist e, poucos dias depois, pausou novos cadastros por excesso de demanda, mantendo em funcionamento as contas já criadas (volto nisso lá no fim do post, porque muda o que faz sentido você fazer hoje)

A proposta é diferente do que você está acostumado: em vez de devolver texto, ele devolve decisões tipadas com probabilidade calibrada

Uma chamada ao Jev tem duas partes:

• o estado: texto livre, JSON ou uma combinação dos dois
• um conjunto de perguntas tipadas, cujas opções válidas são declaradas ANTES da execução

O modelo só pode responder dentro do conjunto declarado. Nada de improviso

Os tipos de pergunta são três: Choice, Score e Noul. O Noul é a pergunta sim/não que devolve a probabilidade de a afirmação ser verdadeira (o nome vem de Bernoulli, se liga na piada interna)

E cada resposta de Choice e de Score vem acompanhada de um valor de confiança de 0 a 1, derivado da forma da distribuição de probabilidade

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

Todos os modelos são servidos pelo mesmo endpoint: POST https://api.typesafe.ai/v1/systemone

O preço tem uma pegadinha boa: são cobrados apenas os tokens de entrada, a US$ 0,042 por 1 milhão de tokens, e a saída não é medida. A latência declarada pela TypeSafe é de 70 a 500 ms ponta a ponta

Agora o ponto central, que é o que interessa pra este post:

O Jev não gera texto. Não escreve prosa, não gera código, não devolve cadeia de raciocínio em texto. A saída fica restrita ao schema tipado

Ou seja: ele nunca vai te explicar o procedimento, nunca vai te entregar o passo a passo, nunca vai documentar nada. Ele responde. Só isso, e muito rápido

Então se você estava pensando em jogar fora suas skills porque agora "tem um modelo que decide", relaxa, é o contrário: as duas coisas se completam

O que é uma skill no Claude Code e o que ela carrega

Uma skill no Claude Code é um diretório com um arquivo SKILL.md dentro

Esse arquivo tem duas partes: o frontmatter YAML (com campos como name e description) e o corpo em Markdown, que são as instruções propriamente ditas

Mais ou menos assim:

---
name: revisao-de-pr
description: Revisa um pull request seguindo o checklist do time, conferindo testes, migrations e impacto em API pública
allowed-tools: Read, Grep, Bash
---

# Revisão de PR

## Quando usar
...

## Procedimento
1. ...

O frontmatter também aceita allowed-tools, que controla quais ferramentas aquela skill pode usar. Guardrails (limites) na veia

E onde isso vive? Duas opções:

• ~/.claude/skills/ para skills pessoais
• .claude/skills/ para skills de projeto, que vão compartilhadas via git com o time

Agora a parte que muita gente não sabe e que muda TUDO na hora de escrever skill: o progressive disclosure

No início da sessão, o Claude Code carrega apenas name e description do frontmatter de cada skill

O corpo do SKILL.md só entra no contexto quando a skill é acionada

Se você conhece lazy loading, é exatamente isso: a vitrine fica sempre visível, o estoque só sai da prateleira quando alguém pede

E tem mais: uma skill pode incluir arquivos de apoio no próprio diretório, organizados em subpastas:

• scripts/ para executáveis
• references/ para documentação que será carregada em contexto
• assets/ para templates e binários

Ou seja, a skill é um pacote de procedimento. Instrução, referência, script, template. É o "como fazer" empacotado

Se você ainda está na fase de garimpar quais valem a pena, dei uma olhada nas skills mais populares do Claude em outro post, e a conclusão não foi a mais óbvia

Skill x Jev: quem responde o quê

Coloquei lado a lado pra ficar difícil confundir:

Lendo a tabela de cima a baixo dá pra resumir em uma frase:

Procedimento na skill, veredito no Jev

Guarda essa, porque ela resolve quase toda dúvida de arquitetura que aparece depois

Como as duas camadas se encaixam na prática

A composição mais natural é essa: a skill descreve COMO montar a chamada, e o Jev devolve a decisão

A skill é quem carrega o conhecimento chato e repetitivo: como montar o state, quais perguntas fazem sentido pra aquele domínio, quais opções declarar em cada Choice, o que fazer quando a confiança volta baixa, onde registrar o resultado

O Jev não sabe nada disso e não precisa saber. Ele recebe e responde

Skill pública pra escrever código que chama o Jev

Já existe uma skill de comunidade pra isso: o repositório dbreunig/building-with-jev-skill, mantido no GitHub pelo usuário dbreunig, traz uma skill pra escrever e melhorar programas que chamam o Jev

A skill fica em skills/jev/SKILL.md e a instalação é copiar essa pasta para ~/.claude/skills/jev

Depois você chama por nome com /jev

Repara no desenho: o procedimento de "como escrever um programa que chama o Jev" está em Markdown, numa skill. A decisão em si continua sendo do Jev, em runtime. Ninguém pisou no pé de ninguém

O Jev como porteiro das suas skills

Essa aqui é a inversão mais massa que apareceu até agora

Daniel Avila publicou o Jev Skill Suggestion, um mod para Claude Code onde as skills são marcadas como user invocable only e o Jev entra como classificador: ele decide qual skill combina com o pedido e só essa é injetada no contexto

A lista fica fora do contexto até o momento em que realmente precisa

Sacou o que aconteceu? A decisão "qual skill usar" é uma pergunta de classificação, com opções finitas e declaradas antes. É o formato Choice na veia, não é tarefa pra prosa

E de novo a mesma regra: o Jev escolhe, a skill executa

Esse tipo de raciocínio de camadas é o mesmo que vale pra decidir onde cada ferramenta encaixa no fluxo quando você tem orquestrador, agente e automação no mesmo projeto

Onde as pessoas duplicam esforço (e como evitar)

Aqui vão os quatro erros conceituais que mais aparecem, e todos nascem da mesma causa: não aceitar que cada camada já resolve a parte dela

1. Pedir explicação em texto ao Jev

Não vai vir. A saída é restrita ao schema tipado, ponto

Se você precisa de justificativa em prosa, o lugar dela é outra camada do seu fluxo, não o Jev. O que ele te dá de "explicação" é a confiança de 0 a 1 junto da resposta, e isso já é bastante informação pra decidir se você segue ou se escala pra um humano

2. Codificar regras de decisão no corpo da skill

Tome cuidado com isso! Se as opções válidas já são declaradas antes da execução, escrever no Markdown "nunca responda nada fora da lista" é texto morto ocupando contexto

O schema é o guardrail. A skill deveria estar falando de COMO montar boas perguntas, não repetindo uma restrição que o tipo já garante

3. Repetir na skill o que o frontmatter já resolve

Se allowed-tools limita as ferramentas, não precisa de um parágrafo pedindo por favor pro modelo não rodar os rm -rf da vida

E o corpo do SKILL.md não precisa se reapresentar: o name e a description já foram lidos pra ela ser acionada

4. Inflar contexto com referência que podia entrar sob demanda

Esse é o mais caro dos quatro

Como só name e description são carregados no início, o corpo grande não te custa nada enquanto a skill está parada. Mas o que você joga pra dentro de references/ e manda carregar sempre, aí sim pesa

Material de consulta é material de consulta: deixa em references/ e puxa quando o procedimento realmente pedir

O que aprendi montando skills de verdade

Deixa eu marcar o recorte antes de falar: o que eu tenho de mão na massa aqui é com skills no Claude Code, não com o Jev

Mas é justamente a parte que ensina o que uma skill deve e não deve carregar

No vídeo abaixo eu mostro uma skill que lê o código e desenha a arquitetura do sistema sozinha. Instalei escolhendo o Claude Code como destino e optei pelo modo de instalação recomendado pela própria ferramenta, que segundo a proposta dela deixa a skill universal, utilizável por qualquer IA

E aí eu fui pra cima

Primeiro pedi pra planejar a arquitetura de um e-commerce. O diagrama veio com o fluxo completo: checkout, integração de pagamento com a Appmax, webhook de retorno e gravação do pedido no banco

Depois clonei o repositório da Evolution API e pedi um diagrama de arquitetura de runtime com componentes principais, fluxo de dados, dependências externas e fronteiras de segurança. Ela executou o clone, analisou o código e devolveu o diagrama

Esse veio COMPLEXO: banco de dados, cache, integração com armazenamento externo e o caminho da mensagem desde o WhatsApp até a resposta gerada pela IA integrada

E pra fechar, pedi em português, sem termo técnico nenhum, a arquitetura completa de uma rede social, só pra ver como ela se comportava num sistema de maior escala

O que isso me ensinou sobre a anatomia de uma skill:

A description é o trabalho mais importante que você faz

Como é ela (junto do name) que fica disponível desde o início da sessão, é ela que decide se a skill vai ser acionada na hora certa ou se vai dormir no diretório

Description vaga, tipo "ajuda com arquitetura", é convite pra skill nunca aparecer ou aparecer errado. Escreve o que ela faz E quando deve ser usada, com as palavras que VOCÊ usa quando pede a coisa

O progressive disclosure é o que te deixa escrever skill longa sem culpa

Sabendo que o corpo só entra no contexto quando a skill é acionada, dá pra ser detalhista no procedimento sem medo de estar carregando peso morto na sessão inteira

Essa é a liberdade que muita gente não usa porque não sabe que existe

Etapa de validação dentro do procedimento muda a entrega

O que eu destaquei como diferencial nessa skill foi ela ter uma etapa de revisão antes de entregar o resultado final. Na minha opinião, isso melhora bastante a qualidade comparado a pedir direto num gerador de imagem genérico

E olha que isso é puro procedimento, ou seja, é exatamente o tipo de coisa que mora no corpo do SKILL.md, não numa camada de decisão

scripts/, references/ e allowed-tools existem pra você não escrever um romance

Se o passo é um executável, ele vai pra scripts/. Se é documentação que o modelo precisa ler, references/. Se a skill não deveria tocar em certas ferramentas, allowed-tools no frontmatter resolve em uma linha

O corpo do Markdown fica pro raciocínio, não pra tudo

Na demonstração eu ainda usei as funcionalidades extras: alternância entre tema claro e escuro, exportação em PNG e SVG e a opção de copiar o diagrama direto pra área de transferência

E fica a dica que eu dei lá: o diagrama gerado dá pra reaproveitar como insumo pra IA revisar o plano do sistema depois. Ele não é só bonito, é contexto

Pra mim não serve só pra desenhar arquitetura de sistema, viu? Dá pra mapear workflows de CI/CD, aprovações, chamadas de ferramentas, sequência de chamadas (quem chama quem e o que cada uma retorna) e resposta a incidentes

Entender a arquitetura antes de codar ajuda quem não tem background técnico e ajuda quem já é experiente. Evita os problemas clássicos de escopo mal planejado e de sistema que não escala

Pra começar do zero com skills, este vídeo do canal mostra o processo inteiro na prática, da instalação até o diagrama pronto:

Vale montar skill para o Jev agora?

Aqui entra o estado do acesso, que está movimentado

A TypeSafe abriu o cadastro do Jev pra todos sem waitlist em 20/09/2026

Poucos dias depois, em 22/09/2026, pausou novos cadastros por excesso de demanda

As contas já criadas seguem funcionando normalmente

O que isso significa na prática, dividido em dois cenários:

Se você já tem conta: pode compor as duas camadas hoje. Monta a skill com o procedimento, declara as perguntas tipadas e chama o endpoint

Se você não tem: nada te impede de estruturar as skills desde já

E esse é o melhor argumento a favor da separação de camadas que eu consigo dar: procedimento não depende de API

O SKILL.md que descreve como o seu time toma uma decisão, quais opções existem, o que fazer com confiança baixa e onde registrar o resultado, isso é conhecimento seu, escrito em Markdown, versionado no .claude/skills/ do projeto

Quando o acesso chegar, você plugga as perguntas tipadas num procedimento que já está maduro

Quem faz o contrário, corre atrás da API primeiro e vai escrever o procedimento depois, acaba com um monte de chamada solta e nenhuma documentação de por que aquela decisão era daquele jeito

Conclusão

A regra mental cabe em cinco palavras: procedimento na skill, veredito no Jev

A skill carrega o como fazer, o contexto, os scripts, as referências e os limites de ferramenta. Ela é Markdown num diretório, com name e description sempre visíveis e o corpo entrando sob demanda

O Jev carrega a decisão: state mais perguntas tipadas, resposta restrita ao schema, confiança de 0 a 1 do lado. Não escreve prosa, não gera código, não te explica nada, e é exatamente por isso que ele é bom no que faz

Quando você respeita essa fronteira, para de duplicar regra em dois lugares e para de inflar contexto sem motivo

Próximo passo, se quiser começar hoje: escolhe UMA decisão repetitiva do seu fluxo, escreve uma skill pequena com a description bem afiada, testa se ela é acionada na hora certa

Só depois você pluga as perguntas tipadas

Skill pequena que dispara certo vale mais que skill completona que nunca acorda 😀

Até o próximo post!