CommunityRedacción y edicióngithub.com

lukehalley/introspect

Habilidad de superación personal agnóstica al agente: lee tus hilos de Claude Code, Codex y Cursor y convierte correcciones recurrentes en reglas en CLAUDE.md / AGENTS.md / .cursor/rules. La parte de escritura de /insights.

¿Qué es introspect?

Introspect es una habilidad agnóstica al agente diseñada para optimizar la configuración de tu agente de IA a lo largo del tiempo, evitando que las mejoras se pierdan entre sesiones. A diferencia de /insights de Claude (que solo lee), Introspect analiza hilos de Claude Code, Codex y Cursor, identifica patrones de correcciones repetidas y preferencias del usuario, y las propone como reglas en los archivos de configuración de cada agente (CLAUDE.md, AGENTS.md, reglas de Cursor). Su principio fundamental es 'patrones, no tácticas': solo se proponen cambios cuando aparecen más de una vez, no están ya documentados y habrían cambiado el resultado. El flujo consta de seis pasos: recolección unificada de hilos, extracción de preferencias duraderas y brechas de configuración, comparación con la configuración existente para evitar duplicados, propuesta limitada a ~5 cambios, aprobación mediante diffs explícitos, y aplicación reversible con un ledger. Cuenta con un modelo de seguridad sólido que exige aprobación humana, tiene umbral de recurrencia, convergencia (refuerza reglas existentes sin duplicar) y reversibilidad. Se ejecuta bajo demanda, mediante programación nativa o cada N sesiones, garantizando que el sistema mejore sin inflarse.

Compatible con✓Claude Code✓Codex CLI✓Cursor
npx skills add lukehalley/introspect

Installed? Explore more Redacción y edición skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

¿Qué hace introspect?

Convierte lo que sucedió en tus hilos de codificación con IA en cambios en cómo trabajan tus agentes para ti — para que tu configuración se acumule en lugar de reiniciarse cada sesión.

Es agnóstico al agente. Lee tus hilos de Claude Code, OpenAI Codex y Cursor, encuentra las pocas cosas que vale la pena cambiar y, con tu aprobación, las escribe en la configuración del agente que realmente dirige las sesiones futuras. Claude Code ya incluye /insights, que lee tus últimos 30 días y te muestra un informe. Esa es la parte de lectura, solo para Claude. Introspect es la parte de escritura en todos los agentes que uses. Youssef lo expresó bien en el hilo del que surgió esto: arregla el sistema una vez para no tener que arreglar la salida mil veces.

La única idea que hace que esto funcione: patrones, no tácticas

El modo de fallo de "¿qué podría haber hecho mejor?" es que saca a relucir tácticas — una mejor bandera para un comando, un enfoque más inteligente para un error. Esas no se acumulan. Desaparecen mañana.

Lo que se acumula es un hábito que sigues repitiendo: la misma corrección que das en tres hilos diferentes, la misma preferencia que repites cada semana, el mismo giro equivocado que da el agente cada vez que toca tu configuración de pruebas. Por lo tanto, toda la habilidad está sesgada hacia la recurrencia:

Un cambio candidato merece su lugar solo cuando aparece más de una vez, aún no está escrito en algún lugar y plausiblemente habría cambiado el resultado. Todo lo demás es ruido — regístralo, no actúes sobre ello.

Esta también es la respuesta honesta a los dos temores que la gente planteó en ese hilo:

  • "Me preocupa acumular malas decisiones / que mi flujo de trabajo se vuelva estúpido." → Nada se escribe sin que veas el diff exacto y lo apruebes. Cada cambio aplicado se registra y es reversible. En caso de duda, propón menos cosas.
  • "¿Simplemente actualiza la habilidad todos los días para siempre? ¿Alguna vez converge?" → Debería converger. Si ya existe una regla, la refuerzas o fusionas; no agregas una segunda. Un día tranquilo produce un conjunto de cambios vacío, y eso es un éxito, no un fracaso.

El pipeline

Recolectar  →  Extraer  →  Comparar vs. configuración existente  →  Proponer conjunto de cambios  →  Aprobar  →  Aplicar + Registrar
(script)      (tú)         (tú, lees la configuración actual)        (tú, con evidencia)          (usuario)     (tú, reversiblemente)

1. Recolectar — ejecuta el script, no vuelvas a analizar nada a mano

scripts/collect_threads.py lee el almacén de hilos de cada agente (JSONL de Claude, archivos de rollout de Codex, SQLite de Cursor), filtra por ventana de tiempo, oculta secretos y emite UN resumen común: por sesión, etiqueta qué agente fue, las indicaciones escritas por el humano, las herramientas utilizadas, dónde fallaron las herramientas y señales ligeras de "fricción" (indicaciones que parecen correcciones, herramientas llamadas muchas veces seguidas).

python3 scripts/collect_threads.py --days 1               # hoy, cada agente instalado (auto)
python3 scripts/collect_threads.py --agent all --days 7   # última semana, fuerza los tres
python3 scripts/collect_threads.py --agent codex --format md
python3 scripts/collect_threads.py --since 2026-07-01 --until 2026-07-05 --format json
python3 scripts/collect_threads.py --project ~/dev/myproject   # un proyecto
python3 scripts/collect_threads.py --selftest             # verificación de cordura de los tres analizadores

--agent por defecto es auto (detecta qué agentes están instalados). Usa --format md cuando lo leas tú mismo; --format json para posprocesamiento. El script nunca decide nada — te da material limpio y normalizado para que emplees tu criterio en lo que importa, no en analizar tres formatos de transcripción diferentes.

2. Extraer — lee el resumen y extrae tres tipos de cosas

Lee el resumen como si fueras el jefe de gabinete del usuario revisando el día en todas sus herramientas. Las preferencias del usuario son lo primero — esta habilidad trata principalmente de aprender cómo ellos gustan trabajar, no de vigilar el comportamiento base de un agente. Separa:

  1. Preferencias duraderas (el evento principal) — el usuario corrigiendo un valor predeterminado o repitiendo cómo le gustan las cosas ("no, usa pnpm", "deja de añadir comentarios", "siempre crea una rama a partir de development primero", "no toques el árbol de trabajo"). Una preferencia que aparece en TUS hilos de Claude y Codex es una señal especialmente fuerte — se trata de ti, no de la herramienta.
  2. Brechas de configuración que hicieron que el agente repitiera trabajo — donde el agente redescubrió o se atascó en múltiples sesiones porque algo no estaba escrito: volver a aprender un comando de compilación, reencontrar un archivo que siempre está en el mismo lugar, faltaba un fragmento de contexto del proyecto. La solución es escribir lo que falta en la configuración del usuario — NO añadir una regla que regañe al agente. Si una repetición es simplemente un comportamiento genérico del agente sin una solución específica del usuario (por ejemplo, "leer un archivo antes de editarlo"), eso no es una regla, es ruido; déjalo fuera.
  3. Flujos de trabajo reutilizables — algo de varios pasos que el usuario realizó más de una vez y que merece ser una habilidad o un comando para que sea un solo paso la próxima vez.

Para cada candidato, anota la evidencia: qué agente, qué sesiones, cuántas veces, una cita corta. Sin evidencia de recurrencia → es una táctica, no un patrón → descártalo.

3. Comparar contra la configuración existente — el paso anti-inflado / convergencia

Antes de proponer nada, lee lo que ya está ahí para el/los agente(s) relevante(s), para que refuerces el sistema en lugar de inflarlo. references/routing.md tiene las ubicaciones exactas de lectura/escritura y formatos para cada agente; la versión corta:

AgenteConfiguración existente para leer (y luego escribir)
Claude~/.claude/CLAUDE.md (global), ./CLAUDE.md, memoria por proyecto ~/.claude/projects/<dir>/memory/, ~/.claude/skills/, ~/.claude/commands/
Codex~/.codex/AGENTS.md (global), <repo>/AGENTS.md (proyecto), habilidades en ~/.agents/skills/
Cursor.cursor/rules/*.mdc (proyecto), .cursorrules heredado, AGENTS.md

Para cada candidato pregúntate: ¿Esto ya está cubierto? Si sí → descártalo, o propón una pequeña edición que haga más precisa la regla existente. Nunca añadas una segunda regla que diga casi lo mismo. Si dos candidatos se superponen, fusiónalos. Prefiere editar sobre añadir.

Consejo multiagente: AGENTS.md es leído por Codex y Cursor, y muchas personas lo enlazan simbólicamente a CLAUDE.md. Si una preferencia es genuinamente universal, prefiere escribirla en un lugar donde todos los agentes la vean (un AGENTS.md, o un enlace simbólico CLAUDE.md↔AGENTS.md) en lugar de duplicarla tres veces. Siempre resuelve los enlaces simbólicos antes de escribir para saber qué archivo estás editando realmente.

4. Proponer un conjunto de cambios — diffs concretos con evidencia, con límite

Presenta un conjunto de cambios: una lista ordenada y escaneable donde cada elemento tiene el agente + archivo objetivo, la edición exacta (un diff o un antes/después claramente marcado), la evidencia y una confianza. Usa el formato en references/changeset-format.md. Dos reglas lo mantienen sensato:

  • Pon un límite. Muestra como máximo ~5 cambios por ejecución, primero los de mayor confianza. Cualquier otra cosa va a una sección de "pendientes" — anotado, no aplicado. Un aluvión de ediciones es cómo los flujos de trabajo se vuelven estúpidos.
  • Clasifica por recurrencia × impacto. Una preferencia expresada tres veces que ahorrará una corrección cada sesión supera a una inteligente única cada vez.

Siempre guarda el conjunto de cambios en un informe con fecha incluso si no se aplica nada, para que haya un registro al que volver (esto responde al "¿guardas las salidas en algún lugar, o solo lees y sigues adelante?" del hilo). Escríbelo en ~/.introspect/reports/YYYY-MM-DD.md.

5. Aprobar — la puerta de entrada

Muestra el conjunto de cambios y deja que el usuario elija qué aplicar: todo, algunos o ninguno. Por defecto, proponer-y-aprobar — no edites la configuración de ningún agente sin un sí explícito. Usa AskUserQuestion (selección múltiple) para que puedan elegir elementos cuando haya varios. Si el usuario ha solicitado explícitamente una ejecución desatendida/programada, consulta "Ejecuciones desatendidas" más abajo.

6. Aplicar + registrar — reversiblemente

Para cada elemento aprobado, escribe en la superficie correcta (formatos completos en references/routing.md):

  • Claude — CLAUDE.md: añade bajo la sección ## correspondiente o edita la regla en su lugar; mantén el estilo de la casa (corto, imperativo, explica por qué).
  • Claude — memoria: crea/añade un archivo de nodo y añade una línea de índice a MEMORY.md; sigue las convenciones feedback_* / project_* / reference_* y los enlaces cruzados [[wikilink]].
  • Claude — habilidad/comando: crea/edita ~/.claude/skills/<name>/SKILL.md o ~/.claude/commands/<name>.md. Si varias sesiones reescribieron el mismo script auxiliar, agrégalo.
  • Codex — AGENTS.md: añade dentro de un bloque gestionado (` … AGENTS.md en ~32 KiB). Prefiere el AGENTS.md en la raíz del proyecto (la aplicación de escritorio no carga de forma fiable el global).
  • Cursor — .cursor/rules/*.mdc: escribe un archivo de regla con frontmatter YAML (alwaysApply: true para preferencias siempre activas, o description: + alwaysApply: false). NO intentes escribir las "Memorias" en la nube de Cursor; usa archivos de reglas. No escribas en el state.vscdb en vivo mientras Cursor se esté ejecutando.

Luego añade una línea al libro de registro en ~/.introspect/ledger.jsonl — un objeto JSON por cambio aplicado: {date, agent, target_file, kind, summary, evidence, sessions, undo_hint}. El libro de registro te permite (a) mostrar cómo se ha acumulado la configuración con el tiempo, y (b) deshacer un cambio más adelante. Antes de editar un archivo existente, anota su estado anterior en undo_hint (o guarda un .bak).

Modelo de seguridad (léelo — es la razón por la que esto es seguro de ejecutar a diario)

  • Proponer, no imponer. Puerta de aprobación activada por defecto. El usuario ve cada diff.
  • Umbral de recurrencia. No propongas a partir de una sola ocurrencia. Hábitos, no tácticas.
  • Converger, no agitar. Refuerza/fusiona reglas existentes en lugar de añadir casi duplicados. Una ejecución que no cambia nada está bien y se espera en un día tranquilo.
  • Limita el radio de explosión. Máximo ~5 cambios por ejecución; el resto a pendientes.
  • Las reglas tratan sobre el usuario, no sobre el agente. Captura cómo quiere trabajar el usuario. No fabriques reglas que simplemente reiteren la competencia base de un agente (como "leer antes de editar") — eso es inflado. Una señal de "el agente se atascó / se repitió" merece un cambio solo cuando anotar una parte de la configuración del usuario evitaría la repetición.
  • Nunca almacenes secretos. El recolector oculta formas comunes de claves/tokens, pero mantente alerta: nunca copies una clave de API, contraseña, valor .env o token en una regla o informe. Si ves uno, déjalo fuera y (si parece activo) avísale al usuario.
  • Reversible. Todo lo aplicado está en el libro de registro con una pista de deshacer.
  • Superficie correcta, alcance correcto. Preferencias para todo el usuario → el archivo global de ese agente. Datos específicos del proyecto → la configuración de ese proyecto. No pongas trivialidades del proyecto en un archivo global.

Disparadores — tres formas de ejecutar

  1. Bajo demanda. "revisa mis hilos", "ejecuta introspect", "qué seguí repitiendo esta semana en Claude y Codex", "convierte las correcciones de hoy en reglas". Ventana por defecto: hoy.
  2. Diario / programado (nativo del arnés). Registra la ejecución a través del programador nativo del arnés — la habilidad schedule o la herramienta de rutina CronCreate — no un cron del SO, launchd o un bucle de shell. La programación nativa ejecuta la rutina dentro del arnés con las mismas herramientas y permisos, y el usuario la gestiona con /schedule. Un buen valor predeterminado es una vez al día por la noche durante la ventana de ese día.
  3. Cada N sesiones / por fricción (opcional). Algunas personas (ver buildooor en el hilo fuente) prefieren activar esto cuando algo ha ido mal o cada ~10 sesiones en lugar de por reloj. Conéctalos como un hook Stop que cuente las invocaciones y notifique después de N. Ofrécelo; nunca instales un hook sin aprobación.

Ejecuciones desatendidas

Si se invoca mediante una rutina programada sin presencia humana, no apliques cambios silenciosamente a la configuración de ningún agente. En su lugar: ejecuta el pipeline, escribe el informe con fecha que contenga el conjunto de cambios propuesto en ~/.introspect/reports/ y muestra un breve resumen (a través de la notificación de la rutina) para que el usuario pueda aprobar en su próxima sesión interactiva. La única categoría segura de aplicar automáticamente sin supervisión es un nuevo nodo de memoria de Claude que no duplique nada — e incluso entonces, regístralo. Mantén la acumulación bajo control humano; ese es el objetivo.

Referencias

  • references/routing.md — fuentes de lectura por agente + superficies de escritura + formatos exactos en disco (CLAUDE.md, memoria, AGENTS.md, .cursor/rules/*.mdc) y los esquemas de transcripción que utiliza el recolector.
  • references/changeset-format.md — las plantillas de conjunto de cambios + informe + libro de registro.
  • scripts/collect_threads.py — el recolector multiagente (ejecuta --selftest para verificarlo).

Repitiendo el bucle central, porque es todo: recolecta los hilos de cada agente → encuentra los patrones recurrentes (no las tácticas únicas) → comprueba que no estén ya escritos → propón un conjunto de cambios pequeño, limitado y respaldado por evidencia → aplica solo lo aprobado en la configuración del agente correcto → regístralo reversiblemente.

Skills relacionados