Skip to content

Desarrollo junto con Claude Code: TypeSafe Agent Skill ​

Las tres primeras lecciones desmontaron los cuatro patrones de arquitectura oficiales: preguntas paralelas y speculative fan-out, enrutamiento inteligente, puntuación compuesta. Como se dijo en la introducción de la etapa, la lección 4 resuelve la última pregunta: quién escribe este código.

La respuesta oficial: lo escribe tu coding agent, siempre que le instales TypeSafe Agent Skill, un skill oficial que empaqueta los tipos de preguntas de TypeSafe, los patrones de arquitectura y la forma de escribir las solicitudes en el flujo de trabajo del agent. Esta lección también desmonta un malentendido popular: Jev no sirve para reemplazar el modelo detrás de Claude Code. Duración total: 10 minutos.

Qué podrás hacer al terminar ​

  • Instalar TypeSafe Agent Skill en Claude Code con dos comandos, y en otros agent (Codex, etc.) con un solo comando npx, y explicar cómo actualizarlo y la actualización automática
  • Usar los 3 prompts de ejemplo oficiales para dirigir al agent: explorar el proyecto en busca de puntos de integración, ejecutar experimentos baratos con tu API key y proponer refactorizaciones comparando con el cookbook oficial
  • Explicar con claridad la división de tareas entre Jev y el coding agent: el agent escribe el código, Jev hace los juicios dentro del código; no existe ninguna configuración que reemplace el modelo detrás del agent por Jev
  • Organizar la integración de Jev según el principio de «reunir preguntas y umbrales en un solo archivo», para que el resultado del agent sea revisable y modificable de forma colaborativa
  • Usar las rutas de diagnóstico oficiales para los 5 problemas comunes y localizar fallos: el skill no se carga, campos inventados, el enrutamiento no cumple lo esperado…

Tu situación actual ​

  • Le pedí a Claude Code que integrara Jev en el proyecto; no había leído la documentación y se puso a escribir directamente: inventó nombres de campos (por ejemplo, leer .confidence de una respuesta de Noul, cuando Noul ni siquiera tiene ese campo) y fallaba al ejecutar. Le pegué media página de documentación, corrigió esto y volvió a inventar aquello
  • Me convence Jev por ser «rápido y barato, con respuestas que traen probabilidades», y quiero encontrar puntos de integración en mi proyecto, pero la documentación oficial tiene más de cien páginas y no sé por dónde hacer que el agent empiece a leer; si yo elijo y traduzco partes al prompt, siempre se me escapan reglas clave
  • No me atrevo a poner en producción las questions que escribe el agent: descripciones de opciones ambiguas, tres juicios metidos en una sola pregunta, umbrales escritos a mano y fijados sin criterio. El código corre, pero las respuestas son inestables; en la revisión, la definición de las preguntas está dispersa en cinco archivos y es imposible de revisar

Cuándo usar esta técnica ​

Cuando necesitas:

  • Hacer que agent como Claude Code, Codex y otros escriban directamente código de llamadas correcto a Jev, sin tener que pegar la documentación en el contexto cada vez
  • Revisar sistemáticamente un proyecto existente: qué análisis complejos, tablas de palabras clave y heurísticas frágiles pueden sustituirse por una pregunta tipada
  • Hacer que el agent valide la redacción de las preguntas con experimentos reales de API, en lugar de afirmar sin fundamento «debería funcionar»

Y no quieres:

  • Alimentar la documentación a mano: consume contexto y además nunca está completa
  • Corregir una y otra vez los campos inventados y los usos desactualizados del agent
  • Recibir un montón de código de integración con definiciones de preguntas dispersas por todas partes, imposible de revisar

Este es exactamente el escenario de uso descrito en SKILL.md: al construir, revisar o depurar código que llama a TypeSafe; al reemplazar «prompt a un LLM y luego analizar», coincidencia de palabras clave o heurísticas frágiles por preguntas tipadas; o al hacer brainstorming sobre dónde puede encajar el «sentido común programable» en tu aplicación.

🎒 Preparativos antes de empezar ​

  • Haber leído la introducción de la etapa de flujo de trabajo eficiente: saber que esta lección es la número 4 de la etapa y resuelve «quién escribe el código»
  • Tener Claude Code instalado, u otro coding agent que uses (Codex, Cursor, opencode, etc.); esta lección no enseña la instalación del agent en sí
  • Si quieres ejecutar el experimento del paso 4: que el TYPESAFE_API_KEY de la lección primera solicitud siga funcionando; si no lo tienes, crea uno en console.typesafe.ai/keys
  • Conviene tener a mano un proyecto real: el prompt de ejemplo del paso 3 consiste precisamente en que el agent analice tu código

Idea central ​

Primero, sitúa bien el papel de Jev. La documentación oficial de coding-agents de Jev lo deja claro desde el principio: no es un reemplazo directo del LLM detrás de Claude Code, Cursor, opencode, Copilot, Muse Spark, Grok Bot o herramientas similares; sigues usando tu coding agent como siempre y le haces escribir código que «llama a Jev para tomar decisiones».

Jev es System One, un modelo de decisión: no genera texto, no escribe código, no conversa; solo responde preguntas tipadas. Palabras textuales de la documentación oficial: no existe una configuración como model: "jev-latest" que convierta tu coding agent en un agent impulsado por Jev: los dos sistemas resuelven problemas distintos.

Entonces, ¿qué instala el TypeSafe Agent Skill? No es cambiar de modelo, es darle contexto al agent. Definición oficial de un skill: darle al coding agent el contexto completo de la API de TypeSafe: tipos de preguntas, patrones de arquitectura y mejores prácticas para organizar solicitudes. Más una «guía de live docs»: el SKILL.md exige explícitamente que el agent trate docs.typesafe.ai como fuente de verdad sobre sintaxis de solicitudes, SDK y límites, en lugar de confiar en su memoria de entrenamiento.

Dimensión de comparaciónAgent sin skill instaladoAgent con skill instalado
Campos de la APILos escribe de memoria, los nombres de campo pueden ser inventadosSigue los tipos oficiales; si no está seguro, consulta las live docs
Diseño de preguntasUn solo prompt mete todos los juicios, saca JSON y lo parseaUn juicio por pregunta, respuestas tipadas, el código ramifica directamente
ArquitecturaEscribe sobre la marcha, sin planOrganizada según patrones oficiales: preguntas en paralelo, gating, puntuación compuesta
Método de verificaciónAfirmar que «debería funcionar»Probar la API de verdad, conservando el payload de cada caso

La filosofía central que el skill enseña al agent: los juicios se le dan a Jev, las decisiones se quedan en el código. El SKILL.md ve cada decisión como una tabla de verdad: Jev aporta las entradas («¿el cliente suena frustrado?», «¿de qué producto habla este mensaje?»), y el código contiene la lógica que mapea entradas a acciones. Al contrario, las preguntas que hacen que Jev decida directamente («¿debería escalarse este ticket?», «¿qué debería hacer el agent ahora?») indican que la pregunta está mal planteada a nivel equivocado: descompón la decisión en los juicios de los que depende, y escribe la decisión misma en el código, donde es visible y testeable. El código de las tres primeras lecciones sigue exactamente esta forma: Jev da intent y complexity, y un if/elif decide el enrutamiento.

Si vienes con otras expectativas, la documentación oficial ofrece además una tabla de correspondencia:

Lo que querías…La forma correcta
Hacer que tu coding agent sea mejor escribiendo código que llame a TypeSafeInstalar el TypeSafe agent skill (esta lección)
Usar Jev en la app que construyes para enrutamiento, clasificación, puntuación y guardrailsEmpezar por la primera solicitud; para los patrones, ver las tres primeras lecciones de esta etapa
Cambiar el modelo detrás de tu coding agentJev no hace eso. Sigue usando un LLM coding agent, y usa Jev por separado donde tu producto necesite decisiones rápidas, calibradas y estructuradas
Probar Jev sin escribir códigoAbrir el Playground (console.typesafe.ai/playground), pegar el state y añadir preguntas

Sígueme paso a paso ​

Paso 1: instalar el TypeSafe Agent Skill ​

Por qué: cuando el agent no ha leído la documentación de TypeSafe, solo puede escribir las llamadas de memoria de entrenamiento, y es fácil que invente nombres de campos. El skill carga de una sola vez la experiencia oficial de integración en el flujo de trabajo del agent; todos los pasos siguientes se construyen sobre esto.

Forma A (recomendada): plugin de Claude Code ​

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

Deberías ver: los dos comandos terminan con normalidad y sin errores. La documentación oficial no da el texto exacto de salida; para saber si la instalación funcionó, guíate por la verificación del paso siguiente.

Forma B: otros agents (Codex etc., vía skills.sh) ​

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

Elige el agent que estés usando cuando te lo pregunte. Por defecto se instala en el proyecto actual; para tenerlo disponible globalmente añade -g.

Forma C: dejar que el agent se instale solo ​

Pega tal cual este prompt oficial al agent, y él mismo detectará el entorno y lo ejecutará:

text
Install the TypeSafe skill. If you're in Claude Code, run `claude plugin marketplace add typesafe-ai/skills`, then `claude plugin install typesafe@typesafe-ai`. If you're in another agent, run `npx skills add typesafe-ai/skills --skill typesafe-ai` and select your agent. Use one installation method. You can read the skill directly at https://github.com/typesafe-ai/skills/blob/main/skills/typesafe-ai/SKILL.md (raw: https://raw.githubusercontent.com/typesafe-ai/skills/main/skills/typesafe-ai/SKILL.md). Then use the TypeSafe skill when working on this project.

⚠️ Elige solo una forma

La documentación oficial advierte explícitamente: mezclar varias formas genera copias duplicadas (duplicate copies). Si instalas manualmente, copia todo el directorio skills/typesafe-ai (incluidos los archivos de referencia) en el directorio de skills del agent.

  • Solo usé una forma de instalación

Paso 2: llamarlo por su nombre y confirmar que el skill está cargado ​

Por qué: instalarlo ≠ que el agent lo use por iniciativa propia. El uso oficial es «mencionarlo por su nombre en el prompt»: decir "use the TypeSafe skill" funciona en cualquier agent; con el plugin de Claude Code además se puede invocar el comando directamente.

Escribe esto en Claude Code:

text
/typesafe:typesafe-ai

O escribe esto en un mensaje a otro agent:

text
Use the TypeSafe skill when working on this project.

Deberías ver: que la respuesta del agent incluya el contexto de TypeSafe: mencione state, questions, tipos de pregunta como Choice/Score/Noul, o que vaya por sí mismo a leer la documentación live de docs.typesafe.ai. El SKILL.md define las live docs como fuente de verdad sobre sintaxis de solicitudes y límites; un agent con el skill bien instalado consulta antes de escribir, en lugar de empezar a inventar.

¿No se cargó? Dos pasos de diagnóstico oficiales: confirma que el comando de instalación instaló el skill en el agent que realmente estás usando (la forma B pide elegir al instalar) → reinicia el agent y vuelve a intentarlo.

  • La respuesta del agent contiene contexto de tipos de pregunta / state / questions, y no improvisación libre

Paso 3: usar el prompt de ejemplo oficial para que el agent encuentre los puntos de integración del proyecto ​

Por qué: la mejor forma de empezar no es decirle al agent dónde conectar Jev, sino dejar que el agent con el skill lo encuentre solo. La documentación oficial lo lista como «a good prompt to start with».

En el directorio de tu proyecto, envía esto al agent (texto oficial original):

text
Using the TypeSafe skill, explore the project and find opportunities for using
intelligent judgement to stand in for complex parsing or other fragile code.

Deberías ver: el agent escanea el código, señala dónde están los parses frágiles, las listas de palabras clave y las reglas heurísticas, y propone cuáles se pueden sustituir por «preguntas tipadas + decisiones en código».

El criterio para juzgar la calidad de las propuestas es la tabla de verdad de la idea central: una buena propuesta tiene la forma «aquí añadir un Choice / Noul, y el código ramifica según la respuesta»; si el agent propone «dejar que Jev decida si escalar el ticket», está metiendo la decisión en el modelo; el SKILL.md dice claramente que ese tipo de pregunta está planteada en el nivel equivocado: pídele que la descomponga en juicios y que la corrija.

  • Las propuestas del agent tienen la forma «añadir juicios, ramificar en código», y no «dejar que Jev decida»

Paso 4: hacer que el agent ejecute experimentos baratos y proponga un plan de refactorización contrastando con el cookbook ​

Por qué: encontrar los puntos es solo el plan. El paso 3 del flujo de trabajo del skill es «probe the live API»: validar la redacción de las preguntas con solicitudes reales, hasta que el comportamiento de la aplicación cumpla lo esperado. La documentación oficial da dos prompts listos para usar.

Primero exporta la key (si no tienes, créala en console.typesafe.ai/keys):

bash
export TYPESAFE_API_KEY="<你的API Key>"

Prompt de experimentación (texto oficial original):

text
Using the TypeSafe skill, run some experiments using the TypeSafe API key that I've
exported to `TYPESAFE_API_KEY`. Propose changes based on the most promising results.

Deberías ver: el agente te pide permiso primero — SKILL.md exige que primero obtenga consentimiento, explique qué datos enviará (especialmente datos personales o privados), declare que usará tu key, y solo entonces envíe solicitudes de prueba. Las pruebas usan casos representativos + casos difíciles + casos negativos cuya respuesta es «no»; cada caso conserva el payload completo de la solicitud, y al final propone cambios basándose en el resultado más prometedor.

Luego pide al agente que busque oportunidades de refactorización comparando con el cookbook oficial (texto original oficial):

text
Using the TypeSafe skill, analyze my code and see if there are any applicable
cookbooks (https://docs.typesafe.ai/cookbooks) that show how I could
refactor my code to be less fragile or complex.

Deberías ver: el agente señala cookbooks oficiales similares a tu código — por ejemplo, extracción frágil de correo/teléfono corresponde a pre-parsed value extraction, lógica de despacho compleja corresponde a intent routing — y propone un plan de refactorización siguiendo los patrones del cookbook. La implementación completa de estos cookbooks es la práctica de escenarios de la siguiente etapa.

💡 Presupuesto de experimentación y seguridad

Palabras textuales de SKILL.md: TypeSafe es muy barato, con un pequeño presupuesto se llega muy lejos (a little can go a very long way). Dale al agente un límite de presupuesto de experimentación y confirma que su entorno de ejecución puede acceder al endpoint de la API. Al escribir código de producción, las reglas de integración del skill exigen que la key permanezca en el servidor.

  • El agente pidió mi permiso antes de enviar solicitudes y explicó qué datos enviaría

Paso 5: reúne preguntas y umbrales en un archivo y entrégalo a revisión humana ​

Por qué: el agente escribe código rápido, pero el oficial advierte «Agents aren't great at writing questions» — la redacción de preguntas, la descripción de opciones y los umbrales son las partes de la integración que más requieren supervisión humana, y también las que más se cambian al revisar. Al centralizarlas en un archivo, tu edición colaborativa con el agente tiene un punto de apoyo.

Por ejemplo, reúne las preguntas de enrutamiento de la lección de enrutamiento inteligente en questions.py (la estructura sigue la escritura de la página oficial de patrones):

python
# questions.py —— 所有问题与阈值集中在这里;改措辞、调阈值只动这个文件
from typesafe_sdk import Choice, Score

ROUTING_QUESTIONS = {
    "intent": Choice(...),      # 完整定义见「智能路由」课第 1 步
    "complexity": Score(...),
}

# 阈值也收在这里:兜底线与各动作的风险阈值分开
CONFIDENCE_FLOOR = 0.5          # 分类兜底:低于它先转人工
TRANSFER_THRESHOLD = 0.85       # 高危动作:过了它才免确认自动执行

Los cuatro principios de colaboración oficiales (agent-skill.md, «Good vibe coding principles»):

  1. Primero discute a fondo el plan con el agente — usa los prompts de ejemplo de arriba como punto de partida
  2. Antes de implementar, la persona repasa primero el plan y confirma que tiene sentido
  3. Las constantes (preguntas y umbrales) se reúnen en un solo lugar para facilitar la revisión; el agente no es bueno escribiendo preguntas, la expectativa es edición colaborativa
  4. No tomes las afirmaciones del agente como hechos — anímalo a validar sus propias hipótesis

Deberías ver: en el proyecto hay un archivo separado que contiene todas las definiciones de preguntas y constantes de umbral. El agente luego modifica la lógica de negocio sin tocarlo; al ajustar la redacción de preguntas, solo revisas el diff de ese único archivo.

  • Las preguntas y umbrales están en un archivo; reviso primero la propuesta del agente antes de dejar que actúe

Punto de control ✅ ​

  • Puedo explicar el lugar de Jev en un coding agent: no es el modelo detrás, sino el motor de decisiones dentro del código que escribe el agente
  • En Claude Code se puede invocar el skill con /typesafe:typesafe-ai; en otros agentes, mencionar "use the TypeSafe skill" surte efecto
  • He ejecutado al menos uno de los tres prompts de ejemplo oficiales: buscar puntos de integración / correr experimentos / comparar con el cookbook
  • Las preguntas y umbrales están reunidas en un archivo; al cambiar la redacción solo se toca ese
  • Cuando el agente inventa campos, sé que la primera reacción es actualizar el skill y reintentar

Aviso de errores comunes ​

❌ Instalé el skill y el agente aún no lo usa ​

Síntoma: tras instalar el plugin, el agente sigue improvisando al escribir código de Jev. Ruta de diagnóstico oficial: invocar directamente /typesafe:typesafe-ai en Claude Code; en otros agentes, mencionar "use the TypeSafe skill" en el prompt. Si aún no funciona, confirma que el agente objetivo elegido al instalar no sea el equivocado, y luego reinicia el agente.

❌ El agente inventa campos de solicitud/respuesta ​

Síntoma: aparecen en el código campos que no están en la documentación — por ejemplo, leer .confidence de una respuesta de Noul, cuando Noul solo tiene el valor noul en el rango 0–1. Diagnóstico oficial: skill desactualizado (stale skill). Actualiza según tu método de instalación y reintenta:

bash
claude plugin marketplace update typesafe-ai
claude plugin update typesafe@typesafe-ai

Luego reinicia Claude Code o ejecuta /reload-plugins. Para mayor tranquilidad puedes activar la actualización automática: /plugin → Marketplaces → typesafe-ai → Enable auto-update. Para lo instalado con skills.sh, usa npx skills update; si lo copiaste manualmente, reemplaza todo el directorio por la última versión de GitHub.

❌ Los resultados no cumplen lo esperado y sospechas primero del modelo ​

Síntoma: la clasificación o el enrutamiento empiezan a errar. El orden de diagnóstico oficial es revisar primero preguntas y umbrales: un umbral demasiado alto produce falsos negativos (lo que debía automatizarse no se automatiza), uno demasiado bajo produce falsos positivos (se aprueba lo que no tiene certeza); después, hacer las preguntas más específicas. El aviso de errores de la lección de enrutamiento inteligente lo desarrolla en detalle.

❌ Establecer umbrales de confidence por todas partes ​

Recordatorio oficial: si solo te importa elegir la mejor opción, basta con tomar directamente la respuesta con el confidence más alto; si tienes necesidades específicas de algoritmos estadísticos, deberías usar probabilities. Esto ya se desarrolló en la lección de enrutamiento inteligente, no se repite.

❌ El código TypeSafe escrito por el agente es imposible de revisar ​

Síntoma: al revisar, las definiciones de preguntas están dispersas en cinco archivos y reunir un juego de umbrales lleva mucho tiempo buscando. Recomendación oficial: lo que la persona más debe revisar es la redacción de preguntas y las constantes de umbral; reúnelas en un solo archivo de código, sin necesidad de buscar por todas partes — es exactamente lo que se hace en el paso 5.

Técnicas avanzadas (opcional) ​

Lee el propio SKILL.md. El skill es un archivo Markdown de 288 líneas (licencia MIT, github.com/typesafe-ai/skills), con cuatro bloques de contenido central: la estratificación de juicio y decisión (tabla de verdad), la «prueba humana» del diseño de states (mirando solo este state, ¿puede una persona inteligente responder rápidamente por intuición?), las reglas de redacción de preguntas (un juicio por pregunta; los nombres de opciones deben describir el contenido, porque el ID de la pregunta no se envía al modelo) y la interpretación de respuestas (confidence rara vez actúa como compuerta, umbrales de partida de Noul 0.7/0.3, mirar la distribución de Score). La mayoría de las reglas se explicaron en lecciones anteriores (Noul, Confidence); lo que queda y vale la pena leer entero es la «lista de banderas amarillas».

Usa la secuencia de diagnóstico en cinco pasos del skill para «la respuesta parece incorrecta». El orden de comprobación que da SKILL.md: ① el payload realmente enviado → ② ¿el state pasa la prueba humana? → ③ ¿hay o no una respuesta correcta entre las opciones? → ④ ¿la pregunta puede dividirse más? → ⑤ la redacción. Si tras revisar todo sigue fallando, consulta las debilidades conocidas del modelo: Jev manual de errores comunes de 1.13.

Reconoce las «banderas amarillas» (prompt gymnastics). Las banderas amarillas que lista el oficial: criteria fijados a la medida de un caso de prueba concreto, añadir una cláusula por cada caso que falla, caveats que justifican rarezas del modelo, umbrales ajustados a casos específicos, pruebas que afirman probabilidades exactas, código que sobrescribe respuestas en secreto. Estas tendencias de «redacción escrita para forzar un valor concreto» colapsan con entradas nuevas y con la siguiente versión del modelo; prioriza las correcciones estructurales — un mejor state, dividir en preguntas independientes o cambiar el código.

Resumen de la lección ​

✅ TypeSafe Agent Skill se instala en Claude Code con dos comandos (claude plugin marketplace add typesafe-ai/skills → claude plugin install typesafe@typesafe-ai); en otros agentes, un solo npx skills add; elige solo un método para evitar copias duplicadas.

✅ Jev: División del trabajo con el coding agent: el agente escribe el código, Jev hace los juicios dentro del código; no existe una configuración de model: "jev-latest" que convierta al agente en uno dirigido por Jev.

✅ Tres prompts de ejemplo oficiales: explorar el proyecto buscando puntos de integración, correr experimentos baratos con TYPESAFE_API_KEY, proponer refactorizaciones comparando con el cookbook.

✅ Principios de colaboración: revisar el plan antes de implementar; reunir preguntas y umbrales en un archivo; el agente no es bueno escribiendo preguntas, la expectativa es edición colaborativa; no tomes las afirmaciones como hechos.

✅ Diagnóstico de cinco problemas comunes: no carga → mencionarlo / verificar el objetivo / reiniciar; inventa campos → actualizar el skill; no cumple lo esperado → revisar primero umbrales y preguntas; solo elegir el mejor → no fijar umbrales; difícil de revisar → centralizar constantes.

Referencia rápida de comandos clave:

ElementoComando / ProcedimientoFuente
Claude Code Instalaciónclaude plugin marketplace add typesafe-ai/skills → claude plugin install typesafe@typesafe-aidocs/agent-skill.md
Instalación en otros agentesnpx skills add typesafe-ai/skills --skill typesafe-ai (por defecto a nivel de proyecto, -g global)Igual que arriba
Claude Code Invocación/typesafe:typesafe-ai (común a cualquier agente: mencionar "use the TypeSafe skill")Igual que arriba
Actualización del pluginclaude plugin marketplace update typesafe-ai → claude plugin update typesafe@typesafe-ai, reiniciar o /reload-pluginsIgual que arriba
Actualización de skills.shnpx skills updateIgual que arriba
Actualización automática/plugin → Marketplaces → typesafe-ai → Enable auto-updateIgual que arriba
Repositorio de skillsgithub.com/typesafe-ai/skills (MIT; 2026-11-03 verificación: SKILL.md tiene 288 líneas, idéntico palabra por palabra a la versión en línea)Captura y verificación en tiempo real

Vista previa de la próxima lección ​

Con los cuatro modos practicados, el agente también puede escribir código por ti. La próxima parada lleva todo el conjunto a un proyecto real — Escenarios prácticos: elige tu ruta, 15 casos completos derivados del cookbook oficial.

Aprenderás:

  • Elegir un caso según tu ruta: cada caso es una forma completa de «diseño de state + pregunta tipada + decisión de código»
  • Barandillas para LLM: inspección completa de seguridad de los mensajes de entrada y salida de una aplicación LLM en una sola solicitud
  • Verificación de citas, Control de pasajes RAG: cómo llevar a la práctica este tipo de tareas de nivel producción
  • Cómo se combinan en cada caso los patrones de las tres primeras lecciones
gaodong.aiAboutPrivacyContact

Independent tutorials, not affiliated with any product mentioned. Product names and trademarks belong to their owners. Check official pages for prices and policies.