DOMINICODE

Category: AI

  • Optimización de AI Workflow para Programadores: Claves y Herramientas

    Optimización de AI Workflow para Programadores: Claves y Herramientas

    ¿Tu IA te está haciendo el trabajo… o te está creando más trabajo?

    Tiempo estimado de lectura: 7 min

    • Contexto y estructura son imprescindibles: sin contexto la IA amplifica el caos.
    • Protege datos sensibles: no subas secretos; usa modelos locales y exclusiones.
    • Automatiza de forma asíncrona y con fallos en mente: sin esto la IA solo será una conversación bonita.
    • Audita más, escribe menos: la IA genera repetitivo; tú revisas seguridad, performance y casos límite.
    • Mide y observa: métricas y logs son esenciales para LLMOps.

    Introducción

    Poca gente habla de esto en serio: tener modelos potentes no es el mismo problema que tener un workflow que te sirva. Uno vende promesas; el otro te hace entregar cosas en producción sin incendios a las 3 a.m.

    Voy a ser directo. Si tu AI workflow no tiene estructura, privacidad y automatización pensando en fallos, lo único que tendrás es un asistente que copia y pega errores más rápido. Aquí tienes la guía práctica y sin postureo para preparar tu AI workflow como programador. Con herramientas, trucos y decisiones claras. Nada de listas largas de “prueba esto” que nadie usa.

    Resumen rápido (lectores con prisa)

    Qué es: Conjunto de prácticas para construir workflows de IA seguros, observables y automatizados.

    Cuándo usarlo: Al integrar modelos en pipelines de producción o cuando manejas datos sensibles.

    Por qué importa: Evita fugas de datos, reduce bugs en producción y facilita auditoría y cumplimiento.

    Cómo funciona (resumen): Documenta contexto, aísla datos sensibles, orquesta tareas asíncronas, valida salidas con JSON schema y mide métricas clave.

    Primero: tres reglas que no puedes saltarte

    Contexto. Sin contexto, la IA es ruido.

    Sin contexto, la IA no puede tomar decisiones útiles. Asegúrate de que tus prompts se alimenten de datos relevantes y estructurados.

    Seguridad. Sin filtros, la IA es fuga de datos.

    Define exclusiones y políticas de retención. Evita enviar secretos y PII a servicios externos sin controles.

    Automatización asíncrona. Sin ella, la IA es una conversación bonita y nada más.

    Automatiza en background, maneja reintentos y diseña para fallos. Una integración síncrona sin tolerancia a fallos no escala.

    Si no cumples esas tres, deja de leer y organiza tu repositorio. En serio.

    1. Ingeniería de contexto: no alimentes a la IA con basura

    Los LLMs son amnésicos por diseño. No “saben” nada hasta que se lo das. Si tu repo es un caos, la IA amplifica el caos.

    Qué hacer:

    • Documenta. ARCHITECTURE.md en la raíz. Puntos rápidos: responsabilidades de cada módulo, decisiones de diseño, contratos de API.
    • Código legible. Nombres claros. Dos minutos que ahorres en comentarios lo recuperas en prompts más precisos.
    • Indexación controlada. Herramientas como Cursor indexan la base de código. No es opcional si quieres que la IA entienda dependencias entre archivos.

    Resultado: prompts más eficaces, menos vueltas y menos parches en producción.

    2. Aislamiento y tratamiento de datos confidenciales: protege lo que importa

    Enviar todo a la nube es fácil. También es ilegal o estúpido, según el caso.

    Medidas concretas:

    • Archivos de exclusión: .cursorignore, .copilotignore. No indexes credenciales, tests con datos reales ni directorios con PII.
    • Modelos locales para datos sensibles: Ollama o LM Studio ejecutan modelos en tu máquina. Cero fugas externas.
    • Política de retención y cifrado: define cuánto tiempo y cómo borras la memoria generada por agentes.

    Si te salta la duda: no subas datos sensibles. Punto.

    3. Cambia el rol: de escribir a auditar

    El workflow moderno invierte la proporción de tiempo. La IA genera lo repetitivo; tú compruebas. Auditar es la nueva magia.

    Haz esto:

    • Usa la IA para boilerplate, tests iniciales y esquemas.
    • Invierte tu tiempo en seguridad, performance y casos límite raros.
    • Configura revisiones automáticas que devuelvan sugerencias como comentarios en PRs (con n8n, por ejemplo).

    Herramientas que realmente usan los equipos que producen

    No quiero listas infinitas. Estas son las que funcionan en equipos medianos y grandes.

    IDEs y asistentes

    • Cursor: indexación real del repo. Útil para refactors que impliquen muchos archivos.
    • Supermaven: autocompletado ultrarrápido (latencia mínima).
    • GitHub Copilot: confianza y cumplimiento en entornos Enterprise.

    Orquestadores y workflows

    • n8n: automatización visual. Ideal para pipelines que conecten GitHub → Linter IA → Slack → PR comments. Maneja reintentos y errores sin que el dev escriba microservicios extra.
    • Alternativas: Zapier/Pipedream para casos sencillos; Airbyte para ingest de datos.

    Ejecución local y modelos privados

    • Ollama: corre modelos en localhost. Perfecto si tu cliente lo exige.
    • LM Studio: buen balance para experimentar con modelos cuantizados y exponerlos como API local.
    • Vector DBs: Pinecone, Qdrant, Weaviate si necesitas búsqueda semántica en docs internos.

    SDKs vs frameworks pesados

    • Evita LangChain/LlamaIndex cuando necesites control fino. Te ayudan a prototipar, pero esconden la lógica real.
    • Usa SDKs oficiales (OpenAI/Anthropic) + orquestador visual: control, visibilidad y debugging más sencillo.

    Patrones prácticos: cómo montar pipelines que no te rompan

    A continuación, flujos que puedes implementar en cuestión de días.

    Pipeline: revisión automática de PR con IA (n8n)

    1. Webhook en GitHub al abrir PR.
    2. n8n descarga diff y lo manda a un modelo local o API con prompt que busca issues de seguridad / antipatrón.
    3. Resultados validados (JSON schema) → comentarios automáticos en PR + reporte en Slack.
    4. Si la IA sugiere algo crítico, crea un ticket en JIRA y asigna prioridad.

    Beneficio: feedback inmediato sin humanos en la primera línea.

    Pipeline RAG para documentación interna

    1. Indexa docs técnicas en vector DB (Pinecone/Qdrant).
    2. Usa un extractor barato (GPT-4o-mini / Claude 3 Haiku) para generar metadatos y facts.
    3. Cuando el asistente responde, inyecta top-K facts relevantes en el prompt.
    4. Mantén extractor asíncrono con reconciliación por versión para evitar race conditions.

    Diseño de memoria y extracción: regla simple

    • Extrae hechos en background (asíncrono).
    • Para acciones críticas (pagos, cambios legales), ejecuta extracción síncrona o pide confirmación explícita.
    • Versiona la memoria (version_id) y aplica locks optimistas.

    Errores que te costarán tiempo y reputación

    • Enviar secrets a modelos en la nube. Sí, gente lo hace. No seas esa gente.
    • Depender de selectores CSS o clases de librería en tests generados por IA. Rompen fácil. Usa data-testid.
    • Confiar en la IA para lógica crítica sin validación humana estricta. La probabilidad no es garantía.

    Observabilidad y LLMOps: lo que medir y por qué importa

    No puedes mejorar lo que no mides. Las métricas importan.

    Métricas claves:

    • TTFT (Time to First Token).
    • Tiempo de extracción de memoria.
    • Tasa de fallos de parsing JSON del extractor.
    • Conflictos por versiones aplicadas a la memoria.
    • Porcentaje de sugerencias de IA aceptadas por humanos.

    Logs:

    Guarda inputs y outputs del extractor, pero anonimiza PII. Necesitarás trazabilidad si algo sale mal.

    Checklist para lanzar tu AI workflow hoy (marca y haz)

    • [ ] ARCHITECTURE.md en la raíz del repo.
    • [ ] .cursorignore / .copilotignore configurados.
    • [ ] Pipeline básico en n8n para PR review.
    • [ ] Modelo local para datos sensibles (Ollama / LM Studio).
    • [ ] Extractor forzado a JSON + validación con Zod/JSON Schema.
    • [ ] Versionado de memoria y locks optimistas.
    • [ ] Logs estructurados y dashboard de métricas.
    • [ ] Pruebas E2E que incluyan casos de race conditions.

    Plan de 30 días (qué tocar cada semana)

    Semana 1

    Limpiar repo y documentar arquitectura. Configurar ignores.

    Semana 2

    Implementar n8n para PR review + tests automáticos generados por IA.

    Semana 3

    Levantar modelo local y mover procesos sensibles allí. Añadir vector DB básica.

    Semana 4

    Añadir observabilidad y medir. Ejecutar pruebas A/B con y sin memoria en producción limitada.

    Historias reales (no teoría, verdad en el barro)

    Laura, frontend

    Usaba la IA para PRs. Al principio aceptaba todo. Rompió producción en staging. Aprendió a auditar, ahora automatiza el 60% del boilerplate y solo revisa arquitectura.

    Marco, mobile

    Migró a modelos locales para PII y ganó la confianza de compliance. El equipo redujo tiempos de revisión y ganó contrato público.

    Carla, PM

    Quería “más features” sin pensar en deuda. Les explicó la regla: si no hay métricas detrás, no se lanza. El equipo ahora prioriza correctamente.

    Metáfora que recuerda todo esto

    La IA es un taladro potente. Si no pones la broca correcta y no aseguras la pared, perforas donde no debes. Aprende a elegir la broca y pon un protector antes de empezar.

    Cierre con decisión y CTA fuerte

    ¿Quieres el plan y la plantilla listos para pegar en tu repo?

    Responde “QUIERO AI-WORKFLOW” y te mando:

    • Checklist descargable.
    • Prompt extractor listo para usar.
    • Un flujo n8n para revisión de PRs que puedes clonar y ejecutar en 20 minutos.

    Esto no acaba aquí. La IA no es una moda: es infraestructura. Si no defines tu workflow hoy, tu competencia lo hará mañana. ¿Vas a quedarte viendo cómo lo hacen otros o quieres montar algo que funcione de verdad?

    Para recursos y experimentos que complementan estas prácticas visita Dominicode Labs. Es un buen punto de partida si quieres plantillas y flujos listos para adaptar.

    FAQ

    ¿Cuáles son las tres reglas imprescindibles?

    Contexto, Seguridad y Automatización asíncrona. Sin esos tres pilares tu workflow será propenso a errores, fugas de datos y no escalará.

    ¿Cómo evito filtrar datos sensibles a modelos en la nube?

    Configura archivos de exclusión (.cursorignore, .copilotignore), usa modelos locales (Ollama/LM Studio) para datos sensibles y aplica políticas de retención y cifrado.

    ¿Qué herramientas conviene priorizar para empezar?

    Para equipos medianos: Cursor para indexación, n8n para orquestación, y un vector DB básico (Pinecone/Qdrant). Complementa con modelos locales si manejas PII.

    ¿Por qué evitar LangChain/LlamaIndex en producción?

    Porque abstraen lógica crítica y pueden esconder fallos. Para control fino es mejor usar SDKs oficiales y un orquestador visual que te permita debugear y auditar.

    ¿Qué métricas debo medir primero?

    TTFT, tiempo de extracción de memoria, tasa de fallos de parsing JSON, conflictos de versiones en memoria y porcentaje de sugerencias aceptadas por humanos.

    ¿Cómo implementar un pipeline básico de revisión de PRs?

    Configura un webhook en GitHub, usa n8n para descargar el diff y llamar a un modelo (local o API), valida la respuesta con JSON schema y publica comentarios en el PR. Para sugerencias críticas crea tickets automáticos en JIRA.

  • Implementando Gemini Embedding 2 para optimizar pipelines multimodales

    Implementando Gemini Embedding 2 para optimizar pipelines multimodales

    Gemini Embedding 2: Nuestro primer modelo de incrustación multimodal nativo

    Tiempo estimado de lectura: 4 min

    • Un modelo multimodal nativo: texto, imagen y audio se representan en el mismo espacio semántico.
    • Simplifica pipelines: ingesta directa → vector multimodal → almacenamiento y búsqueda.
    • Impacto operativo: menor latencia, menos puntos de fallo y menos pérdida semántica frente a convertir todo a texto.
    • Consideraciones: coste computacional, chunking multimodal y balance calidad/coste.

    Introducción

    Gemini Embedding 2: Nuestro primer modelo de incrustación multimodal nativo aparece como un cambio arquitectónico claro: dejar de traducir imágenes, audio o video a texto para poder indexarlos. En las primeras líneas: este modelo convierte múltiples modalidades en vectores que coexisten en el mismo espacio semántico, y eso reconfigura cómo diseñamos RAG, agentes y pipelines de búsqueda. Fuente: https://blog.google/innovation-and-ai/models-and-research/gemini-models/gemini-embedding-2/

    Resumen rápido (lectores con prisa)

    Qué es: Un modelo de embeddings multimodales que representa texto, imagen y audio en un espacio latente compartido.

    Cuándo usarlo: Cuando las señales visuales o auditivas añaden valor a la búsqueda o memoria de agentes (diagramas, capturas, clips de vídeo, audio significativo).

    Por qué importa: Reduce pasos intermedios (OCR/descripción), latencia operacional y pérdida semántica al indexar multimodal directamente.

    Cómo funciona (alto nivel): Ingesta → vectorización multimodal → almacenamiento en DB vectorial → recuperación por similitud → LLM para RAG.

    Qué cambia en la práctica

    Antes: pipeline fragmentado. OCR → visión → descripción → vectorización. Ahora: ingesta directa. Esa diferencia reduce latencia operacional, puntos de fallo y, sobre todo, la pérdida semántica que ocurre al comprimir una imagen en texto.

    Implicaciones para un equipo técnico

    • Indexas diagramas, capturas de pantalla y clips de vídeo sin pasos intermedios.
    • Una misma consulta textual puede recuperar imágenes o fragmentos de audio porque sus vectores están alineados.
    • Los agentes con memoria dejan de depender exclusivamente del texto; pueden “recordar” por contenido visual o auditivo.

    No es magia. Es una abstracción más correcta: representa texto, imagen y audio en un solo espacio latente, simplificando las búsquedas semánticas y las respuestas de agentes.

    Arquitectura práctica: cómo integrarlo en un RAG moderno

    1. Ingesta

    Webhook recibe PDF, JPG o MP4.

    2. Enriquecimiento

    Opcional extracción de metadatos (autor, timestamp, página).

    3. Vectorización

    Llamada a Gemini Embedding 2 → vector multimodal.

    4. Almacenamiento

    Persistir vector + metadata en Qdrant/Pinecone/Weaviate.

    5. Recuperación

    Búsqueda por similitud y pase a un LLM para respuesta contextual (RAG).

    Consejo operativo: no trates cada frame de un vídeo como un vector único por defecto. Segmenta por escenas relevantes (detección de cambios de escena, keyframes, o subclips con audio significativo). El chunking multimodal es ahora la decisión de diseño central: afecta coste, latencia y calidad de recuperación.

    Ejemplo concreto con n8n + vector DB

    • Nodo HTTP recibe un ZIP de imágenes y un PDF.
    • Nodo Function extrae imágenes y páginas (si aplica).
    • Nodo HTTP (Gemini Embedding 2) vectoriza cada elemento y devuelve vectores con IDs.
    • Nodo DB inserta vectores en Qdrant con metadata {source, page, bbox, timestamp}.
    • Trigger de búsqueda: usuario pregunta en Slack; n8n consulta Qdrant por similitud y devuelve imágenes + extracto de texto al LLM que redondea la respuesta.

    Esto convierte un flujo de soporte técnico en algo utilizable: la captura de pantalla de un error devuelve soluciones anteriores sin depender de la calidad de la descripción humana.

    Costes, latencia y trade-offs reales

    Adoptar embeddings multimodales implica decisiones reales:

    Coste de cómputo

    Vectorizar video o largos audios consume más CPU/GPU. Para workloads síncronos, considera preprocesado asíncrono y cachés.

    Almacenamiento

    Vectores multimodales pueden requerir mayor dimensionalidad; esto aumenta coste por vector en DBs vectoriales. Usa reducción dimensional o compresión cuando tengas muchos vectores similares.

    Latencia

    En experiencias conversacionales en tiempo real, el procesamiento directo de vídeo puede ser demasiado lento. Fragmenta, pre-indexa o procesa en batch donde sea posible.

    Calidad vs. coste

    No siempre necesitas representación multimodal completa. Si tus consultas son casi siempre textuales, un pipeline texto-first sigue siendo válido.

    Estrategia de adopción — dónde empezar hoy

    1. Identifica contenido con valor visual real: manuales con diagramas, reportes con gráficos, repositorios con screenshots de errores.
    2. Prototipa un RAG limitado: 1k documentos multimodales, vectorízalos y corre consultas reales. Mide recuperación y coste.
    3. Ajusta chunking y dimensionalidad: balancea precisión vs. coste operativo.
    4. Expande gradualmente: añade vídeo/audio solo cuando el ROI de búsqueda visual/audio exista (p. ej., soporte de vídeo de producto, formación interna).

    Conclusión técnica y criterio

    Gemini Embedding 2 no es solo una mejora de rendimiento: cambia la unidad de abstracción con la que trabajamos. En lugar de forzar todo a texto, tratamos documentos como objetos multimodales nativos. Para equipos de automatización y arquitectos técnicos, la pregunta no es si usarlo, sino cómo incorporarlo sin disparar costes ni latencias.

    Empieza por validar con casos donde la señal visual o auditiva aporte claramente al resultado (resolución de errores, extracción de métricas de gráficos, búsqueda en tutoriales en video). Optimiza chunking y dimensionalidad antes de vectorizar todo tu repositorio. Así conviertes una promesa técnica en valor real, medible y reproducible para tu producto o tu operación interna.

    Para equipos interesados en prototipado y automatización aplicada, Dominicode Labs ofrece recursos y plantillas para integrar pipelines multimodales con herramientas como n8n y bases de datos vectoriales. Considera usar esos recursos como punto de partida para pruebas de concepto rápidas y controladas.

    FAQ

    ¿Qué distingue a Gemini Embedding 2 de embeddings solo textuales?

    Gemini Embedding 2 representa texto, imagen y audio en el mismo espacio semántico, permitiendo recuperar elementos multimodales con consultas textuales sin convertir previamente imágenes o audio a texto.

    ¿Cuándo merece la pena vectorizar vídeo o audio?

    Cuando la señal visual o auditiva aporta valor a las búsquedas o memoria (p. ej., tutoriales en video, soporte con capturas de pantalla, registros de audio con información útil). Si las consultas son casi siempre textuales, puede no ser necesario.

    ¿Cómo afecta esto al diseño de RAG y agentes?

    Permite que agentes y RAG recuperen y utilicen contenido no textual directamente, reduciendo pasos intermedios y pérdida semántica, y permitiendo memorias basadas en señales visuales y auditivas.

    ¿Qué bases de datos vectoriales son compatibles?

    Bases de datos como Qdrant, Pinecone y Weaviate son mencionadas como destinos para persistir vectores multimodales.

    ¿Cómo optimizo coste y latencia?

    Usa preprocesado asíncrono, cachés, reducción dimensional o compresión de vectores, y procesa vídeo/audio en batch o pre-indexado en lugar de en tiempo real cuando la interacción lo permite.

    ¿Qué es el chunking multimodal y por qué importa?

    Es la decisión de cómo segmentar contenido multimodal (frames, escenas, subclips, páginas). Afecta coste, latencia y calidad de recuperación; un mal chunking puede inflar costos o degradar resultados.

  • Mejores Prácticas para Crear Habilidades de Agentes Efectivas

    Mejores Prácticas para Crear Habilidades de Agentes Efectivas

    Best Practices for Creating Agent Skills

    Tiempo estimado de lectura: 6 min

    Ideas clave

    • Diseñar skills con frontmatter preciso y estructura mínima para que los agentes los carguen correctamente.
    • Escribir instrucciones procedimentales orientadas a máquinas, usando Progressive Disclosure para ahorrar tokens.
    • Empaquetar scripts deterministas para operaciones repetitivas y definir stdout/stderr como contrato para decisiones automáticas.
    • Validar skills con fases: Discovery, Logic y Edge-case testing usando LLMs.
    • Documentar fallbacks y thresholds en referencias; tratar skills como componentes versionados e inspeccionables.

    Best Practices for Creating Agent Skills: si quieres que un agente no solo arranque, sino que sobreviva en producción, necesitas más que buenos prompts. Necesitas arquitectura, disciplina y pruebas diseñadas para máquinas. Este artículo explica, con ejemplos prácticos y referencias, cómo construir skills que los LLMs realmente puedan usar.

    Resumen rápido (lectores con prisa)

    Definir frontmatter preciso, escribir pasos procedimentales en tercera persona imperativa, mover reglas densas a references/ y proveer scripts deterministas. Validar con tres fases (Discovery, Logic, Edge-case) y usar stdout/stderr como contrato para decisiones automáticas.

    Best Practices for Creating Agent Skills: estructura, metadatos y responsabilidades claras

    Los agentes ven un skill antes que nada por su frontmatter. Si ese nombre o descripción no son precisos, el agente nunca cargará tu skill. Sigue estas reglas prácticas:

    • Estructura mínima obligatoria:
    skill-name/
├── SKILL.md              # Metadatos + instrucciones core (<500 líneas)
├── scripts/              # CLIs pequeños para tareas deterministas
├── references/           # Reglas densas, esquemas, decision-trees
└── assets/               # Plantillas y JSON schemas
    • Frontmatter: nombre exacto del skill = nombre del directorio; 1–64 caracteres, minúsculas, números y guiones.
    • Descripción: 1.024 caracteres máx.; redactar en tercera persona; incluir negative triggers (qué NO debe hacer el skill).

    Referencia: agentes basados en metadatos (ej.: agentskills.io).

    Escribe para máquinas: instrucciones procedimentales y JiT loading

    Los LLMs funcionan por patrones. Tu SKILL.md no es un manual; es el orquestador.

    • SKILL.md: pasos cronológicos en tercera persona imperativa. Ejemplo:
      1. “Validate environment: run scripts/check-node-env.js.”
      2. “If fails, abort with message from stderr and surface actionable advice.”
    • No copies masivas de config. Usa Progressive Disclosure: mueve plantillas y reglas densas a assets/ y references/ y obliga al agente a leerlas solo cuando las necesite.
    • Rutas siempre con forward slashes (/).

    Beneficio: menor consumo de tokens, decisiones más precisas.

    Bundle deterministic scripts for repetitive operations

    No pidas al modelo que genere parseadores complejos cada ejecución. Provee scripts probados:

    • scripts/detect-commonjs.mjs — detecta módulos CommonJS problemáticos (puede usar madge: Madge).
    • scripts/env-validator.mjs — valida versión de Node, gestor de paquetes y permisos.
    • scripts/transform-schema.py — transforma esquemas con reglas inmutables.

    Diseña los scripts para devolver errores humanos y machine-actionable por stderr/stdout. Ejemplo de stderr útil:

    CRITICAL: package.json lacks 'build' script. Recommend: run `npx ng update @angular/cli` then retry.

    Referencias técnicas: Vite, esbuild, Node.js.

    Progressive Disclosure: cuándo cargar qué

    Patrón:

    • SKILL.md indica: “Si detectas X, leer references/X.md”.
    • Agent only loads references/X.md when X aparece en el repo.

    Ejemplo aplicado a migración Angular→Vite:

    • No leer webpack-fallbacks.md salvo que angular.json contenga @angular-builders/custom-webpack.

    Resultado: contexto limpio hasta el momento de la decisión.

    Validación con LLMs: Discovery, Logic y Edge-case testing

    Prueba tus skills con otros agentes siguiendo tres fases:

    1. Discovery Validation
      • Pega solo el frontmatter en un LLM y pregúntale qué prompts deberían y no deberían activar la skill. Ajusta description hasta que el modelo sea inequívoco.
    2. Logic Validation
      • Da al LLM SKILL.md + tree de archivos. Pídele simular ejecución paso a paso con monólogo interno: “¿Qué archivo leo? ¿Qué script ejecuto? ¿Dónde me obligaron a adivinar?”
      • Marca las líneas donde el agente tuvo que suponer datos.
    3. Edge Case Testing
      • Pide al LLM que actúe como QA hostil y genere 3–5 preguntas que rompan la skill (p. ej. Node version < 18, custom webpack builders, imports dinámicos CommonJS).

    Sugerencia de benchmark: SkillsBench para inspiración de evals (busca repositorios o frameworks de evaluación de skills).

    Manejo de errores y criterios de fallback

    • Stdout/stderr como contrato: script devuelve JSON estructurado para éxito o mensajes humanos para fallos.
    • Define thresholds decisionales: p. ej., si detectas >3 dependencias CommonJS problemáticas, abortar migración automática y sugerir fallback híbrido.
    • Documenta fallbacks en references/, no en SKILL.md.

    Ejemplo rápido de decisión (pseudocódigo)

    1. Run scripts/env-validator.mjs
2. If exit code ≠ 0 -> return error to user with remediation steps
3. Run scripts/detect-legacy-deps.mjs
4. If legacyDeps.count > 3 -> consult references/commonjs-guide.md and recommend hybrid strategy
5. Else -> read assets/vite.config.template.ts and generate vite.config.ts

    Cierre: audiencia, responsabilidad y próxima iteración

    Las Agent Skills son componentes de infraestructura: deben ser nombradas, versionadas y validadas como cualquier servicio. La disciplina (terminología única, scripts deterministas, progressive disclosure y validación con LLMs) convierte un experimento en una herramienta repetible.

    Implementa estas prácticas y reduce fallos sorpresa en entornos reales. Si quieres un checklist listo para copiar en SKILL.md o ejemplos de scripts env-validator/detect-commonjs, disponemos de plantillas y pruebas automatizadas que puedes integrar hoy.

    Fuentes y lectura adicional

    Implementa esto ahora: estructura tu skill, saca las reglas densas a references/, empaqueta los scripts y empieza las pruebas Discovery/Logic/Edge-case con un LLM. Tu próxima iteración será menos sorpresiva y mucho más confiable.

    Para continuar con herramientas y plantillas que complementan este enfoque, considera explorar Dominicode Labs como una continuación lógica de prácticas de automatización y evaluación de skills.

    FAQ

    ¿Qué debe contener la estructura mínima de un skill?

    La estructura mínima es:

    skill-name/
├── SKILL.md
├── scripts/
├── references/
└── assets/

    SKILL.md contiene metadatos e instrucciones core (<500 líneas); scripts/ almacena herramientas deterministas; references/ reglas densas; assets/ plantillas y esquemas.

    ¿Qué es Progressive Disclosure y cuándo usarlo?

    Es la práctica de mover reglas y artefactos densos a archivos que se cargan solo si son necesarios. Úsalo para reducir tokens y mantener el contexto limpio hasta el momento de la decisión.

    ¿Cómo deben devolver los scripts errores y resultados?

    Definir stdout/stderr como contrato: devolver JSON estructurado para éxitos y mensajes humanos accionables en stderr para fallos, por ejemplo:

    CRITICAL: package.json lacks 'build' script. Recommend: run `npx ng update @angular/cli` then retry.

    ¿Qué pruebas realizar con LLMs?

    Realiza tres fases: Discovery (solo frontmatter), Logic (simulación paso a paso con SKILL.md + tree) y Edge-case (QA hostil generando escenarios que rompan la skill).

    ¿Cuándo abortar una migración automática?

    Define thresholds decisionales; por ejemplo, si detectas >3 dependencias CommonJS problemáticas, aborta la migración automática y recomienda una estrategia híbrida documentada en references/.

  • Cómo optimizar Agentes y Skills en Claude Code para un mejor rendimiento

    Cómo optimizar Agentes y Skills en Claude Code para un mejor rendimiento

    entender Agentes vs Skills, en Claude code, trade-offs de los agentes, y los trade-offs de los modelos

    ¿Quieres que tu sistema con Claude deje de comportarse como un aprendiz despistado y empiece a trabajar como un equipo bien entrenado? entender Agentes vs Skills, en Claude code, trade-offs de los agentes, y los trade-offs de los modelos es el primer paso. No es filosofía; es diseño técnico que decide costes, latencia y confiabilidad.

    En una frase: una Skill es una herramienta; un Agente es quien decide cuándo y cómo usarla. En Claude Code (y en el Model Context Protocol) esa diferencia no es semántica: define el control flow, la observabilidad y la estrategia de modelo.

    Resumen rápido (lectores con prisa)

    Qué es: Skill = función stateless y determinista; Agente = sistema que orquesta Skills con loop de razonamiento.

    Cuándo usarlo: Skill para flujos deterministas; Agente para tareas multi-step y adaptativas.

    Por qué importa: determina latencia, coste, observabilidad y riesgo de loops.

    Cómo funciona (alto nivel): Agente observa, planifica, invoca Skills y verifica; Skills exponen APIs claras (MCP/HTTP).

    Tiempo estimado de lectura

    Tiempo estimado de lectura: 5 min

    Ideas clave

    • Skills son funciones deterministas y stateless; expónlas como APIs claras.
    • Agentes orquestan Skills y gestionan objetivo, memoria y reintentos.
    • Los agentes añaden latencia, coste e indeterminismo; requieren guardrails y observabilidad.
    • Elige modelo por trade-off: Haiku (rápido/barato), Sonnet (equilibrio), Opus (máxima calidad).
    • Patrón híbrido recomendado: router ligero → Skills directas → Agentes especializados → guardrails y tracing.

    Tabla de contenidos

    Introducción

    ¿Quieres que tu sistema con Claude deje de comportarse como un aprendiz despistado y empiece a trabajar como un equipo bien entrenado? entender Agentes vs Skills, en Claude code, trade-offs de los agentes, y los trade-offs de los modelos es el primer paso. No es filosofía; es diseño técnico que decide costes, latencia y confiabilidad.

    Agentes vs Skills: la distinción que evita catástrofes

    Skills = funciones puntuales, deterministas y stateless.

    Skills

    • readFile(path), runSQL(query), sendSlack(channel, text).
    • Implementadas como código tradicional (JS/Python) y expuestas al modelo con una firma clara (MCP/HTTP).
    • No razonan. Ejecutan.

    Agentes

    • Mantienen objetivo, memoria y loop de razonamiento (Observe → Plan → Act → Verify).
    • Un Agente puede invocar múltiples Skills, evaluar resultados, reintentar o escalar a humano.
    • En Claude Code, el Agente es la instancia del modelo que ejecuta el bucle y usa las Skills ofrecidas por el runtime.

    Técnicamente: Skills son APIs; Agentes son sistemas de control y decisión que consumen esas APIs.

    Por qué importa: trade-offs de los agentes

    Autonomía suena bien hasta que el Agente se vuelve caro o tóxico. Estos son los efectos prácticos que deberías medir.

    Latencia multiplicada

    Cada paso del bucle agrega llamadas al modelo y a Skills. Una tarea que toma 2s con una Skill directa puede tardar 15–30s con un Agente que valida y reintenta. Para workflows interactivos eso mata la UX.

    Riesgo de loops infinitos

    Si no limitas iteraciones o detectas patrones repetitivos, el Agente puede intentar la misma corrección 1000 veces. Resultado: facturas de API astronómicas y procesos bloqueados.

    Indeterminismo e idempotencia perdida

    Un Agente puede resolver la misma tarea de maneras distintas. Eso da flexibilidad ante casos abiertos, pero complica testing, CI/CD y auditoría. Necesitas validaciones basadas en propiedades (constraints) en lugar de resultados fijos.

    Observabilidad y debugging costosos

    Debuguear un flow agéntico exige trazas por cada llamada LLM ↔ Skill, snapshots de memoria y métricas de confianza. Sin esto, los fallos solo se detectan cuando el usuario se queja.

    Mitigaciones prácticas:

    • Limitar pasos y tiempo por tarea (timeouts cognitivos).
    • Implementar detección de retries repetidos y bloqueo.
    • Validación post-acción (tests automáticos, checksums, schema validation).
    • Escalada a humano cuando la confianza baja.

    Trade-offs de los modelos: elegir Sonnet, Haiku u Opus

    No todos los modelos sirven para todo. Aquí el criterio es coste versus capacidad de razonamiento.

    Claude 3.5 Sonnet — el equilibrio

    • Pros: razonamiento sólido, buen manejo de Tool Use y generación de código.
    • Contras: coste y latencia moderados.
    • Uso: cerebro del Agente para planificación y edición de código.

    Claude 3 Haiku — router / executor barato

    • Pros: rápido y barato.
    • Contras: menos capaz en razonamiento profundo; mayor riesgo de alucinación en tareas complejas.
    • Uso: clasificación, enrutamiento, pre-filtros, resumen rápido o conversión simple.

    Claude 3 Opus — máxima calidad (cuando el coste no importa)

    • Pros: razonamiento profundo y menor tasa de error en zero-shot.
    • Contras: latencia y coste altos.
    • Uso: análisis crítico donde la calidad es la prioridad absoluta.

    Arquitectura recomendada: híbrida. Usa Haiku como router inicial; Sonnet para agentes especializados; Opus solo en batches o tareas off-line costosas.

    Patrón de despliegue práctico (claude-code + MCP)

    1. Router (Haiku): decide si la petición necesita Skill directa o Agente Sonnet.

    2. Skill directa: ejecutar si el flujo es determinista (p. ej. ETL, queries, envíos).

    3. Agente Sonnet: para tareas multi-step (refactor, investigación, remediación).

    4. Guardrails: límites de iteración, chequeos de schema, registros de decisión.

    5. Observabilidad: tracing por etapa (LLM prompt/responses, llamadas Skill, costos).

    Para referencia del runtime y la integración con Skills revisa la documentación de Claude Code en el portal de Anthropic (y el repositorio de ejemplo).

    Criterio final para un Tech Lead

    Decide según tres preguntas:

    • ¿Es el flujo determinista? Usa una Skill.
    • ¿Requiere adaptación y varios pasos? Construye un Agente.
    • ¿Cuál es el SLA de latencia y el presupuesto de coste? Selecciona Haiku/Sonnet/Opus acorde al ROI.

    No es magia: es ingeniería de trade-offs. Un Agente bien diseñado reduce intervención humana y aumenta alcance, pero exige observabilidad, límites y selección cuidadosa de modelo. En Dominicode tratamos Agentes como infraestructura: medimos, protegemos y versionamos. Haz lo mismo y tu Claude Code dejará de improvisar y empezará a producir.

    Dominicode Labs

    Si trabajas con automatización, agentes o workflows, puedes encontrar recursos adicionales y experimentos en Dominicode Labs. Es un complemento práctico para aplicar patrones de despliegue, guardrails y observabilidad en proyectos reales.

    FAQ

    ¿Cuándo debería preferir una Skill sobre un Agente?

    Usa una Skill cuando el flujo sea determinista, idempotente y pueda representarse como una API con firma clara (por ejemplo ETL, consultas, envíos). Las Skills reducen latencia y coste y facilitan testing y CI/CD.

    ¿Cómo mitigo el riesgo de loops infinitos en un Agente?

    Implementa límites de iteración, timeouts cognitivos y detección de patrones de retry repetidos. Añade reglas que bloqueen acciones cuando se superan umbrales y escalamiento a humano cuando la confianza sea baja.

    ¿Qué observabilidad mínima necesito para un Agente en producción?

    Traza cada llamada LLM ↔ Skill, snapshots de memoria relevantes y métricas de confianza/decisión. Registra costos por etapa para analizar trade-offs de latencia y gasto.

    ¿Cómo selecciono entre Haiku, Sonnet y Opus?

    Elige según coste vs capacidad de razonamiento: Haiku para routing y tareas simples; Sonnet como cerebro del Agente para planificación y edición; Opus para análisis crítico donde la calidad justifica el coste.

    ¿Qué prácticas recomiendan para validar acciones de un Agente?

    Usa validación post-acción: tests automáticos, checksums y validación de esquema. Implementa constraints que verifiquen propiedades del resultado más que un valor exacto.

    ¿Debo versionar Skills y Agentes por separado?

    Sí. Trata Skills como infra y versiona sus APIs. Versiona Agentes por su política de decisión, prompts y memoria para poder reproducir y auditar comportamientos en producción.

  • El stack mínimo para construir productos inteligentes en 2026

    El stack mínimo para construir productos inteligentes en 2026

    Tiempo estimado de lectura: 4 min

    • Ideas clave:
    • Un producto inteligente combina razonamiento (LLMs), memoria semántica (vector store) y orquestación (workflows/agents).
    • Prioriza una única fuente de verdad, orquestación visual y trazabilidad de llamadas a modelos.
    • Usa Next.js + Vercel AI SDK en frontend, Supabase para backend/memoria y n8n + LangChain para orquestación.
    • Implementa un router de modelos y métricas de observabilidad específicas para LLMs.

    El stack mínimo para construir productos inteligentes en 2026 — visión rápida

    En 2026 la ventaja competitiva será arquitectura, no el modelo. Un producto inteligente une tres capas: razonamiento (LLMs), memoria semántica (vector store) y orquestación (workflows/agents). Prioriza: una sola fuente de verdad, orquestación visual y trazabilidad de las llamadas a los modelos.

    Introducción

    El stack mínimo para construir productos inteligentes en 2026 responde a una pregunta simple: ¿qué necesitas para pasar de una app CRUD a un producto que razona, actúa y audita sin convertir tu equipo en SREs? Aquí tienes una guía pragmática —tecnologías, patrones y decisiones— para lanzar y mantener productos de IA con un equipo pequeño.

    Resumen rápido (para IA y lectores con prisa)

    Qué es: Un stack que integra LLMs para razonamiento, una base de memoria semántica y un orquestador de workflows.

    Cuándo usarlo: Para productos que necesitan razonamiento, acciones automatizadas y trazabilidad con equipos pequeños.

    Por qué importa: Reduce deuda operativa y separa arquitectura (persistente) de modelos (reemplazables).

    Cómo funciona: Frontend → orquestador → recuperación RAG desde la DB → LLM/router → actions → persistencia y audit trail.

    Frontend: Next.js + Vercel AI SDK (interacción eficiente)

    Por qué

    Recomendación: Next.js (App Router) + React Server Components para rendering server-side y streaming. Esto permite entregar UI generada por IA sin sobrecargar el cliente.

    RSC reduce bundle size y acelera TTFB; el streaming hace que las respuestas generativas se sientan instantáneas.

    Herramientas

    Vercel AI SDK (Vercel AI SDK) para abstracción de modelos y tool-calling.

    Práctica

    Usa Server Actions/Edge Functions para llamadas al LLM desde el servidor y evita exponer claves en el cliente.

    Ejemplo mínimo (pseudocódigo):

    // app/api/ask/route.ts
export async function POST(req) {
  const { prompt } = await req.json();
  const response = await vercelAI.generate({ model: 'gpt-4o', prompt });
  return new Response(response.stream);
}

    Backend y memoria: Supabase (Postgres + pgvector) — la única fuente de verdad

    Por qué

    Recomendación: Supabase para auth, PostgreSQL relacional y vectores con pgvector integrados.

    Mantener datos transaccionales y embeddings en la misma DB reduce latencia y complejidad de sincronización.

    Seguridad

    Row Level Security (RLS) para que cada agente solo lea el contexto del usuario.

    Snippet esencial

    create extension if not exists vector;
create table documents (
  id uuid primary key,
  content text,
  embedding vector(1536),
  user_id uuid references auth.users(id)
);
create policy "user_docs" on documents for select using (auth.uid() = user_id);

    Práctica operativa: indexa embeddings en ingest y almacena metadata para filtros semánticos + estructurales. Mide latencia RAG target <100ms.

    Referencia: guía de Supabase sobre vectores Supabase Vector Guide

    Orquestación y agentes: n8n (self-hosted) + LangChain (lógica)

    Recomendación: orquesta agentes con n8n y codifica patrones complejos con LangChain/LangGraph.

    Separar flujo (n8n) de razonamiento (LangChain) permite iterar sin redeploys masivos.

    Patrón: Frontend → webhook n8n → recuperación RAG (Supabase) → LLM (router) → actions (APIs, DB) → update (Supabase) → frontend via Realtime.

    Nodos imprescindibles: webhook, HTTP request, execute JS, wait for approval (human-in-loop), webhook response.

    Ejemplo de flujo:

    • Request del usuario llega a n8n.
    • n8n ejecuta búsqueda semántica en Supabase.
    • Llama al LLM con prompt estructurado (schema + ejemplos).
    • Si la acción es pública, pausa y envía draft a Slack para aprobación.

    Docs n8n: n8n AI Features

    Modelos: router agnóstico y fallback local

    Recomendación: no te cases con un modelo. Implementa un router que seleccione modelo según latencia/costo/privacidad.

    Estrategia: razonamiento crítico → modelo A (Claude/Anthropic), generación de texto económico → modelo B (GPT-mini), fallback privado → Llama/Meta local.

    Implementación: una capa que decide provider por task_type, cost_budget y data_sensitivity.

    Pseudocódigo:

    const model = chooseModel({ task: 'reasoning', privacy: 'high' }); // e.g. Anthropic
const result = await model.call(prompt);

    Pagos y monetización: Lemon Squeezy vs Stripe

    Lemon Squeezy si quieres evitar la trampa fiscal internacional (Merchant of Record).

    Stripe si necesitas facturación por uso (metered billing) y control granular B2B.

    Patrón: webhook de pago → n8n → update user.plan en Supabase → activar feature flags.

    Observabilidad: PostHog + LangSmith (producto + LLM tracing)

    Recomendación: dos capas de observabilidad.

    • PostHog para funnels, retención y session replay.
    • LangSmith (o Arize) para trazas de prompts: coste, latencia, tasa de hallucination y prompts exactos. Sin trazabilidad LLM estás adivinando por qué falla el producto.

    Métricas clave: RAG latency, parse_success_rate (JSON mode), token cost per active user, time-to-approve (human-in-loop).

    Decisiones prácticas y trade-offs

    • Empieza con Supabase; migra a Pinecone/Weaviate sólo si superas límites operativos.
    • Self-host n8n si manejas datos sensibles; usa SaaS para velocidad de prototipo.
    • Mantén temperature=0 en producción para tareas deterministas (parsing, clasificación).

    Conclusión

    El stack mínimo para construir productos inteligentes en 2026 integra Next.js, Supabase y un orquestador como n8n con un router de modelos. No es glamouroso, es eficaz: reduce la deuda operativa y te permite iterar rápido en capacidades de IA útiles. Construye primero la memoria y la orquestación; los modelos son reemplazables, la arquitectura no.

    Recursos

    Para quienes trabajan en automatización, agentes y workflows, puede ser útil explorar herramientas y experimentos adicionales en Dominicode Labs. Esta referencia funciona como una continuación práctica para validar patrones de orquestación y trazabilidad en productos inteligentes.

    FAQ

    Respuesta: ¿Por qué usar Supabase en lugar de un vector store separado?

    Mantener datos transaccionales y embeddings en la misma base de datos reduce latencia y complejidad de sincronización. Supabase ofrece auth integrada y RLS, lo que simplifica seguridad y control de acceso.

    Respuesta: ¿Cuándo self-hostear n8n vs usar la versión SaaS?

    Self-host si manejas datos sensibles o requisitos regulatorios; SaaS si necesitas velocidad de prototipado y menor overhead operativo.

    Respuesta: ¿Cómo implementar trazabilidad de prompts?

    Registra prompts, respuestas, tokens y metadatos en una capa de tracing (ej. LangSmith). Correlaciona con eventos de producto (PostHog) para diagnosticar errores y medir hallucination rate.

    Respuesta: ¿Qué criterios debe usar el router de modelos?

    Decide por task_type, cost_budget y data_sensitivity. Prioriza latencia y privacidad para tareas críticas, economía para generación masiva y fallback local cuando la sensibilidad lo requiera.

    Respuesta: ¿Cuál es la práctica recomendada para production temperature?

    Mantén temperature=0 para tareas deterministas (parsing, clasificación). Ajusta solo cuando necesitas creatividad en generación y puedes auditar resultados.

    Respuesta: ¿Cómo medir la latencia objetivo de RAG?

    Mide desde la petición inicial hasta la respuesta final del LLM incluyendo la búsqueda semántica; el objetivo operativo recomendado en el artículo es <100ms para la etapa RAG (recuperación e indexado de embeddings).

  • Cómo crear un plugin para Anthropic Claude usando MCP

    Cómo crear un plugin para Anthropic Claude usando MCP

    Crear tu primer plugin para Anthropic Claude (Claude Code)

    Crear tu primer plugin para Anthropic Claude (Claude Code) no es magia. Es arquitectura. En vez de «pegar texto en el prompt», vas a exponer funciones ejecutables que Claude puede invocar como herramientas reales. Aquí tienes una guía práctica, técnica y directa para hacerlo funcionar en minutos.

    Tiempo estimado de lectura: 5 min

    • Convierte prompts en herramientas: expón funciones (tools) que Claude invoca mediante MCP en lugar de meter contexto en el prompt.
    • Implementa un servidor MCP: el servidor genera schemas automáticamente y maneja llamadas desde Claude (ej.: FastMCP en Python).
    • Seguridad y fiabilidad: docstrings claros, timeouts, manejo de errores y principio de menor privilegio son imprescindibles.
    • Observabilidad y versionado: registra llamadas, latencias y versiona schemas para evitar rupturas en producción.
    • Integración: estas tools pueden orquestarse en n8n u otros workflows como nodos reutilizables.

    Introducción

    Un “plugin” en Claude es, en realidad, Tool Use o Function Calling via Model Context Protocol (MCP). No le estás metiendo código al modelo: le das una API estructurada y el modelo decide cuándo llamarla. Tu servidor ejecuta la lógica real (Python/TS/Go) y el modelo actúa como cliente que conoce las herramientas disponibles mediante un schema.

    Resumen rápido (lectores con prisa)

    Qué es: Exponer funciones ejecutables (tools) que Claude puede invocar vía MCP.

    Cuándo usarlo: Cuando necesites que el asistente consulte sistemas externos, ejecute acciones o maneje datos sin inflar el prompt.

    Por qué importa: Permite acciones deterministas, auditables y seguras desde un asistente LLM.

    Cómo funciona: El modelo selecciona una tool, genera parámetros según el schema y llama al servidor MCP; el servidor responde con texto estructurado.

    ¿Qué es un “plugin” en Claude?

    Conceptualmente:

    • Claude = cliente que conoce las herramientas disponibles mediante un schema.
    • MCP = protocolo que negocia llamadas entre Claude y tu servicio (stdio, HTTP, WebSocket).
    • Tu servidor = el plugin: código real que ejecuta la lógica (Python/TS/Go).

    No le estás metiendo código al modelo. Le das una API estructurada y el modelo decide cuándo llamarla.

    ¿Qué necesitas y por qué importa?

    ¿Por qué hacerlo? Porque así conviertes un asistente en un agente capaz de:

    • consultar bases de datos internas,
    • ejecutar comprobaciones de infra,
    • automatizar workflows en n8n,

    sin inundar el prompt con contexto ni exponer credenciales en texto.

    Requisitos mínimos:

    Código mínimo: servidor MCP en Python

    Este ejemplo expone una tool que verifica el estado HTTP de una URL usando FastMCP. Copia, ajusta y ejecuta.

    from mcp.server.fastmcp import FastMCP
import httpx

mcp = FastMCP("WebChecker")

@mcp.tool()
async def check_website_status(url: str) -> str:
    """
    Verifica el estado HTTP de una URL.
    Args:
      url: URL completa (ej: https://dominicode.com)
    Returns:
      Mensaje con código y razón, o error legible.
    """
    try:
        async with httpx.AsyncClient(timeout=5.0) as client:
            r = await client.get(url, follow_redirects=True)
            return f"Status: {r.status_code} - {r.reason_phrase}"
    except Exception as e:
        return f"Error: {str(e)}"

if __name__ == "__main__":
    mcp.run()

    FastMCP genera automáticamente el schema de la tool a partir de los type hints y docstrings. No escribes JSON a mano.

    Registrar el plugin en Claude Desktop / CLI

    Para que Claude vea tu servidor local, añade una entrada en la configuración de Claude Desktop:

    – macOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json
    – Windows: %APPDATA%\Claude\claude_desktop_config.json

    Ejemplo:

    {
  "mcpServers": {
    "web-checker": {
      "command": "python",
      "args": ["/ruta/absoluta/a/server.py"]
    }
  }
}

    Reinicia Claude. Deberías ver el servidor activo (icono de enchufe).

    Flujo de ejecución (Thinking Loop)

    Cuando pides: “Claude, comprueba si dominicode.com responde”, sucede:

    1. Claude detecta necesidad de herramienta.
    2. Selecciona check_website_status.
    3. Genera parámetros (url).
    4. Llama al plugin vía MCP.
    5. El plugin responde con texto estructurado.
    6. Claude formatea la respuesta humana.

    Todo ordenado, trazable y auditable.

    Buenas prácticas imprescindibles

    Docstrings son contratos

    Escribe docstrings claros. El modelo usa esa información para construir la llamada. Ambigüedad = invocación errónea.

    Errores controlados

    Nunca dejes que tu plugin haga crash. Captura excepciones y devuelve mensajes legibles. Si tu proceso muere, Claude pierde acceso a todo ese servidor.

    Timeouts defensivos

    Usa timeouts explícitos (ej. httpx timeout=5s). No querrás procesos colgados.

    Principio de menor privilegio

    No implementes tools como exec_shell(cmd) a la ligera. Restringe rutas, usuarios y operaciones. Si necesitas ejecutar comandos, envuelve y valida cada input.

    Observabilidad

    Loguea prompts recibidos, respuestas, latencias y costes. Traza cada call LLM ↔ tool. Para infra, añade métricas que permitan alertas (ERRORES, RETRIES, LATENCIA).

    Gestión de versiones

    Versiona schemas y tools. Cambiar la firma de una función sin versionado rompe agentes y workflows en producción.

    Escalada humana

    Si el agente entra en loop o baja de confianza, define una regla clara: cortar, crear ticket y notificar a un responsable.

    Integración con workflows y n8n

    Estas tools son bloques reutilizables. Úsalas como nodos en n8n o como pasos en un orquestador de agentes. Por ejemplo:

    • Nodo n8n invoca tu API plugin para obtener estado.
    • Resultado condicional dispara un PR automático o un Slack alert.

    Recursos y lectura adicional

    Cierre operativo

    Crear un plugin para Claude Code es convertir una idea en una API que el modelo puede invocar de forma determinista. No es magia; es ingeniería de interfaces. Empieza con una tool pequeña, aplícala en un workflow y añade observabilidad. Si lo haces bien, tu Claude dejará de hablar y empezará a actuar.

    Esto no acaba aquí: construye la siguiente tool, versiona el schema y orquesta esas tools con un agente. Tu siguiente despliegue será la prueba.

    Dominicode Labs

    Si quieres prototipar y validar pipelines de agentes y automatizaciones, revisa Dominicode Labs. Es una continuación natural para integrar tools, pruebas y orquestación en entornos de trabajo técnico.

    FAQ

    ¿Qué diferencia hay entre un plugin y poner contexto en el prompt?

    Un plugin expone funciones ejecutables con schemas; el modelo invoca esas funciones. Poner contexto en el prompt implica enviar datos y lógica de forma textual, sin capacidad de ejecución externa ni trazabilidad.

    ¿Qué es MCP?

    MCP (Model Context Protocol) es el protocolo que negocia llamadas entre el modelo y tu servicio (stdio, HTTP, WebSocket), permitiendo que el modelo conozca y llame herramientas.

    ¿Por qué usar docstrings en lugar de JSON manual?

    Frameworks como FastMCP generan schemas automáticamente a partir de type hints y docstrings, reduciendo errores y manteniendo documentación y contratos sincronizados.

    ¿Cómo manejo errores para que Claude no pierda acceso?

    Captura excepciones, devuelve mensajes legibles y usa timeouts defensivos. No permitas que el proceso principal haga crash; implementa reinicios supervisados y health checks.

    ¿Qué precauciones de seguridad debo tomar?

    Aplica principio de menor privilegio, valida y sanitiza inputs, restringe rutas y comandos, y evita exponer credenciales en texto plano.

    ¿Puedo integrar estas tools en n8n?

    Sí. Usa las tools como nodos o llamadas API desde n8n; el resultado puede condicionar flujos, crear PRs o enviar alertas en Slack.

  • Cómo medir LLM Evals y Observabilidad en Producción

    Cómo medir LLM Evals y Observabilidad en Producción

    LLM Evals, Alignment y Observabilidad en Producción

    Tiempo estimado de lectura: 3 min

    • Ideas clave:
    • Las métricas operativas (Accuracy, Hallucination Rate, Latency, Cost per Task, Consistencia) son indispensables para pasar de prototipo a servicio escalable.
    • Construye un Golden Dataset, valida outputs estructurados y usa un modelo juez para tareas generativas.
    • Observabilidad en vivo (tracing, sampling, alertas) y guardrails de salida son necesarios para seguridad y estabilidad.

    Cómo medir si tu sistema AI realmente funciona en producción empieza por entender que “parece que responde bien” no es una métrica. LLM Evals, Alignment y Observabilidad en Producción son las piezas que convierten un prototipo bonito en infraestructura operable: Accuracy, Goal Completion, Toxicity, Hallucination Rate, Latency, Cost per Task y Consistencia. Si no mides esto, no escalas —solo maquillas el riesgo.

    Resumen rápido (lectores con prisa)

    LLM Evals: pruebas con un Golden Dataset y un modelo juez para medir factualidad y cumplimiento de objetivos. Observabilidad: tracing, sampling y alertas en vivo para detectar degradación y drift. Alineación y safety: guardrails en la salida y revisión humana cuando la confianza es baja.

    LLM Evals, Alignment y Observabilidad en Producción: qué medir y por qué

    La evaluación de modelos en producción debe ser multidimensional. Aquí están las métricas que importan y cómo interpretarlas:

    Métricas específicas

    Accuracy / Factuality

    ¿La respuesta es correcta? En sistemas RAG separa Context Recall (¿se recuperó lo relevante?) de Context Precision (¿la respuesta se basa en lo recuperado o lo inventa?).

    Hallucination Rate

    % de respuestas con información inventada. Target operativo: <3–5% según criticidad.

    Goal Completion

    Métrica binaria/medible ligada al negocio (email extraído, ticket resuelto). Es la métrica ROI.

    Toxicity / Safety

    Puntuaciones automáticas (ej. Perspective API) y guardrails para bloquear salidas peligrosas.

    Latency (TTFT y Total Latency)

    TTFT <2s para chat aceptable; objetivos más estrictos para aplicaciones UX sensibles.

    Cost per Task

    tokens * precio/modelo → $ por ejecución. Debe compararse con coste humano.

    Consistencia

    Desviación en resultados en ejecuciones repetidas; alta variabilidad indica prompts inestables o temperatura mal gestionada.

    Cómo construir Evals útiles (práctico)

    1. Golden Dataset

    Golden Dataset

    • Crea un conjunto curado de 100–500 ejemplos por workflow (80% casos comunes, 20% edge).
    • Human-label para ground truth inicial. Sin esto no hay baseline.

    Deterministic vs Model-Graded

    • Deterministic: para outputs estructurados valida formato/JSON con schema checks.
    • Model-graded: usa un LLM “juez” (más capaz) con una rúbrica para puntuar respuestas textuales. Ejemplo: pedir al juez “evalúa factualidad (1–5) y da evidencia”.

    Pipeline de CI

    • Ejecuta el Golden Dataset en cada PR que cambie prompts, chain logic o modelo.
    • Rechaza merges si Accuracy/Goal Completion bajan más de X%.

    Ejemplo simple (pseudocódigo de evaluación):

    # enviar respuesta + contexto + prompt de evaluación a un modelo juez
judge_prompt = "Evalúa si la respuesta es fiel al contexto. Score 1-5. Explica brevemente."
score = call_judge_model(input=context + answer, prompt=judge_prompt)

    Observabilidad en producción: trazas, sampling y alertas

    Las Evals funcionan offline; la Observabilidad te dice qué pasa en vivo.

    Tracing completo

    Registra input, documentos recuperados, prompts enviados, tokens, latencias por etapa. Usa LangSmith, LangFuse o Arize Phoenix para visualizar trace chains.

    Sampling inteligente

    Evalúa en línea entre 0.5–5% del tráfico para balancear coste y cobertura.

    Drift detection

    Monitoriza cambios en la distribución de inputs; alerta cuando un feature importante sale del rango esperado.

    Alertas por SLA

    Accuracy drop, Hallucination spike, o coste por task anómalo disparan rollback o canary throttling.

    Integra traces con OpenTelemetry para correlación con logs y métricas infra.

    Alineación operativa y safety

    • Implementa guardrails en la capa de salida (post‑processing) que validen seguridad y formato antes de exponer la respuesta (ej. NVIDIA NeMo Guardrails).
    • Para respuestas sensibles, requiere verificación secundaria: LLM-as-a-Judge + schema check + citation check (si es RAG).
    • Mantén un “human-in-the-loop” para casos de baja confianza: si la confianza < umbral, encolar para revisión humana.

    Métricas objetivo y SLOs realistas

    Define SLOs por workflow, p. ej.:

    • Accuracy > 95% en Golden Dataset.
    • Hallucination Rate < 3%.
    • TTFT < 2s.
    • Cost per Task < $0.05 (ajusta según caso de negocio).

    Monitoriza y versiona SLOs junto al código/infra.

    Errores comunes que debes evitar

    • No tener Golden Dataset.
    • Medir solo calidad, ignorar coste.
    • No versionar prompts ni modelos.
    • Silenciar drift: sin alertas el modelo se degrada sin aviso.

    Cierre operativo

    LLM Evals, Alignment y Observabilidad en Producción no son funciones accesorias: son el núcleo del ciclo de vida de una IA productiva. Empieza por construir tu Golden Dataset, versiona prompts como código, añade un juez para tareas generativas y despliega tracing por etapas. Con esas piezas, transformarás la IA de experimento a servicio confiable, escalable y justificable en costes.

    Lecturas y herramientas prácticas

    Para equipos que implementan pipelines de Evals y observabilidad como parte de workflows de producto, una continuación lógica es revisar recursos y experimentos prácticos disponibles en Dominicode Labs. Ahí puedes encontrar ejemplos aplicados y plantillas para integrar tracing y CI de evaluación en flujos de trabajo.

    FAQ

    ¿Qué es un Golden Dataset y por qué lo necesito?

    Un Golden Dataset es un conjunto curado y etiquetado de ejemplos (100–500 por workflow) que sirve como baseline para evaluar Accuracy y Goal Completion. Sin él no tienes una referencia objetiva para medir degradación o mejoras.

    ¿Cómo medir hallucinations en producción?

    Combina sampling en línea con evaluaciones humanas y modelos juez que comparen respuestas contra contexto o fuentes. Mide el porcentaje de respuestas con información inventada y fija umbrales operativos (<3–5%).

    ¿Qué es un modelo juez (model-graded)?

    Es un LLM más capaz que puntúa respuestas humanas/modelo según una rúbrica (p. ej. factualidad 1–5) y devuelve evidencia o explicación para el score.

    ¿Cuánto tráfico debo muestrear para Evals en línea?

    Generalmente entre 0.5–5% del tráfico, para equilibrar coste y cobertura. Ajusta según criticidad y coste por task.

    ¿Qué abandonar ante un spike de hallucinations?

    Accionar alertas: revertir cambios recientes (rollback), activar canary throttling, aumentar muestreo y encolar casos para revisión humana hasta estabilizar la tasa.

    ¿Cómo integrar tracing con OpenTelemetry?

    Instrumenta puntos clave (entrada, recuperación de documentos, llamada al modelo, post‑processing), exporta traces a tu backend y correlaciona con logs y métricas infra para análisis de causa raíz.

    ¿Cuáles son SLOs realistas para chatbots?

    Ejemplos: Accuracy >95% en Golden Dataset, Hallucination Rate <3%, TTFT <2s. Ajusta según el workflow y coste/humano de fallback.

  • Mejorando la Recuperación de Información con RAG Avanzado

    Mejorando la Recuperación de Información con RAG Avanzado

    RAG Avanzado: Híbrido, Jerárquico y Multi-Vector

    RAG Avanzado: Híbrido, Jerárquico y Multi-Vector. Si eso suena a demasiada ingeniería comparado con “chunk + embeddings”, es porque lo es —y la diferencia entre demo y producto está justo ahí. En producción no vale con que el LLM “suene bien”; necesitas precisión, contexto y control de coste. Este artículo explica qué técnicas añadir, por qué y cuándo.

    Tiempo estimado de lectura: 4 min

    • Ideas clave:
    • La recuperación es el 80% de una buena respuesta: combina sparse (BM25) y dense (embeddings).
    • Arquitectura jerárquica (child + parent) equilibra precisión de fragmento y contexto coherente.
    • Re-ranking con cross-encoders y compresión de contexto reducen hallucinations y coste token.

    Introducción

    La calidad de las respuestas generadas por un sistema RAG depende mayoritariamente de la recuperación. Los vectores aportan semántica; los métodos sparse (BM25) aportan exactitud. En producción necesitas precisión, contexto y control de coste; esto implica añadir capas: híbrido, jerarquía, re-ranking, rewriting y compresión de contexto.

    Resumen rápido (lectores con prisa)

    RAG avanzado combina búsquedas sparse (BM25) y dense (embeddings) para precisión y semántica. Usa indexing jerárquico child→parent para fragmentos precisos con contexto. Re-rank con cross-encoders para reducir ruido. Reescribe y descompone queries; comprime contexto antes del LLM.

    RAG Avanzado: implementación práctica

    1) Hybrid retrieval: BM25 + embeddings

    Problema: buscas “ERR-9921” y el vector devuelve “error de sistema” porque semánticamente es parecido. Solución: híbrido.

    • Sparse: BM25/Elasticsearch para coincidencias literales.
    • Dense: embeddings (OpenAI, Cohere, etc.) para intención.
    • Fusión: Reciprocal Rank Fusion (RRF) o combinación ponderada. Pinecone hybrid search

    Patrón práctico:

    • Ejecuta BM25 y vector search en paralelo.
    • Normaliza scores.
    • Fusiona con RRF.
    • Si BM25 tiene match exacto para tokens sensibles (IDs, SKUs), priorízalo.

    2) Multi-vector / Parent-Child indexación

    Dilema clásico: chunks pequeños = mejor match; chunks grandes = mejor contexto. La arquitectura jerárquica arregla ambos.

    • Indexa embeddings a nivel child (p. ej. 200 tokens).
    • Mantén parent docs grandes (p. ej. 2000 tokens) con metadata.
    • Al recuperar un child relevante, sube el parent completo al contexto.

    Implementación: LangChain ParentDocumentRetriever — LangChain ParentDocumentRetriever

    Beneficio: precisión de fragmento + contexto coherente para razonamiento.

    3) Re-ranking con cross-encoders

    Bi-encoders: rápidos, aproximados. Cross-encoders: lentos, precisos.

    Flujo:

    1. Fast retrieval → top N (50).
    2. Cross-encoder rerank en top N.
    3. Selecciona top K final para el LLM.

    Herramientas: sentence-transformers, Cohere Rerank. Costo: aumenta latencia; recompensa: reduce ruido que provoca hallucinations.

    4) Query rewriting y decomposition

    Muchos fallos vienen por queries ambiguas. No todos los problemas se arreglan en el índice.

    • Query rewrite: un LLM rápido reescribe la consulta con contexto de la sesión.
    • Multi-query: genera 3–5 variantes de la pregunta y busca por cada una.
    • Decomposition: divide preguntas complejas en sub-queries paralelas.

    Técnica HyDE (Hypothetical Document Embeddings) es útil: genera la “respuesta hipotética”, embeddea eso y busca. Idea en práctica: mejora recall sin cambiar el índice.

    5) Context compression antes del LLM

    Enviar 10 documentos de 8k tokens es suicida. Comprime:

    • Filtrado selectivo: extrae párrafos con más evidencia.
    • Summarization condensado (con cuidado: pierde citas).
    • Algoritmos de compresión semántica como LLMLingua

    Objetivo: maximizar densidad informativa dentro de la ventana del LLM.

    Criterio para decidir qué añadir (roadmap pragmático)

    No implementes todo a la vez. Sigue este orden iterativo:

    1. Naive RAG. Mide recall@5 y tasa de hallucination.
    2. Si fallan exact matches → añade Hybrid (BM25).
    3. Si falta contexto coherente → añade Parent-Child multi-vector.
    4. Si llega ruido que confunde al LLM → añade Re-ranking.
    5. Si tokens exceden la ventana → añade Context Compression.

    Mide antes y después. No hay excusas.

    Operacional: latencia, coste y caching

    • Re-ranking y cross-encoders aumentan latencia 10x en la etapa de ranking. Mitiga con caching de top-N por query fingerprint.
    • Hybrid search añade coste infra (Elasticsearch + vector DB). Mide Cost/Accuracy.
    • Batch embeddings nocturnos para contenido estático. Mantén refresh policies.
    • Telemetría: trace request → retrieval steps → rerank → LLM call. LangFuse y LangSmith ayudan a visualizar traces (LangFuse, LangSmith).

    Integración con agentes y workflows (n8n)

    Pipeline ejemplo en n8n:

    1. Node: Query Rewrite (LLM pequeño)
    2. Node: Hybrid Search (ES + Pinecone/Qdrant)
    3. Node: Rerank (Cross-Encoder)
    4. Node: Parent Expander + Context Compressor
    5. Node: LLM final (generation)
    6. Node: Post-check (schema validation / guardrails)

    Versiona prompts, registra fingerprints y alertas en drift.

    Referencias operativas

    Implementar RAG avanzado es menos glamour y más disciplina: medir, añadir la capa correcta y repetir. Hazlo así y tu sistema dejará de improvisar respuestas y empezará a dar respuestas que puedes explicarle al CTO.

    Dominicode Labs

    Si trabajas con pipelines de agentes, workflows o IA aplicada, considera explorar integraciones y experimentos prácticos en Dominicode Labs. Es una continuación lógica para prototipos operacionales y pruebas de telemetría.

    FAQ

     

    Respuesta: ¿Por qué combinar BM25 con embeddings?

    BM25 proporciona coincidencias literales útiles para IDs, SKUs y frases exactas; los embeddings capturan intención y sinónimos. El híbrido reduce falsos positivos semánticos y mejora precisión en búsquedas sensibles.

     

    Respuesta: ¿Qué ventaja tiene la indexación parent-child?

    Permite mantener chunks pequeños para alta precisión en matching mientras se conserva contexto amplio subiendo el documento parent al LLM cuando un child es relevante.

     

    Respuesta: ¿Cuándo usar cross-encoders para re-ranking?

    Úsalos cuando el top-N recuperado contenga ruido que provoca hallucinations o respuestas incorrectas. Son adecuados para reducir falsos positivos aunque aumenten latencia y coste.

     

    Respuesta: ¿Qué es HyDE y por qué usarlo?

    HyDE (Hypothetical Document Embeddings) genera una “respuesta hipotética” desde un LLM, la embeddea y busca con esa representación. Mejora recall sin tocar el índice.

     

    Respuesta: ¿Cómo mitigar la latencia al re-rankear?

    Cachea top-N por huella de consulta, ejecuta re-ranking asíncrono donde sea posible y usa cross-encoders solo en escenarios críticos o por lotes nocturnos para contenido estático.

     

    Respuesta: ¿Qué técnicas de compresión de contexto son seguras?

    Filtrado selectivo de párrafos con evidencia, resúmenes condensados con control de citas y algoritmos semánticos como LLMLingua. Ten cuidado: la compresión puede perder citas y detalles verificables.

  • El futuro de los programadores en un mundo de IA

    El futuro de los programadores en un mundo de IA

    Dejarán de existir los programadores debido a la AI, cuál será el futuro ?

    Tiempo estimado de lectura: 4 min

    • La profesión no desaparece: se transforma hacia orquestación, seguridad y responsabilidad técnica.
    • Habilidades críticas: testeo semántico, control de agentes, observabilidad de LLMs, FinOps y seguridad.
    • Roles emergentes: orquestadores de agentes, AI FinOps, observability y security engineers especializados en IA.

    Dejarán de existir los programadores debido a la AI, cuál será el futuro? No: la profesión no desaparece, se transforma. Lo que muere es la recompensa por saber cerrar un paréntesis. Lo que surge es la demanda por gente que tenga criterio para diseñar, orquestar y responsabilizar una capa de IA dentro de sistemas reales.

    Los LLMs generan código. Bien. Eso no es la mitad del problema; es solo la parte fácil. El verdadero trabajo será asegurar que ese código no rompa la seguridad, no arruine las finanzas del proyecto y funcione 1.000 veces en producción sin alucinar.

    Resumen rápido (lectores con prisa)

    Qué es: La automatización con LLMs transforma el rol de programador hacia orquestación, seguridad y fiabilidad.

    Cuándo usarlo: Al integrar LLMs en sistemas productivos que requieren disponibilidad, coste controlado y seguridad.

    Por qué importa: Implementar IA sin pruebas semánticas, observabilidad y control de costes puede generar fallos graves y gastos inesperados.

    Cómo funciona (resumen): Orquesta agentes, traza prompts/embeddings/tool-calls, aplica tests semánticos y controles financieros por flujo.

    Dejarán de existir los programadores debido a la AI, diagnóstico técnico

    No estamos ante la extinción del oficio, sino ante su re-especialización. La automatización desplaza tareas repetitivas; obliga a los ingenieros a evolucionar hacia roles donde el juicio técnico y la orquestación valen más que teclear rápido.

    Los puntos clave

    • La IA reduce el coste de producción de implementación, no el coste de responsabilidad técnica.
    • El valor pasa de la implementación a la arquitectura, la seguridad y la fiabilidad.
    • Aparecen roles nuevos: orquestadores de agentes, ingenieros FinOps de IA, responsables de observabilidad de LLMs.

    Estos cambios ya son prácticos: n8n y LangChain no son hobbies; son infra para orquestar lógica humana + IA. Pinecone es la memoria cuando el modelo no puede cargar todo el contexto. OpenTelemetry y Arize son los instrumentos para medir lo que antes sólo se infería.

    El nuevo skill set crítico (cinco prioridades)

    Si quieres seguir siendo indispensable, domina estas cinco áreas. No son “buenas ideas”; son requisitos de producción.

    1) Testeo automático inteligente (Evals)

    Los tests string-to-string fallan con LLMs. Necesitas evaluadores semánticos: datasets de respuestas esperadas, pruebas basadas en esquemas (JSON Schema) y LLMs que actúen como juez. Herramientas y patrones: golden datasets, pruebas adversariales y evaluación automática de coherencia y factualidad.

    2) Evaluación de agentes y control de flujo

    Un agente que funciona una vez es un experimento. Uno que opera a escala requiere máquinas de estado, grafos de flujo y guardrails. Usa FSMs, límites de iteración y validaciones por step para evitar loops, fugas de datos o ejecuciones no deseadas.

    3) Observabilidad de LLMs

    La traza del stack ya no es suficiente. Tienes que recolectar: prompt original, embeddings usados (RAG), tool calls, respuesta del modelo, tokens consumidos y latencia por paso. Implementa tracing end-to-end con OpenTelemetry y tableros que correlacionen degradación de calidad con cambios en prompts o datos.

    4) Cost control (FinOps para IA)

    Un bug puede costar miles en una noche. Controla tokens, cachea respuestas recurrentes (Redis), enruta cargas a modelos baratos para operaciones simples y reserva modelos caros solo para razonamientos complejos. Mide coste por petición y ROI por cada flujo automatizado.

    5) Seguridad y prompt injection

    La seguridad ya no es sólo SQLi o XSS. Es impedir que una instrucción de usuario manipule el prompt o que un agente ejecute acciones peligrosas. Aplica mínimo privilegio en cada tool que expongas, valida outputs con esquemas y aisla tokens/credenciales. Considera frameworks de guardrails como NVIDIA NeMo Guardrails y políticas de ejecución restringidas.

    Roles que emergen: quiénes ganan

    • Orquestador de agentes: diseña flujos, define límites y asegura estabilidad.
    • AI FinOps Engineer: controla coste, optimiza rutas de modelos y define SLAs económicos.
    • Observability Engineer para IA: instrumenta trazas y define alertas sobre calidad, no solo sobre latencia.
    • Security Engineer de IA: modela amenazas específicas de LLM y aplica mitigaciones.

    La diferencia entre un “operador” y un “orquestador” será la diferencia entre un puesto reemplazable y uno que aguante la próxima década.

    Qué hacer desde ya (práctico)

    1. Empieza por auditar: ¿qué procesos usan IA y cuánto cuestan en tokens al mes?
    2. Implementa tracing básico: persistir prompts, respuestas y metadatos por petición.
    3. Define 10 pruebas de “smoke” semánticas para tus agentes: respuestas que siempre deben cumplirse.
    4. Añade límites de ejecución y una ruta de escalado humano si el agente falla.
    5. Establece un plan de costes: modelos baratos para lo trivial, modelos caros para lo crítico.

    Cierre — no se acaba aquí

    La IA no borrará a los programadores; los forzará a subir de nivel. Si te niegas a aprender testeo semántico, observabilidad y FinOps para IA, estarás desapareciendo a cámara lenta. Si lo aprendes, pasarás de escribir funciones a diseñar sistemas confiables que realmente automaten trabajo de valor.

    Empieza hoy: instrumenta un flujo con tracing, añade una prueba semántica y pon límites de coste. Lo siguiente será orquestarlo a escala.

    Si trabajas en automatización, agentes o workflows y buscas recursos prácticos para prototipar trazas y pruebas semánticas, consulta Dominicode Labs. Es una continuidad lógica para equipos que quieren pasar de experimentos a pipelines reproducibles y observables.

    FAQ

    Respuesta: No. La profesión se transforma: disminuye el valor de tareas repetitivas y aumenta la demanda de roles que gestionen, orquesten y aseguren sistemas con IA.

    Respuesta: Testeo semántico, control de agentes/flow, observabilidad de LLMs, FinOps para IA y seguridad frente a prompt injection.

    Respuesta: Empieza creando golden datasets de respuestas esperadas, define pruebas basadas en esquemas (JSON Schema) y automatiza evaluaciones usando LLMs como juez y pruebas adversariales.

    Respuesta: Es trazar prompts, embeddings, tool calls, respuestas, tokens y latencias end-to-end para correlacionar degradación de calidad con cambios en datos o prompts.

    Respuesta: Mide coste por petición, cachea respuestas recurrentes, enruta cargas simples a modelos baratos y reserva modelos caros para razonamiento complejo; aplica límites y alertas.

    Respuesta: Aplica mínimo privilegio a tools, valida outputs con esquemas, aísla tokens/credenciales y usa frameworks de guardrails para mitigar prompt injection.

  • Prácticas para crear skills efectivas en agentes

    Prácticas para crear skills efectivas en agentes

    Best Practices for Creating Agent Skills

    Tiempo estimado de lectura: 5 min

    • Diseña SKILL.md como orquestador compacto: no como una enciclopedia; enumera pasos y triggers claros.
    • Externaliza lo frágil: scripts deterministas en scripts/, reglas densas en references/, templates en assets/.
    • Progressive Disclosure (JiT): carga solo archivos cuando surge un trigger explícito.
    • Validación en tres fases con LLMs: discovery, lógica y edge-case testing.

    Introducción

    ¿Quieres que tus agentes dejen de fallar por cosas tontas? La mayoría lo hace porque sus skills son documentación para humanos disfrazada de herramienta para máquinas. Los agentes no leen; ejecutan. Y para ejecutar necesitan reglas claras, rutas exactas y scripts que no improvisen.

    Aquí va la arquitectura práctica que uso cuando diseñamos skills que realmente funcionan en producción.

    Resumen rápido (lectores con prisa)

    Qué es: Un conjunto de reglas, scripts y plantillas organizadas para que un agente tome decisiones deterministas.

    Cuándo usarlo: Al diseñar skills que interactúan con repositorios, migraciones, o tareas automatizadas que requieren reproducibilidad.

    Por qué importa: Evita ambigüedades que causan alucinaciones y resultados inconsistentes.

    Cómo funciona: SKILL.md orquesta; scripts ejecutan validaciones; references/ y assets/ se cargan sólo mediante triggers explícitos.

    Estructura de una skill: la regla de hierro

    skill-name/
├── SKILL.md              # Metadatos + instrucciones core (<500 líneas)
├── scripts/              # CLIs pequeños para tareas deterministas
├── references/           # Reglas densas, cheatsheets, esquemas
└── assets/               # Templates y archivos estáticos

    SKILL.md es “el cerebro”: orquesta, no enciclopedia. scripts/ ejecuta lo que no puede fallar. references/ y assets/ guardan lo pesado, pero el agente sólo los lee cuando se lo indicas.

    Naming y frontmatter: haz que la skill sea visible

    El agente decide cargar una skill solo por el frontmatter. Si tu nombre y descripción son vagos, la skill es invisible.

    Reglas:

    • name = 1–64 chars, minúsculas, números y guiones. Debe coincidir exactamente con el nombre del directorio.
    • descripción = máximo 1,024 caracteres, en tercera persona e incluye negative triggers.

    Ejemplo práctico:

    name: angular-vite-migrator
description: Migra proyectos Angular CLI de Webpack a Vite y esbuild. Usar para actualizar builders o reemplazar plugins de Webpack por equivalentes de Rollup. No usar para proyectos React, Svelte o para sólo actualizar la versión de Angular.

    Eso reduce falsos positivos. Punto.

    Progressive Disclosure: carga solo lo necesario

    Los LLMs tienen memoria limitada. Meter 800 líneas de vite.config.ts en el prompt es pedir perdón por las alucinaciones.

    Patrón: JiT (Just-in-Time).

    • SKILL.md enumera pasos altos y dice exactamente cuándo abrir un archivo.
    • Coloca plantillas complejas en assets/ y reglas en references/.
    • Instrucción clara: “Si detectas @angular-builders/custom-webpack en angular.json, abre references/webpack-fallbacks.md”.

    El agente no ve nada hasta que el trigger ocurre. Menos tokens, más precisión.

    Escribe para máquinas: imperativo y pasos numerados

    Las skills son código en lenguaje natural. Escribe en tercera persona, imperativo y con pasos numerados.

    Correcto:

    1. Ejecuta scripts/env-validator.mjs
2. Si el exit code es 1, reporta: "Node version incompatible. Upgrade required." Termina.

    Incorrecto: “Quizá quieras comprobar la versión de Node…” — frase que confunde y genera ambigüedad.

    Scripts deterministas: no pidas improvisación

    No le pidas al LLM que escriba parsers complejos en cada ejecución. Empaqueta esos parsers y detectores como scripts pequeños y probados en scripts/. El agente los invoca con parámetros y actúa según stdout/stderr.

    Ejemplo de stdout útil:

    CRITICAL: Found legacy CommonJS 'legacy-lib' that uses dynamic require(). Recommendation: add to optimizeDeps.include or shim with esm-adapter. See references/commonjs-guide.md

    Ese mensaje debe permitir al agente decidir el siguiente paso sin adivinar.

    Templates y outputs parseables

    Coloca un template en assets/ (por ejemplo, assets/vite.config.template.ts). Instrucción en SKILL.md:

    • “Copia assets/vite.config.template.ts a vite.config.ts y rellena los placeholders según el mapeo en references/mapping.md.”

    Los LLMs reconocen patrones; darles la plantilla evita salidas rotas y archivos inválidos.

    Validación con LLMs: prueba en tres fases

    Las skills las usarán LLMs, así que valídalas con LLMs.

    1. Discovery Validation

    Pega solo el frontmatter en un LLM limpio. Pide 3 prompts que deben activar la skill y 3 que no. Ajusta la descripción hasta que el modelo acierte.

    2. Logic Validation

    Pasa el SKILL.md y la estructura de archivos. Pide al LLM que actúe como agente y escriba su monólogo paso a paso: qué lee, qué ejecuta, y dónde se ve obligado a adivinar.

    3. Edge Case Testing (Red Team)

    Pide al LLM que te rompa la skill con preguntas concretas: Node antiguo, builders custom, imports dinámicos. Si responde con huecos, rellena referencias y scripts hasta que no queden ambigüedades.

    Ejemplos de fallas comunes y cómo prepararlas

    • CommonJS legacy en esbuild: añade scripts/detect-commonjs.mjs que devuelvan JSON con las dependencias problemáticas y recomendaciones.
    • @angular-builders/custom-webpack en angular.json: stop automatic migration. Instruye a abrir references/webpack-fallbacks.md y proponer un plan híbrido (mantener Webpack para producción, migrar dev a Vite).
    • Entorno Node no compatible: scripts/env-validator.mjs debe chequear process.version y salir con mensaje accionable.

    Cierre con criterio

    Construir skills no es arte ni redacción creativa: es ingeniería. Nombra con precisión, externaliza lo frágil a scripts, usa templates y obliga a los agentes a cargar sólo lo que necesitan. Haz esto y tus agentes dejarán de inventar soluciones —y empezarán a producir resultados reproducibles.

    Reestructura una skill bajo estas reglas hoy y verás cómo el agente deja de improvisar. Esto no acaba aquí; las skills bien diseñadas son la base de la automatización fiable.

    Dominicode Labs

    Para equipos que diseñan workflows y agentes, recursos y experimentos prácticos en automatización y agentes están disponibles en Dominicode Labs. Considera revisarlo como complemento para validar skills y pipelines en entornos reales.

    FAQ

     

    ¿Qué debe contener SKILL.md?

    SKILL.md debe ser el orquestador: metadatos (frontmatter), pasos numerados claros, triggers explícitos sobre cuándo abrir archivos en references/ o assets/, y referencias a scripts/ ejecutables. Mantenerlo por debajo de 500 líneas.

     

    ¿Por qué externalizar parsers en scripts/?

    Porque los parsers y detectores complejos son frágiles si se piden al LLM en cada ejecución. Scripts deterministas devuelven stdout/stderr o JSON que permite decisiones automáticas sin ambigüedad.

     

    ¿Cómo funciona Progressive Disclosure?

    El agente solo carga información adicional cuando un trigger en SKILL.md lo indica (JiT). Así se evita saturar el prompt con archivos largos y se mejora la precisión.

     

    ¿Qué formato deben tener los outputs de los scripts?

    Outputs legibles por máquina: líneas con prefijos (ej. CRITICAL:) o JSON. Deben contener suficiente contexto y una recomendación accionable para que el agente decida el siguiente paso.

     

    ¿Cuándo incluir references/webpack-fallbacks.md?

    Incluirlo cuando detectes @angular-builders/custom-webpack en angular.json. La instrucción en SKILL.md debe ordenar abrir ese archivo y proponer un plan híbrido si aplica.

     

    ¿Cómo validar una skill con LLMs?

    Validación en tres fases: Discovery Validation con solo frontmatter, Logic Validation con SKILL.md y estructura de archivos (monólogo del agente), y Edge Case Testing (Red Team) para cerrar huecos.