Como escrever uma skill que ensina o agente a montar perguntas tipadas do Jev?

Um agente que improvisa pergunta tipada não erra feio na sintaxe, ele erra no silêncio: monta um score sem níveis escritos, joga três julgamentos dentro de um noul e devolve um número que parece resposta, mas é chute com casinha decimal

O Jev foi apresentado pela TypeSafe AI em 15 de setembro de 2026 como o primeiro modelo da classe System One, e é aí que a coisa aperta: o modelo responde bem o que você perguntou bem

É exatamente esse o trabalho de uma skill. Ela não existe pra ensinar API, existe pra impedir que o agente invente type, criteria e escala quando ele está com pressa de fechar a task

Antes que você pergunte: sim, já existe skill pronta pra isso. A TypeSafe publica uma agent skill oficial, e ainda tem opções de comunidade no GitHub

Só que elas ensinam o primitivo, não o SEU domínio. Lá pro final eu comparo os dois caminhos, e adianto: eles se somam bem

Bora escrever o texto dessa skill, linha por linha?

O que você precisa saber antes de escrever a skill

Esse post é sobre o TEXTO da skill, beleza? Não é sobre configurar produto, não é sobre integração

Mas tem três coisas que você precisa ter na cabeça antes de abrir o arquivo, senão a skill sai descrevendo o que você não entendeu direito

Primeiro: a anatomia da pergunta tipada. Toda pergunta do Jev tem um id (a chave que você escolhe), um type e instructions. Os tipos choice e score também recebem criteria obrigatório, e no noul o criteria é opcional, servindo pra esclarecer o que significa sim e o que significa não

Segundo: como a chamada acontece. É um único endpoint, POST https://api.typesafe.ai/v1/systemone, com três campos obrigatórios no corpo: model (ex.: jev-latest), state e questions. O questions é um mapa de perguntas tipadas e as respostas voltam nas mesmas chaves

O state pode ser string, objeto JSON ou array de valores de texto, e vale a pena entender bem como montar o state do Jev antes de escrever qualquer instrução sobre ele na skill

Um detalhe que muda o desenho das perguntas: o Jev ingere o state uma vez e avalia todas as perguntas em paralelo e de forma independente contra ele. Ou seja, adicionar pergunta quase não muda a latência

Isso é ouro pra skill. Decompor pergunta complexa em cinco perguntas atômicas não sai "caro" em tempo, então a skill pode mandar decompor sem medo 🙂

Terceiro: onde a skill vive. No Claude Code, uma skill é um diretório com um arquivo SKILL.md: frontmatter YAML entre marcadores --- mais o conteúdo markdown com as instruções que o Claude segue

Skills de projeto ficam em .claude/skills/ e valem só no projeto atual. Skills pessoais ficam em ~/.claude/skills/ e ficam disponíveis em todos os projetos

Escolha simples: se as perguntas tipadas são desse produto, vai em .claude/skills/. Se é seu jeito de trabalhar em qualquer projeto, vai em ~/.claude/skills/

Passo a passo: escrevendo o conteúdo do SKILL.md

1. Escreva o frontmatter pensando no gatilho, não na estética

No frontmatter, o campo description é o que determina quando o Claude invoca a skill, e o nome do diretório (ou o campo name, quando você define) vira o comando digitado

A doc de boas práticas é direta: a description deve responder o que a skill faz E em que situações ativar, incluindo frases e contextos de gatilho específicos, porque o modelo tende a subacionar skill quando o match não é óbvio

   ---
   name: jev-questions
   description: Monta perguntas tipadas do Jev (noul, choice e score) para avaliacao System One, com criteria e escalas escritos. Use quando o pedido falar em "montar pergunta Jev", "avaliacao System One", "questions do systemone", "classificar com noul", "score de 1 a 5 com IA" ou quando o codigo precisar de uma decisao tipada sobre um texto.
   ---

O erro comum deste passo: escrever description: skill para o Jev. Isso não tem gatilho nenhum. O agente lê, não reconhece situação e segue improvisando por conta

2. Abra o corpo com o objetivo em uma frase de comando direto

As boas práticas de autoria pedem instruções escritas como comandos diretos. Então nada de "esta skill tem como objetivo auxiliar o desenvolvedor a"

   ## Objetivo

   Transforme qualquer pedido de julgamento sobre texto em perguntas tipadas do Jev, escolhendo entre noul, choice e score, e nunca invente campo que nao esteja descrito aqui.

O erro comum deste passo: objetivo em forma de resumo passivo. O agente trata prosa descritiva como contexto opcional, e trata imperativo como regra

3. Declare a regra central: atômico sempre

O guia oficial tem um conceito que ele mesmo coloca como o mais importante: fazer as perguntas mais explícitas, estreitas, específicas e atômicas possíveis, decompondo pergunta complexa em perguntas que avaliam uma propriedade cada, e combinando os resultados com lógica no seu código

Essa frase praticamente já é o parágrafo da sua skill

   ## Regra central

   Cada pergunta avalia UMA propriedade. Se a pergunta tem "e", "ou", "no geral" ou "de modo geral", decomponha.
   Combine os resultados com logica no codigo, nunca peca ao modelo para combinar julgamentos.

O erro comum deste passo: deixar isso como sugestão ("prefira perguntas específicas"). Sugestão vira exceção na primeira pergunta difícil

4. Descreva os três tipos com campos e limites, sem enfeite

São três tipos: noul (sim/não), choice (uma opção de um conjunto que você definiu) e score (posição numa escala que você escreveu), com as respostas acompanhadas de probabilidades e confiança

O que a skill precisa dizer de cada um:

– noul: devolve um número entre 0 e 1 com a probabilidade de a afirmação ser verdadeira, e um enunciado afirmativo funciona tão bem quanto uma pergunta – choice: aceita até 255 opções, e cada opção custa poucos tokens, então passe a lista COMPLETA em vez de uma lista curta. O criteria é um mapa de opção para descrição de rubrica, usando null quando a opção não precisa de detalhe extra – score: o criteria é um array ordenado de descrições de nível, do extremo baixo ao alto, com no mínimo 2 níveis e no máximo 10

   ## Tipos

   noul: use para verdadeiro/falso. Resposta e probabilidade entre 0 e 1.
   Escreva como afirmacao. criteria e opcional, use so para separar sim de nao em caso ambiguo.

   choice: use para categoria unica. Ate 255 opcoes, passe a lista completa.
   criteria e um mapa opcao -> descricao, com null quando a opcao e obvia.

   score: use para intensidade ou qualidade em escala.
   criteria e um array ordenado do nivel mais baixo ao mais alto, entre 2 e 10 niveis.
   Escreva o que caracteriza CADA nivel, nunca apenas "ruim", "medio", "bom".

O erro comum deste passo: esquecer os limites numéricos. Sem o teto de 10 níveis escrito, o agente monta escala de 1 a 100 e você descobre isso em produção

5. Mande manter a pergunta curta e empurrar apoio pra campos nomeados

instructions e criteria costumam ser strings, e pra pergunta curta e sem ambiguidade a string basta. Quando a orientação é de vários tipos, a doc recomenda usar objetos ou arrays com campos nomeados em vez de prosa densa

   ## Formato

   A pergunta fica em UM campo, curta.
   Dado de apoio (lista de termos, regra de negocio, exemplo) vai em campo nomeado, nunca dentro da frase da pergunta.

O erro comum deste passo: instructions de doze linhas com regra de negócio, exemplo e ressalva tudo junto. Fica ilegível pra você e ambíguo pro modelo

6. Obrigue o agente a centralizar perguntas e thresholds num arquivo só

A recomendação oficial pra uso com agentes de código é bem clara: o que mais importa que humanos revisem são as perguntas e as constantes de threshold, e elas devem ficar definidas num único arquivo de código pra serem fáceis de achar

Isso precisa estar NA skill, porque o agente por padrão espalha constante pelo lugar onde ela é usada

O nome e o caminho desse arquivo são escolha sua, a doc não manda nenhum em específico: o que ela pede é que seja UM só e fácil de achar

   ## Onde o codigo mora

   Defina TODAS as perguntas e TODAS as constantes de threshold num unico arquivo de codigo, sempre o mesmo do projeto.
   Nao declare threshold inline no ponto de uso. Importe do arquivo unico.

O erro comum deste passo: aceitar if (score > 0.8) espalhado pelo código. Aí ninguém revisa, porque ninguém acha

7. Segure o tamanho do SKILL.md

As boas práticas pedem manter o SKILL.md abaixo de 500 linhas, referenciando arquivos extras para os detalhes

Então a skill principal fica com regra, tipos e formato. Catálogo enorme de exemplo, rubrica comprida de domínio, tabela de categorias: tudo isso vai pra arquivo de referência citado no corpo

O erro comum deste passo: transformar a skill num manual. Skill comprida dilui a regra, e a regra é o único motivo dela existir

Exemplos de pergunta boa e ruim para colar na skill

Aqui está a parte que mais muda o comportamento do agente: par de exemplo ruim e bom, com o motivo do erro escrito do lado

Cola isso dentro do SKILL.md mesmo, é conteúdo de skill, não é conteúdo de post

A pergunta guarda-chuva (o clássico)

A própria doc oficial usa esse exemplo: em vez de "rate this startup pitch", pergunte separadamente sobre tamanho de mercado, viabilidade técnica e diferenciação

{
  "pitch_score": {
    "type": "score",
    "instructions": "Rate this startup pitch",
    "criteria": ["ruim", "medio", "bom"]
  }
}

Por que falha: "rate this pitch" esconde três julgamentos diferentes dentro de um número, e os níveis não descrevem nada. Um pitch com mercado gigante e tecnologia impossível cai no mesmo lugar de um pitch morno em tudo

Versão boa, decomposta:

{
  "market_size_stated_above_1b": {
    "type": "noul",
    "instructions": "The pitch states a target market above one billion dollars"
  },
  "technical_feasibility": {
    "type": "score",
    "instructions": "Viabilidade tecnica do que o pitch promete entregar",
    "criteria": [
      "Depende de tecnologia que nao existe hoje",
      "Existe em laboratorio, sem produto em producao conhecido",
      "Existe em producao em outros produtos, integracao e o trabalho",
      "Usa tecnologia madura e disponivel, e so montar"
    ]
  },
  "differentiation_is_explicit": {
    "type": "noul",
    "instructions": "O pitch nomeia ao menos um concorrente e diz o que faz diferente dele"
  }
}

Repara que cada pergunta responde uma coisa, e a nota final do pitch vira lógica no seu código, não no modelo

O noul escrito como enunciado

A doc mostra que um enunciado afirmativo funciona tão bem quanto uma pergunta, e usa esse exemplo: "The customer is requesting a refund"

Ruim:

{
  "refund": {
    "type": "noul",
    "instructions": "O cliente esta insatisfeito e quer resolver isso de alguma forma?"
  }
}

Por que falha: "insatisfeito" e "resolver de alguma forma" são duas coisas, e nenhuma delas é o que você vai usar no if

Bom:

{
  "customer_requesting_refund": {
    "type": "noul",
    "instructions": "The customer is requesting a refund",
    "criteria": "Verdadeiro quando o cliente pede dinheiro de volta. Falso quando pede troca, reparo ou apenas reclama."
  }
}

O criteria aqui é opcional, mas é ele que separa reembolso de troca. Duas coisas que todo suporte confunde 😀

O choice com lista aparada

Ruim:

{
  "refund_reason": {
    "type": "choice",
    "instructions": "Motivo do pedido",
    "criteria": {
      "produto": null,
      "entrega": null,
      "outros": null
    }
  }
}

Por que falha: a categoria "outros" vira lixeira e come metade dos casos. E como um choice aceita até 255 opções, cortar a lista pra três não economiza quase nada

Bom:

{
  "refund_reason": {
    "type": "choice",
    "instructions": "Motivo declarado pelo cliente para o pedido de reembolso",
    "criteria": {
      "produto_danificado": "Chegou quebrado, amassado ou com defeito fisico",
      "produto_diferente_do_anunciado": "Recebeu item diferente do que comprou",
      "atraso_na_entrega": "O cliente reclama do prazo, nao do produto",
      "cobranca_duplicada": "Aparece mais de uma cobranca pelo mesmo item",
      "arrependimento": null,
      "produto_nao_entregue": "Nada chegou",
      "motivo_nao_declarado": "O cliente pede reembolso sem dizer por que"
    }
  }
}

Se liga no uso do null: "arrependimento" dispensa rubrica, os ambíguos ganham descrição. É exatamente pra isso que o criteria do choice é um mapa de opção para descrição

E "motivo_nao_declarado" é bem melhor que "outros", porque é uma categoria de verdade e não um balde

O score sem escala escrita

Ruim: criteria com ["1", "2", "3", "4", "5"]

Por que falha: "3" não significa nada. O modelo tem que adivinhar onde fica a fronteira, e você nunca sabe se 3 é aceitável ou não

Bom: array ordenado do extremo baixo ao alto, com cada nível descrevendo um estado observável, como no technical_feasibility ali em cima. Lembrando o teto: no máximo 10 níveis

O que deixar de fora para o agente não improvisar

Agora a parte que ninguém escreve e que é a que mais segura o agente: a lista de proibições

A doc oficial lista três antipadrões, e eles entram na skill como negativa explícita:

## Nunca faca isso

1. Nunca peca ao modelo algo que o codigo calcula de forma exata
   (soma, media, diferenca de valores, comparacao numerica pronta).
2. Nunca esconda varios julgamentos dentro de uma pergunta. Decomponha.
3. Nunca coloque no state mais contexto do que a pergunta precisa.
   Material irrelevante custa acuracia (context rot).

O terceiro merece um parágrafo, porque é contraintuitivo. Entupir o state parece grátis, e em dinheiro quase é: a documentação lista a entrada do Jev a US$ 0,042 por 1 milhão de tokens e a saída a US$ 0,00 por 1 milhão de tokens

O custo não é o problema. O custo é a acurácia, porque contexto irrelevante degrada a resposta

As limitações do modelo entram como proibição

O jev-1.13 tem limitações documentadas, e elas precisam estar na skill senão o agente monta pergunta que nunca vai funcionar bem:

• Data é lida como texto, não como quantidade ordenada. Comparar qual data vem antes, distância entre datas ou se cai numa janela é inconfiável
• Contagem é inconfiável. Caracteres, ocorrências, itens de lista longa, com o erro crescendo conforme o tamanho

## Limitacoes do modelo (jev-1.13)

Nao pergunte comparacao de datas, distancia entre datas ou se uma data cai numa janela.
Calcule isso no codigo e, se precisar, passe o resultado pronto no state.

Nao pergunte contagem (caracteres, ocorrencias, itens de lista).
Conte no codigo.

Repara que isso é o mesmo espírito do antipadrão 1: tem coisa que é trabalho do for, não do modelo. Vale a pena entender bem essa fronteira quando você for dividir os papéis dentro do agente

Orçamento de contexto

A skill também precisa avisar do teto: são 64k pra cobrir o state mais todas as perguntas somadas, e 32k que se aplicam ao state mais a pergunta mais longa

É um limite que engana, porque parece folgado até o agente decidir colar o documento inteiro no state e escrever rubricas quilométricas

Threshold não é decisão de agente

Última proibição e talvez a mais importante: o agente não define threshold sozinho

A recomendação oficial diz que perguntas e constantes de threshold são justamente o que humanos precisam revisar. Se o agente escolhe o número, o único revisor virou o agente

## Threshold

Nunca escolha valor de threshold por conta.
Deixe a constante com nome explicito, comentario TODO e valor marcado para revisao humana.

Um bom parâmetro de como isso fica na prática vem do cookbook oficial de self-consistency com nouls, que trata a faixa de 0,30 a 0,70 como resultado explicitamente incerto e encaminha esses casos pra revisão humana

Ou seja: a saída do Jev não precisa ser só sim ou não. Pode ser sim, não e "chama um humano", e isso é decisão de projeto, não de agente

Pra começar do zero com skills e ver uma funcionando de ponta a ponta, esse vídeo do canal mostra uma skill que lê o código do projeto e desenha a arquitetura sozinha:

Escrever a sua skill ou instalar a oficial da TypeSafe?

Pergunta justa, e a resposta não é excludente

A TypeSafe publica uma agent skill oficial que dá ao agente de código contexto da API: os três tipos de pergunta, os padrões arquiteturais e boas práticas de estruturação das avaliações

No Claude Code a instalação é por plugin marketplace:

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

Para outros agentes existe um comando via npx:

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

E tem também skills de comunidade para Jev no GitHub, mantidas por terceiros (não oficiais), como o jev-agent-skill e o jev-skill

Comparando o que cada caminho entrega:

O desenho que faz mais sentido: a oficial pro agente saber o que é noul, choice e score, e a sua pro agente saber as SUAS categorias, as SUAS escalas e o arquivo onde perguntas e thresholds moram

Uma ensina o primitivo, a outra ensina a casa

Conclusão

Skill boa não é a que explica tudo, é a que restringe

O agente já sabe escrever JSON. O que ele não sabe é que "outros" arruína um choice, que escala sem nível descrito é número solto, que data e contagem são trabalho do código e que threshold é decisão de humano

Esses quatro parágrafos valem mais que 400 linhas de documentação copiada

Próximo passo é curto: cria o diretório em .claude/skills/, escreve a primeira versão do SKILL.md com o frontmatter de gatilho, cola os pares de exemplo bom e ruim, e roda uma avaliação real contra POST https://api.typesafe.ai/v1/systemone pra ver se o agente respeitou os tipos

Se ele voltar com um score de níveis vazios, você já sabe qual parágrafo da skill está fraco 😀

até o próximo post!