paper-to-notebook

Convierte un artículo de investigación —en formato PDF, HTML o texto plano (LaTeX, Markdown, etc.)— en un cuaderno de aprendizaje interactivo y ejecutable con marimo. Úsalo cuando te pidan crear un cuaderno explicativo, enseñar un artículo de forma interactiva o construir un recorrido guiado de una publicación. No lo uses para revisiones bibliográficas de múltiples artículos ni para salidas que no sean marimo, a menos que el usuario cambie explícitamente el formato.

¿Qué es paper-to-notebook?

Esta habilidad guía a un agente de IA para transformar un solo artículo de investigación en un cuaderno marimo ejecutable y educativo. El cuaderno no es un simple resumen, sino una lección interactiva que incluye explicaciones en lenguaje sencillo, widgets interactivos para explorar conceptos y verificaciones informales a lo largo del camino. El objetivo es que el cuaderno sea inteligible y representativo del artículo, evitando prosa genérica de IA. El agente sigue un flujo de trabajo de cinco pasos: ingestión del artículo completo (PDF, HTML o texto plano), extracción de estructura, ecuaciones y figuras, planificación de una ruta de aprendizaje adaptativa, generación del cuaderno marimo siguiendo patrones y habilidades específicas (como `marimo-notebook-patterns`), y validación de que el cuaderno se ejecute correctamente. La habilidad está diseñada para plataformas como Claude Code, Cursor o Codex, y se basa en habilidades auxiliares de marimo para garantizar calidad y coherencia. Entre sus características clave destacan la explicación adaptativa a múltiples niveles (desde niño hasta experto), la inclusión de una prueba final de cinco preguntas, y la capacidad de manejar ecuaciones en LaTeX, figuras y referencias. La habilidad también prioriza la transparencia: marca explícitamente cualquier contenido que vaya más allá del artículo original (como "Nuestra demo" o "Suposición simplificada") y proporciona metadatos completos del artículo. En resumen, es una herramienta poderosa para crear materiales didácticos interactivos a partir de publicaciones científicas, ideal para educadores, estudiantes e investigadores.

Compatible con✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ericmjl/paper-to-notebook-skill/tree/main

Installed? Explore more Investigación y análisis de datos skills: affaan-m/uspto-database, affaan-m/scholar-evaluation, affaan-m/literature-review · View all 6 →

Preguntar en tu IA favorita

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

Documentación

De artículo a cuaderno

Guía a un agente para convertir un artículo en un cuaderno marimo ejecutable que ayude al lector a comprender dicho artículo. El cuaderno es una lección, no una página de resumen: explicaciones en lenguaje sencillo, widgets interactivos cuando sean útiles y verificaciones informales a lo largo del camino. La redacción debe ser inteligible y representativa del artículo, no una prosa genérica de IA.

Este archivo es un esqueleto. Muchos detalles se completarán más adelante. Los elementos marcados como PENDIENTE aún no están decididos o solo están esbozados.

Contrato

EntradaUn artículo en PDF, HTML o texto plano (LaTeX, Markdown, etc.). La ruta, URL o identificador es válido siempre que se pueda obtener el texto completo.
SalidaUn cuaderno marimo ejecutable (*.py) que el lector pueda abrir con uvx marimo edit --sandbox ….

Entradas opcionales para solicitar si faltan (no bloquees si el usuario solo proporciona el artículo):

  • Audiencia inicial o "adapta sobre la marcha". Suposición predeterminada: estudiante de licenciatura a posgrado, más profesionales en activo que se inicien en este artículo o campo, con conocimientos científicos generales. PENDIENTE: ajustar la suposición predeterminada.
  • Contexto adicional: información complementaria, artículos citados u otras fuentes que el usuario quiera considerar como base (no solo conocimiento general).
  • Profundidad: recorrido completo vs. métodos, resultados o una figura.
  • Ruta de salida y restricciones de ejecución.

No trates esta habilidad como una herramienta para revisar una literatura extensa. Eso es otro trabajo.

Flujo de trabajo

1. Ingestar el artículo (PDF / HTML / texto plano)
2. Extraer estructura, términos, ecuaciones, figuras y lagunas
3. Planificar la ruta de aprendizaje
4. Generar el cuaderno marimo
5. Validar que se ejecute con `uv run`, y luego entregar

1. Ingestar el artículo

Obtén el texto completo, no solo un resumen. Ramifica según el tipo de entrada; coloca las notas específicas del formato en resources/ y cualquier ayuda en scripts/ (siempre con uv run, nunca con un pip install global).

  • PDF: PENDIENTE: cómo obtener y analizar (texto, matemáticas, figuras, orden de lectura). Señala fallos en lugar de adivinar.
  • HTML: PENDIENTE: cómo obtener y analizar (texto principal vs. navegación/barra, MathJax/MathML, figuras).
  • Texto plano (LaTeX, Markdown, etc.): PENDIENTE: cómo seguir inclusiones, bibliografía y archivos de figuras; cómo mantener las etiquetas de ecuaciones y figuras.

Registra el título del artículo, autores, año y un enlace o identificador estable cuando esté disponible.

2. Extraer estructura, ecuaciones y figuras

Construye una imagen intermedia del artículo antes de escribir cualquier cuaderno. PENDIENTE: definir las formas de datos para este paso (ver también la idea de que las estructuras intermedias sólidas facilitan el resto).

Extrae al menos:

  • Problema y contribución, en tus propias palabras.
  • Perfil de prerrequisitos: qué sabe, qué no sabe y qué se le debe enseñar a un lector en cada nivel (consulta Explicar en múltiples niveles).
  • Conceptos clave y términos que el artículo usa pero no define (metadatos centrales o términos del campo). Ejemplo planteado en la discusión de diseño: un artículo sobre ataques al corazón que nunca explica "infarto de miocardio".
  • Ecuaciones clave, numeradas como en el artículo, con variables.
  • Figuras clave: qué codifica cada una, cómo está etiquetada y si los datos subyacentes parecen estar disponibles.
  • Puntos de riesgo para la generación: LaTeX pesado o matemáticas, etiquetas de figuras con letras griegas, otro texto no ASCII.
  • Lagunas evidentes en métodos o informes. No inventes resultados experimentales faltantes.

Clasifica la madurez del campo (establecido, emergente, interdisciplinario o mixto) usando la rúbrica y la muestra ligera de literatura en resources/field-maturity.md. Registra la clase, la evidencia y qué componentes de incorporación de vocabulario del cuaderno son necesarios (glosario, desambiguación, terminología en evolución).

PENDIENTE: si clasificar el artículo como similar a un algoritmo (ejercicios de codificación, reconstrucción inversa del método) vs. similar a un concepto (widgets explicativos escritos por el agente). Ejemplos de química usados en la discusión: balance de masa, cinética de reacción, un nuevo modelo cinético.

3. Planificar la ruta de aprendizaje

Diseña una ruta que un humano pueda seguir en una sola sesión. PENDIENTE: duración objetivo.

No bloquees todo el cuaderno a un solo nivel de lectura. Planifica una explicación adaptativa: el lector debe poder obtener una versión más simple o más avanzada de un pasaje difícil. PENDIENTE: dirección predeterminada: empezar simple y añadir complejidad, o empezar avanzado y bajar de nivel cuando el lector esté confundido. Ambas se propusieron; ninguna se eligió. Los conceptos centrales reciben una escalera completa (consulta Explicar en múltiples niveles).

Estructura sugerida (ajusta según el artículo):

  1. Por qué este artículo es importante.
  2. Intuición o ejemplo sencillo antes de la notación pesada.
  3. Configuración: notación, suposiciones, términos e incorporación de vocabulario del campo (glosario; desambiguación o terminología en evolución cuando sea necesario; consulta resources/field-maturity.md).
  4. Idea central, vinculada a una ecuación o figura.
  5. Paso a paso alineado con el artículo.
  6. Verificaciones informales después de los segmentos, ajustadas al nivel de explicación: explicar, predecir, aplicar o criticar (no evaluación formal; la evaluación formal está fuera del alcance).
  7. Para lectores de posgrado y superiores: puntos de crítica: ¿el diseño experimental aborda la pregunta planteada? ¿El marco estadístico es una elección adecuada? ¿Qué falta? ¿Qué suposiciones está haciendo el lector?
  8. Resumen: limitaciones, qué leer a continuación, cita.
  9. Prueba final: cinco preguntas de opción múltiple sobre el artículo, siempre como última sección (consulta Prueba final).

PENDIENTE: hasta dónde llegan la crítica, el análisis de la sección de resultados y las indicaciones de interpretación de figuras en la primera versión, frente a un recorrido guiado simple.

Si el usuario proporcionó fuentes adicionales, planifica dónde se citarán en el cuaderno y cómo se distinguirá la evidencia con fuente del conocimiento general. PENDIENTE: el mecanismo para esa distinción, y si un mapa conceptual pequeño o una "wiki de conocimiento" pertenece aquí más adelante.

4. Generar el cuaderno marimo

Comienza desde una plantilla en assets/ cuando exista (PENDIENTE: añadir assets/notebook_template.py). Escribe un cuaderno marimo que se pueda abrir con uvx marimo edit --sandbox.

Sigue las habilidades de marimo instaladas en .agents/skills/ (una celda import marimo as mo; nombres únicos de nivel superior; widgets que impulsan la exploración, no la decoración):

  • marimo-notebook-patterns: leer antes de escribir o editar cualquier celda del cuaderno (reglas de importación y parámetros de celda, variables únicas, firmas de API de widgets, errores comunes).
  • marimo: referencia más amplia de autoría, incluido el emparejamiento en vivo y la incrustación de cuadernos en la web.
  • awesome-marimo-notebook: cómo hacer que un cuaderno explicativo de artículo o conjunto de datos sea atractivo y pulido.

Declara las dependencias en un bloque de metadatos de script en línea PEP 723 al principio del archivo (# /// script … # ///), listando marimo y cada paquete que importe el cuaderno, cada uno con una versión mínima (ej. numpy>=2.0). Esto permite que uv run y marimo edit --sandbox los instalen.

Termina el cuaderno con el cuestionario de cinco preguntas descrito en Prueba final.

Requisitos estrictos para la prosa:

  • Inteligible y representativa de las ideas centrales del artículo.
  • No es "basura de IA" genérica. Si una frase podría haberse escrito sobre cualquier artículo, reescríbela.
  • Define símbolos y términos del campo cuando aparezcan por primera vez, o apunta a un glosario / tooltip / ayuda de resaltar para explicar. Sigue resources/field-maturity.md para secciones de incorporación específicas de madurez. PENDIENTE: cuáles de esas ayudas al lector enviar primero. "Marimo Lens" se mencionó como posible opción para resaltar y explicar; confirma el nombre real de la función y la compatibilidad del anfitrión.

Otras reglas de generación:

  • Ecuaciones: LaTeX en mo.md; widgets sobre parámetros cuando eso genere intuición.
  • Figuras: reproduce o simplifica cuando los datos lo permitan; enlaza al número de figura del artículo. Si los datos no están disponibles, dilo; no inventes gráficos. PENDIENTE: hasta dónde llegar con estimaciones basadas en visión o interpretaciones de figuras escritas por el lector en v1.
  • Recorridos de figuras: cuando una figura clave necesite un recorrido guiado paso a paso, lee resources/dynamic_figure_annotation.md (FigureAnnotatorWidget más una ayuda de auditoría de coordenadas en scripts/).
  • Conceptos centrales (1–3 por cuaderno) reciben una escalera de explicación (Explicar en múltiples niveles).
  • Verificaciones informales: preguntas cortas, no evaluación calificada. Usa el patrón show_check en resources/explanation-levels.md §9 (radio, una respuesta numérica con tolerancia, o una respuesta abierta con una respuesta modelo).
  • Modo de dominio del paso 2: ejercicios de codificación y reconstrucción de métodos para artículos similares a algoritmos; widgets explicativos/interactivos escritos por el agente para artículos similares a conceptos (por ejemplo, un mecanismo en una celda).
  • Etiqueta cualquier cosa que vaya más allá del artículo ("Nuestra demo", "Suposición simplificada").
  • Incluye metadatos del artículo y citas.

5. Validar y entregar

Mínimo (esqueleto v1): el cuaderno debe ejecutarse.

uv run scripts/validate_notebook.py ruta/al/cuaderno.py --run

Verifica la sintaxis de Python, ejecuta marimo check --strict y, con --run, ejecuta el cuaderno de principio a fin. Corrige cualquier problema reportado antes de la entrega.

Informa al usuario:

  • Ruta al cuaderno y el comando para abrirlo (uvx marimo edit --sandbox …).
  • Audiencia asumida y qué se simplificó.
  • PENDIENTES y lagunas conocidas (incluyendo datos faltantes o términos indefinidos).
  • Referencia del artículo (título, autores, año, enlace).

Validación planificada más allá de "se ejecuta" (no todo es necesario para un primer esbozo):

  • La redacción es inteligible y representativa, no basura.
  • Los conceptos centrales y términos de metadatos realmente se explican.
  • No hay números o afirmaciones inventados.
  • El cuaderno termina con el cuestionario de cinco preguntas, y sus preguntas tratan sobre las afirmaciones, hallazgos y limitaciones del artículo, no sobre sus detalles de implementación.
  • Cada escalera explica el mismo mecanismo central en todos los niveles; cada simplificación en la escalera se corrige en un nivel posterior; se indica el límite de la analogía.
  • Incorporación de vocabulario: para los casos de estudio establecido, emergente e interdisciplinario, verifica la cobertura del glosario y, cuando sea necesario, las secciones de desambiguación o terminología en evolución según resources/field-maturity.md §8.
  • PENDIENTE: evaluaciones basadas en aserciones o preguntas de oro; ejecuciones con múltiples modelos (se ofrecieron modelos chinos de peso abierto y modelos Claude); LLM como juez solo como primer filtro más confiable para "esto es malo" que para "esto es bueno"; prueba humana con un artículo desconocido; revisión de experto en el dominio después de una prueba de humo en su propio campo.
  • PENDIENTE: un conjunto de artículos de prueba compartido que cubra trabajo establecido, emergente e interdisciplinario, y subdominios, no solo un campo. Se ofreció un artículo sobre gripe de 2016 como un posible caso; la lista no está elegida.

Explicar en múltiples niveles

Las ideas centrales reciben una escalera de explicación: un mecanismo explicado en cinco niveles, cada uno escrito para un lector con prerrequisitos específicos. Está modelada en la serie 5 Niveles de WIRED. Los nombres de los niveles son abreviaturas. Lo que define un nivel es el conocimiento del tema y las matemáticas que el lector aporta, y la precisión que el nivel añade.

Nivel (abreviatura)Conocimiento del tema asumidoMatemáticas asumidasAñade al mecanismo
1 · NiñoExperiencia cotidianaContar y compararCausa y efecto, en términos cotidianos
2 · AdolescenteAlfabetización científica generalAritmética, porcentajes, gráficos simplesUn ejemplo sencillo con números reales pequeños
3 · LicenciaturaUn curso introductorio en el campoHerramientas introductorias del campoLa ecuación o algoritmo exacto, cada símbolo definido
4 · PosgradoMétodos estándar de un área adyacenteSigue las derivaciones del artículoSuposiciones, cuándo se cumple, qué falla y cómo se compara con el enfoque estándar
5 · ExpertoLiteratura de este subcampoFormalismo completoQué es nuevo, compensaciones, límites y preguntas abiertas

Reglas:

  1. Perfil de prerrequisitos por artículo (Fase 1): para cada nivel, qué sabe el lector, qué no sabe y qué debe enseñar el cuaderno. Mapea el contexto declarado del usuario (de las entradas opcionales del Contrato) a un nivel.

  2. Un mecanismo en cada nivel. Escribe primero una columna vertebral del mecanismo de una oración; cada nivel añade precisión. Ningún nivel sustituye un mecanismo más vago o diferente.

  3. Preciso en cada nivel. Simplifica omitiendo cosas, nunca diciendo algo falso. Registra cada simplificación en un libro de contabilidad y corrígela en un nivel posterior.

  4. Mapea la analogía y declara su límite. Lleva un ancla hasta el Nivel 3, mapea sus partes en las partes del método y di dónde se rompe en el Nivel 3.

  5. Verificaciones ajustadas al nivel:

    • Niño: explicar.
    • Adolescente: predecir.
    • Licenciatura: aplicar.
    • Posgrado: aplicar y criticar suposiciones.
    • Experto: criticar.

    Cada verificación tiene una respuesta esperada, el razonamiento y la ubicación en el artículo.

  6. Las escaleras son para lo central: 1–3 conceptos por cuaderno.

  7. Fundamentadas: cita ubicaciones del texto que leíste y nunca adivines. Marca las lagunas [cita: …] durante el borrador y resuélvelas antes de enviar.

  8. Los números llevan sus condiciones: la tabla, cohorte, conjunto de características o rango van en la misma oración. En pruebas con artículos reales, ambas ideas erróneas que causaron las escaleras provinieron de un número despojado de su condición.

En el cuaderno: añade un selector de nivel cerca de la parte superior. Cada escalera recibe mo.ui.tabs que se abre en el nivel del lector, con su verificación debajo.

Leer antes de escribir: resources/explanation-levels.md tiene las plantillas de perfil y libro de contabilidad, un ejemplo trabajado, celdas de marimo probadas y trampas. resources/examples/ tiene dos escaleras más completas,

...

[truncado para traducción]

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

Skills relacionados