AgentHandover: Skills que se Escriben Solas en Claude Code

AgentHandover es una herramienta open-source para macOS que observa cómo trabajas y genera skills compatibles con Claude Code de forma automática. Usa modelos locales (Qwen 3.5 + nomic-embed-text) para capturar tu flujo, extraer patrones y crear playbooks que se auto-mejoran con cada ejecución. El resultado: dejas de repetirle al agente lo mismo en cada sesión.

El problema: 20 minutos explicando lo mismo, cada día

Abres una sesión nueva de Claude Code. Lo primero que haces es explicar el contexto: la estructura del proyecto, las convenciones del equipo, el flujo de deploy, los comandos que usas. Tardas entre 10 y 20 minutos. Al día siguiente, lo repites.

Este patrón se llama fatiga de contexto. No es un bug del modelo, es una limitación arquitectónica. Los agentes de código operan sin memoria persistente entre sesiones. Cada conversación empieza desde cero, y todo ese contexto repetido quema tokens sin aportar valor.

Las soluciones actuales (CLAUDE.md, skills manuales, cursor rules) ayudan, pero requieren que tú escribas y mantengas esa documentación. AgentHandover propone lo contrario: que el sistema aprenda observándote.

¿Qué es AgentHandover?

AgentHandover es una aplicación open-source (Apache 2.0) para macOS que observa tu flujo de trabajo, extrae patrones de comportamiento y genera skills compatibles con Claude Code, Codex, OpenClaw o cualquier agente MCP. Todo el procesamiento es local: no envía datos a ningún servicio externo.

A diferencia de una skill escrita a mano, que dice "haz X y luego Y", las skills de AgentHandover incluyen la estrategia detrás de cada paso, criterios de selección, guardrails, tu estilo de comunicación y una puntuación de confianza basada en observaciones reales.

El proyecto es de Sandro Andric, tiene licencia Apache 2.0, 176 estrellas en GitHub y generó tracción rápida en Reddit (118 upvotes en su post de lanzamiento). La comunidad lo ha recibido como la primera herramienta que ataca la fatiga de contexto desde la observación, no desde la documentación manual.

Arquitectura: cómo observa tu trabajo

Tres componentes en cadena procesan tu actividad y la convierten en skills accionables:

Componente	Lenguaje	Función
Daemon	Rust	Capturas de pantalla, eventos del SO, clipboard, deduplicación
Worker	Python	Pipeline de 11 etapas, base de conocimiento vectorial, síntesis
Extensión Chrome	TypeScript	Snapshots del DOM, targets de click, IDs de formularios

Los datos fluyen por un pipeline de 11 etapas:

Captura de pantalla: media resolución con deduplicación perceptual (descarta ~70% de frames)
Anotación VLM: Qwen 3.5 local analiza cada frame (app activa, URL, acción actual)
Clasificación de actividad: taxonomía de 8 clases (trabajo vs. entretenimiento)
Embedding de texto: nomic-embed-text, vectores de 768 dimensiones
Embedding de imagen: SigLIP opcional, 1152 dimensiones
Clustering semántico: agrupa actividad por significado, no por keywords
Vinculación cross-session: conecta actividades similares entre días
Síntesis de comportamiento: tras 3+ observaciones, extrae estrategia y ramas de decisión
Análisis de voz: captura tu estilo de escritura por flujo
Generación de skill: skill canónica con deduplicación semántica
Revisión humana: tú apruebas; seis puertas de seguridad antes de la ejecución

Un detalle de privacidad: las capturas se eliminan tras la anotación VLM. Solo persiste texto estructurado, cifrado en reposo con XChaCha20-Poly1305. Las API keys, tokens y datos sensibles se redactan de forma automática.

Dos modos de enseñanza: Focus Recording y Passive Discovery

AgentHandover ofrece dos formas de generar skills, y puedes combinarlas.

Focus Recording: captura deliberada

Haz clic en "Record" en la barra de menú, nombra la tarea, ejecútala y pulsa "Stop". El sistema te hace 1-3 preguntas desde la perspectiva del agente (por ejemplo: "¿Qué determina qué elementos procesas y cuáles ignoras?") y genera una skill completa. Es el modo rápido para flujos que quieres delegar ahora.

Passive Discovery: aprendizaje en segundo plano

Trabaja con normalidad. AgentHandover detecta patrones recurrentes entre sesiones usando similitud semántica. Cuando acumula suficiente evidencia (3+ observaciones del mismo flujo), ejecuta síntesis de comportamiento y genera una skill. Este modo funciona para flujos que repites sin darte cuenta.

Si ya usas skills de Claude Code escritas a mano, AgentHandover no las reemplaza: las complementa con skills basadas en observación real que capturan matices que difícilmente documentarías tú mismo.

Instalación y configuración paso a paso

Requisitos: macOS, Ollama instalado, ~6,3 GB de espacio para modelos.

Descarga los modelos locales que necesita el pipeline:

# Modelos necesarios para el pipeline de AgentHandover
ollama pull qwen3.5:2b       # ~2,7 GB - anotación de escenas
ollama pull qwen3.5:4b       # ~3,4 GB - generación de skills
ollama pull nomic-embed-text # ~274 MB - búsqueda semántica

Instala AgentHandover por Homebrew o descarga el .pkg desde releases:

# Instalación via Homebrew
brew tap sandroandric/agenthandover
brew install --HEAD agenthandover

# Verificación y arranque
agenthandover doctor    # comprueba dependencias
agenthandover start all # lanza daemon + worker

Conectar con Claude Code y otros agentes

AgentHandover expone sus skills a través de un servidor MCP. La integración con Claude Code es directa:

# Las skills se convierten en slash commands en Claude Code
agenthandover connect claude-code

Para otros agentes, añade la configuración MCP:

{
  "mcpServers": {
    "agenthandover": {
      "command": "agenthandover-mcp"
    }
  }
}

Si ya tienes servidores MCP configurados en Claude Code, AgentHandover se integra como uno más. El servidor expone 8 herramientas: list_ready_skills, get_skill, search_skills, y tres de reporte de ejecución que alimentan el ciclo de mejora.

El ciclo de auto-mejora

Cuando un agente ejecuta una skill, reporta el resultado paso a paso. Las ejecuciones exitosas aumentan la confianza de la skill. Las desviaciones (2 o más) sugieren nuevas ramas de decisión. Los fallos bajan la confianza, y tras 3 fallos en 7 días, la skill se degrada de forma automática. Es un sistema que se corrige solo.

En Producción

Rendimiento: el daemon en Rust consume recursos mínimos. El worker Python es el componente más pesado por la inferencia VLM, pero al usar modelos de 2-4B parámetros, un Mac con 16 GB de RAM lo mueve sin problemas. En Apple Silicon, la inferencia VLM por frame tarda ~2-3 segundos.

Costes: cero si usas modelos locales con Ollama. Si optas por APIs cloud (OpenAI, Anthropic, Google), AgentHandover las soporta como opción, pero el pipeline de deduplicación descarta el 70% de frames antes de llegar al VLM, lo que limita el gasto.

Limitaciones a tener en cuenta:

Solo macOS. No hay versión para Linux ni Windows. El daemon usa APIs nativas y la UI es SwiftUI.
Extensión Chrome necesaria para capturar contexto web (DOM, URLs, clicks). Sin ella, solo tienes capturas de pantalla.
Mínimo 3 observaciones para Passive Discovery. Si tu flujo varía cada vez, Focus Recording es más práctico.
Las skills replican tus flujos tal cual. Si tu proceso tiene pasos ineficientes, la skill los reproduce fielmente.

Seguridad: las seis puertas (lifecycle, trust, freshness, preflight, evidence, execution history) previenen ejecución sin verificación. No hay ejecución automática sin aprobación explícita. Esto es clave en entornos donde la confianza ciega en herramientas de IA genera más problemas de los que resuelve.

Errores Comunes y Depuración

Error: agenthandover doctor falla con "Ollama not found".
Causa: Ollama no está en el PATH o el servicio no está activo.
Solución: ejecuta ollama serve en otra terminal y verifica con ollama list.

Error: las skills generadas son genéricas o poco útiles.
Causa: pocas observaciones o flujos demasiado variados entre sesiones.
Solución: usa Focus Recording para flujos específicos. El modo pasivo necesita consistencia.

Error: el MCP server no aparece en Claude Code.
Causa: configuración MCP incorrecta o servicio detenido.
Solución: verifica con curl http://localhost:9477/ready y revisa tu settings.json.

Preguntas Frecuentes

¿AgentHandover funciona con agentes que no sean Claude Code?

Sí. Las skills son compatibles con cualquier agente MCP: Codex (agenthandover connect codex), OpenClaw y cualquier herramienta que consuma el protocolo. También expone una API REST en localhost:9477 para integraciones personalizadas.

¿Cuánto espacio en disco necesita?

Los modelos de Ollama ocupan ~6,3 GB. La base de conocimiento crece según tu uso, pero las capturas se eliminan tras la anotación y solo se almacena texto estructurado. En uso normal, la base de datos no supera unos cientos de MB.

¿Puedo usarlo en Linux o Windows?

A abril de 2026, AgentHandover es exclusivo de macOS. El daemon usa APIs nativas del sistema operativo y la interfaz es SwiftUI. El repositorio no menciona planes concretos para otras plataformas, aunque la arquitectura modular del worker (Python) facilitaría un port parcial.

AgentHandover ataca la fatiga de contexto desde la raíz: en lugar de escribir documentación para tu agente, dejas que aprenda observándote. El pipeline local con VLM garantiza privacidad, las seis puertas de seguridad mantienen el control humano, y el ciclo de auto-mejora refina las skills con cada uso. Si trabajas con Claude Code a diario y notas que pasas demasiado tiempo re-explicando contexto, esto vale los 5 minutos de instalación.

Ten en cuenta que es un proyecto joven (176 estrellas, solo macOS) y que la calidad de las skills depende directamente de la consistencia de tus flujos. Como con cualquier herramienta de automatización, la configuración inicial es una inversión que se amortiza con el uso diario.

¿Has probado AgentHandover o tienes tu propio sistema para mantener el contexto entre sesiones? Cuéntamelo en Twitter @sergiomarquezp_. En próximos posts exploraremos más herramientas del ecosistema de skills y cómo montar agentes que necesiten la menor intervención humana posible.