Quais skills vale a pena criar primeiro para trabalhar com o Jev?

Skill boa é a que evita repetição de decisão, não a que repete documentação

Parece óbvio, mas é onde quase todo mundo escorrega: a primeira skill que a galera escreve é um resumo da API, que o modelo já consegue ler sozinho

O Jev é o modelo System One da TypeSafe AI, e ele não gera texto: você manda um estado e perguntas tipadas, ele devolve resposta tipada com probabilidade

São três primitivas de pergunta: Noul (sim/não), Choice (escolha entre opções) e Score (posição numa régua ordenada)

Ou seja, todo trabalho no projeto vira sempre a mesma coreografia: montar a pergunta, definir as categorias, tratar probabilidade baixa e registrar o resultado

A pergunta deste post é simples: quais dessas repetições merecem virar skill no Claude Code e quais é melhor deixar quietas? 🙂

O que você precisa antes de criar a primeira skill

Antes de sair criando pasta, o básico:

Claude Code instalado e um projeto de verdade pra testar. Skill sem caso real vira decoração

Entender o que é uma skill. No Claude Code, uma skill é só uma pasta com um arquivo SKILL.md dentro. Skill pessoal fica em ~/.claude/skills/<nome>/SKILL.md e skill de projeto fica em .claude/skills/<nome>/SKILL.md, versionada junto com o repositório

O SKILL.md tem frontmatter YAML com name e description, mais um corpo em markdown. E se liga nisso: a description é o que o Claude usa pra decidir se aciona a skill, não é enfeite

Esses dois são o mínimo pra skill existir, mas o frontmatter aceita outros campos opcionais que mexem no COMO ela é acionada, caso de disable-model-invocation e allowed-tools, e eu volto neles no passo a passo

Acesso ao Jev. Aqui tem um detalhe chato de calendário: a TypeSafe tirou a waitlist em 20 de setembro de 2026, com US$ 5 de crédito grátis no cadastro, e dois dias depois, em 22 de setembro, pausou os novos cadastros por excesso de demanda

As contas existentes seguem funcionando, e até 26 de setembro de 2026 não existe confirmação oficial de reabertura

Se você não pegou conta a tempo, o Jev também é servido pelo Cloudflare Workers AI sob o identificador typesafe/jev, e o OpenRouter lista typesafe/jev-1.13 com contexto de 32K

Um jeito de chamar o modelo. Tem SDK Python oficial:

pip install typesafe-sdk

Ele exige Python 3.10 ou superior, lê a chave da variável de ambiente TYPESAFE_API_KEY e usa o modelo jev-latest por padrão

Ou você bate direto na API:

POST https://api.typesafe.ai/v1/systemone

corpo obrigatório: state, model, questions

E aqui vale o aviso pra economizar sua tarde: não é compatível com o formato OpenAI

Não tem /chat/completions, não tem messages, não tem temperature. Se você jogar seu client de chat favorito nisso esperando que funcione, não vai

Uma requisição leva um único state e várias questions, avaliadas em paralelo e isoladas contra o mesmo estado

As quatro tarefas que mais se repetem num projeto com decisão tipada

Antes de decidir o que virar skill, mapeia a repetição. Sem esse mapa você cria skill por empolgação

1. Montar a pergunta:

A cada nova decisão do produto alguém precisa escolher a primitiva: isso é sim/não, escolha entre opções ou régua ordenada?

E a documentação recomenda perguntas atômicas e curtas, compostas depois em código, em vez de uma pergunta gigante que tenta resolver tudo

O que se repete aqui é o critério, sempre igual: quebrar a decisão em pedaços pequenos e juntar na aplicação

2. Definir as categorias:

Um Choice aceita até 255 opções e um Score usa de 2 a 10 níveis

E tem uma pegadinha estrutural: um Choice sempre elege um vencedor, ele não consegue se abster

A documentação orienta incluir uma opção other ("nenhuma das anteriores") ou fazer a pergunta "nenhuma destas" como um Noul separado

O que se repete é essa obrigação: toda lista de opções nova precisa da rota de escape

3. Tratar probabilidade baixa:

O Noul devolve uma probabilidade entre 0 e 1 de a afirmação ser verdadeira

Não existe campo separado de confiança: a própria probabilidade É a medida de certeza

E calibração é estatística de grupo, não promessa individual: eventos marcados com 80% acontecem cerca de 80% das vezes no conjunto, o que significa que uma resposta com probabilidade alta ainda pode estar errada

As faixas de decisão (automático, revisão humana, abstenção) ficam no código de quem integra, não no modelo

O que se repete é a convenção de faixas do seu projeto

4. Registrar o resultado:

Todo ponto de integração acaba precisando guardar a resposta junto da probabilidade, pra depois conferir se a coisa está calibrada no agregado

Se esse registro cai num fluxo de automação, dá pra empurrar por um evento HTTP mesmo, e a lógica é a mesma de criar um webhook no n8n pra receber o payload e seguir o processo

O que se repete é o formato do log, e isso é convenção pura do projeto

Vale virar skill ou não? Tabela de decisão

Meu critério, bem direto:

Vale skill quando existe convenção do projeto que o agente erraria sozinho E que se repete a cada pergunta nova

Não vale quando é conhecimento genérico já coberto pela skill oficial da TypeSafe, quando é decisão de produto que muda a cada caso, ou quando a regra cabe em duas linhas no CLAUDE.md

Como criar a primeira skill de perguntas tipadas passo a passo

A primeira é a de convenções de pergunta tipada. Bora ver na prática?

1. Instale a skill oficial da TypeSafe ANTES de escrever a sua. No Claude Code:

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

Ela mora em skills/typesafe-ai/SKILL.md dentro do repositório typesafe-ai/skills e dá ao agente o contexto da API TypeSafe

O erro comum deste passo: escrever a sua skill primeiro e descobrir depois que metade dela era documentação que já existia. Vale o mesmo raciocínio de procurar skills do Claude prontas antes de partir do zero

2. Crie a pasta da skill dentro do projeto, pra ela ser versionada com o código:

mkdir -p .claude/skills/perguntas-tipadas

O erro comum deste passo: jogar em ~/.claude/skills/ uma convenção que é do time. Aí funciona na sua máquina e some na de todo mundo

3. Escreva o frontmatter pensando na description como gatilho. É ela que o Claude lê pra decidir se aciona a skill:

---
name: perguntas-tipadas
description: Convenções do projeto para montar perguntas ao Jev (Noul, Choice, Score), incluindo tamanho da pergunta, limites de opções e regra de abstenção. Use ao criar ou revisar qualquer pergunta tipada.
---

O erro comum deste passo: description vaga tipo "ajuda com o Jev". Com isso a skill ou nunca dispara ou dispara em tudo

4. Escreva o corpo com as convenções, não com a API. O corpo é markdown livre, então foca no que é decisão do seu projeto:

• qual primitiva usar pra cada tipo de decisão do domínio
• perguntas atômicas e curtas, composição em código
• os limites que o formato aceita: até 255 opções num Choice, de 2 a 10 níveis num Score
• todo Choice precisa de opção other ou de um Noul "nenhuma destas", porque Choice não se abstém
• onde os thresholds ficam (no código da aplicação) e que a skill NÃO define número mágico

O erro comum deste passo: transformar o SKILL.md num resumão da documentação da API. Isso não evita repetição de decisão, só aumenta contexto

5. Decida o acionamento. No Claude Code, disable-model-invocation: true impede que o Claude carregue a skill sozinho, deixando ela só pra invocação explícita, e allowed-tools lista as ferramentas que rodam sem aprovação a cada uso enquanto a skill está ativa

Pra uma skill de convenção, acionamento automático normalmente é o que você quer. Se ela é intrusiva e entra onde não deve, aí sim desliga

Tome cuidado com allowed-tools: você está abrindo mão de aprovação por uso, então liste o mínimo

E vale saber: o padrão aberto Agent Skills define name, description, license, compatibility, metadata e allowed-tools. Os outros campos do frontmatter são extensões do Claude Code

6. Revise com a skill-creator. A Anthropic mantém o repositório público anthropics/skills, que inclui a skill skill-creator justamente pra criar, revisar e melhorar outras skills

O erro comum deste passo: pular a revisão e descobrir em produção que a skill fixou um limiar de probabilidade como se fosse verdade do modelo. Não é: o limiar é escolha sua

A segunda skill: faixas de decisão e o que fazer com probabilidade baixa

Essa é a que padroniza o consumo da resposta, e na minha visão é a que dá mais retorno depois da primeira

1. Escreva onde o projeto define as faixas. Automático, revisão humana e abstenção: os três caminhos e quem decide cada um

A skill documenta que essas faixas vivem no código da aplicação, porque o modelo não decide isso pra você

2. Deixe explícito de onde vem a certeza. O Noul devolve probabilidade de 0 a 1 e não existe campo extra de confiança

Se alguém no time procurar um confidence na resposta, vai procurar pra sempre

3. Trate o Choice que sempre elege vencedor. A convenção precisa dizer o que fazer quando o vencedor é other ou quando o Noul complementar de "nenhuma destas" veio alto: normalmente isso cai na rota de abstenção, não na automática

4. Padronize o registro. Guarde a resposta junto da probabilidade que veio, sempre

Sem isso você não tem como olhar a calibração depois no agregado, e calibração só existe em grupo

O erro comum desta skill: tratar probabilidade alta como garantia individual

Calibrado significa que eventos marcados com 80% acontecem cerca de 80% das vezes no conjunto

No caso único, a resposta com probabilidade alta ainda pode estar errada. Quem escreve a regra de negócio precisa ter isso tatuado 😀

A skill que decide qual skill carregar (padrão do cookbook da TypeSafe)

Essa aqui é o caso avançado, e é meio meta: usar o Jev pra escolher qual skill o agente carrega

A TypeSafe publica um cookbook de skill suggestion com um padrão de duas chamadas

A primeira chamada ranqueia todo o catálogo e responde se o turno precisa de alguma skill

A segunda relê só as três melhores, agora com a descrição completa, e pode rejeitar todas

O número medido no catálogo Hermes, com 488 requisições, jev-1.12 e 182 skills: carregamento de skill errada caiu de 16,8% para 7,3% e carregamento desnecessário caiu de 9,8% para 4,0%

Massa, né? Mas repara na condição: 182 skills

Com três skills no repositório isso não resolve problema nenhum, você só adiciona uma chamada de rede no caminho

O que torna o padrão viável em catálogo grande é o custo: o Jev sai por US$ 0,042 por milhão de tokens de entrada, com tokens de saída não cobrados

E tem teto pra respeitar: 64k tokens por requisição (o state mais todas as perguntas), 32k para o state mais a maior pergunta, 250k tokens por segundo e 1.200 requisições por minuto, com ajuste dinâmico conforme demanda e capacidade

Catálogo grande demais estoura o limite de requisição, então ranquear tudo de uma vez tem fronteira

O que NÃO compensa virar skill

Veredito honesto, porque skill demais é contexto demais e contexto demais é ruído:

Não duplique a skill oficial da TypeSafe. Se o conteúdo é "o que é Noul, o que é Choice, como é o corpo da requisição", já está coberto. Instale a oficial e pare

Não crie skill pra decisão de produto. Quais categorias o negócio precisa é reunião, não convenção. Muda a cada caso e envelhece em uma semana

Não crie skill pra regra de uma linha. "Use o modelo padrão" e "nunca chame a API sem timeout" moram no CLAUDE.md, não numa pasta nova

Não coloque dado que muda no SKILL.md. Preço e limites de taxa mudam, e a documentação é a fonte. Skill com número velho é pior que skill sem número

A ordem que eu recomendaria: skill oficial da TypeSafe primeiro, depois a de convenções de pergunta tipada, depois a de faixas de decisão e registro

Skill suggestion só quando o catálogo justificar

Conclusão

Se você for lembrar de uma coisa só: skill existe pra parar de repetir decisão que o agente erraria sozinho

Comece por UMA, a de convenções de pergunta tipada, valide num caso real do projeto e só cresça depois que ela tiver evitado um erro de verdade

As boas skills para o Jev são quase sempre as chatas: quebrar a pergunta em pedaço pequeno, obrigar a rota de abstenção no Choice, deixar claro que o limiar é do seu código e registrar a probabilidade junto do resultado

Próximo passo concreto, na ordem: rodar claude plugin marketplace add typesafe-ai/skills e instalar a oficial, criar .claude/skills/ no repo e passar o rascunho pela skill-creator antes de comitar

Depois é só ir testando e apertando as convenções conforme o projeto reclamar…

Até o próximo post! =)