🌱 Empieza aquí · Capturador de Aprendizajes por Agente

¿Armaste tus propios agentes (subagentes) para que hagan tareas por ti? Genial. El problema es que cada uno aprende cosas mientras trabaja —un error que corregiste, un truco que funcionó, una preferencia tuya— y todo eso se evapora apenas termina. La próxima vez tropieza con la misma piedra.

Esta semilla instala un guardián que actúa justo cuando un agente tuyo termina: revisa si dejó anotados sus aprendizajes. Si no anotó nada, le recuerda a tu asistente capturar lo valioso. Si sí anotó, le pide una revisión rápida de calidad para que la nota sirva de verdad. Así tu equipo de agentes se vuelve más listo con cada uso, sin que tú tengas que estar encima.

Para instalarla

Abre esta carpeta con Claude Code o Cowork y dile a tu asistente:

"Siembra esta semilla 🌱"

Con eso basta de tu parte. Tu asistente hace todo lo técnico y al final te dice cómo comprobar que quedó funcionando. Vas a ver algunas palabras en inglés en la pantalla; ni caso, él te guía.

¿Otras formas de pedírselo? "instala esta semilla", "pon a funcionar el capturador de aprendizajes", "haz el setup de esto". Te entiende igual.

Para el asistente que siembra 🤖

Instala este hook (gancho de automatización) del evento SubagentStop (fin de un subagente). Se dispara cada vez que un subagente termina y le devuelve al orquestador, vía exit 2, una instrucción para capturar o pulir aprendizajes. Sigue estos pasos y no inventes rutas: usa $HOME siempre.

Preflight · verifica `jq` antes de instalar (obligatorio)

El hook lee el nombre del agente con jq. Si jq no está instalado, el hook no falla con un error ruidoso: se queda en silencio y parece que "no hace nada" (el peor tipo de falla). Ojo especial en macOS, que no trae jq de fábrica. Compruébalo primero y, si falta, instálalo antes de seguir:

command -v jq >/dev/null 2>&1 && echo "jq OK: $(jq --version)" || echo "FALTA jq · instálalo antes de continuar"

Si falta:

macOS: brew install jq (o descárgalo de su release oficial si no usas Homebrew).
Debian / Ubuntu / WSL: sudo apt-get install -y jq.
Windows (Git Bash): suele venir incluido; si no, winget install jqlang.jq.

No sigas al paso 1 hasta que el comando imprima jq OK.

0. Este hook asume una convención de aprendizajes por agente

El método parte de una idea simple: cada agente definido por el usuario tiene su propia bitácora de aprendizajes. Por defecto:

Las definiciones de los agentes viven en $HOME/.claude/agents/<nombre>.md.
Sus bitácoras de aprendizajes viven en $HOME/.claude/agents/learnings/<nombre>.md.
(Opcional) Un archivo de patrones comunes a todos: $HOME/.claude/agents/learnings/shared-patterns.md.

Si el usuario no tiene todavía la carpeta learnings/, créala; el hook la usará cuando el agente empiece a escribir ahí. Si el usuario organiza sus agentes en otras rutas, ajústalas con las variables de entorno del paso 3.

1. Copia el script del kernel (el corazón de la semilla)

Copia kernel/learnings-monitor.sh a la carpeta de hooks del usuario y dale permiso de ejecución.

Claude Code / Cowork (macOS o Linux):

mkdir -p "$HOME/.claude/hooks"
cp kernel/learnings-monitor.sh "$HOME/.claude/hooks/learnings-monitor.sh"
chmod +x "$HOME/.claude/hooks/learnings-monitor.sh"

Windows (Git Bash / WSL): misma ruta ~/.claude/hooks/. El script usa bash, jq, find, stat y date, que vienen con Git Bash o WSL. Si el usuario corre Claude Code nativo en Windows sin bash, avísale que este hook necesita un entorno con bash y jq disponibles.

2. Registra el hook en `settings.json`

Abre $HOME/.claude/settings.json (créalo si no existe) y agrega esta entrada dentro de hooks.SubagentStop. Si ya hay hooks de SubagentStop, suma este objeto al arreglo hooks existente en lugar de reemplazarlo:

{
  "hooks": {
    "SubagentStop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "bash $HOME/.claude/hooks/learnings-monitor.sh",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

3. (Opcional) Ajusta rutas o tiempos

Todo es configurable por variables de entorno (o cambiando el valor por defecto en la parte superior del script). Estas son todas las que entiende, con su significado:

AGENTS_DIR — carpeta con las definiciones de los agentes del usuario (por defecto $HOME/.claude/agents).
LEARNINGS_DIR — carpeta donde cada agente guarda su bitácora (por defecto $AGENTS_DIR/learnings).
SHARED_PATTERNS_FILE — el doc de patrones comunes a todos los agentes (por defecto $LEARNINGS_DIR/shared-patterns.md); solo se menciona en el mensaje si el archivo existe.
LEARNINGS_FRESH_MIN — cuántos minutos cuentan como "recién escrito" para decidir entre revisar calidad o recordar capturar (por defecto 5).
LEARNINGS_ANTILOOP_SEC — no revisar al mismo agente dos veces en menos de N segundos (por defecto 60).
LEARNINGS_STATE_DIR — dónde deja los sellos de tiempo anti-repetición (por defecto la carpeta temporal del sistema).

4. Verificación post-siembra (obligatoria)

Confirma que el guardián se dispara de verdad. Simula el evento con un agente de prueba: primero crea su definición y su bitácora recién escrita, luego pásale el evento al hook por la entrada estándar.

# Agente de prueba con bitácora recién escrita
mkdir -p "$HOME/.claude/agents/learnings"
touch "$HOME/.claude/agents/agente-demo.md"
echo "2026-07-05 · demo · aprendizaje de prueba · aplicar-cuando: nunca" > "$HOME/.claude/agents/learnings/agente-demo.md"

echo '{"agent_name":"agente-demo"}' | bash "$HOME/.claude/hooks/learnings-monitor.sh"; echo "EXIT=$?"

Salida esperada (una instrucción de revisión terminada en EXIT=2):

REVISIÓN DE APRENDIZAJE · El agente 'agente-demo' documentó aprendizajes en ...
EXIT=2

Si en vez de eso NO aparece ningún mensaje y sale EXIT=0, casi siempre es que falta jq (revisa el Preflight de arriba) o que la bitácora no quedó "recién escrita". Instala jq y repite este bloque.

Ahora comprueba el caso "no documentó nada". El anti-loop bloquea repetir al mismo agente en 60 segundos, así que usa otro nombre de agente de prueba, definido pero sin bitácora:

touch "$HOME/.claude/agents/agente-demo2.md"   # definido, pero sin bitácora
echo '{"agent_name":"agente-demo2"}' | bash "$HOME/.claude/hooks/learnings-monitor.sh"; echo "EXIT=$?"

Salida esperada: una instrucción que empieza con CHEQUEO DE APRENDIZAJE y EXIT=2.

Por último, comprueba que un agente de sistema (sin definición propia) se ignora en silencio:

echo '{"agent_name":"agente-que-no-existe-9999"}' | bash "$HOME/.claude/hooks/learnings-monitor.sh"; echo "EXIT=$?"

Salida esperada: sin ningún mensaje y EXIT=0.

Y confirma que quedó registrado en settings.json:

grep -q 'learnings-monitor' "$HOME/.claude/settings.json" && echo 'REGISTRADO'

Salida esperada: REGISTRADO.

Por último, limpia los archivos de prueba que creaste (definiciones, bitácoras y los sellos de tiempo anti-repetición):

rm -f "$HOME/.claude/agents/agente-demo"*.md \
      "$HOME/.claude/agents/learnings/agente-demo"*.md \
      "${TMPDIR:-/tmp}/.learnings-monitor-agente-demo"*

Ya que limpiaste, avísale al usuario que quedó instalado y explícale en una línea qué gana con esto.

✅ ¿Cómo sé que funcionó?

De ahora en adelante, cada vez que uno de tus agentes termine una tarea, tu asistente va a asomarse un segundo a la bitácora de ese agente. Si el agente aprendió algo que vale la pena (una corrección tuya, un patrón útil) y no lo anotó, tu asistente lo captura. Si ya lo anotó, revisa que la nota esté bien hecha y no duplique otra.

No tienes que hacer nada especial en el día a día. Solo vas a notar que tus agentes repiten menos los mismos errores y que su memoria de trabajo se va afinando sola. Eso es todo. 🌱