checkpoint

Una skill para Claude Code que guarda el estado de tu trabajo antes de perderlo.

Read this in English

Instalar — pegale esto a Claude Code

Instalá la skill checkpoint: cloná https://github.com/masudj/checkpoint-skill
en ~/.claude/skills/checkpoint

Reiniciá Claude Code y escribí /checkpoint. Nada más que hacer.

---

Estás por hacer /compact (comprimir la conversación para poder seguir, cuando se llena la ventana de contexto). O son las once de la noche y cerrás la sesión. Escribís /checkpoint y, en un minuto, queda escrito:

• Dónde estás parado — qué funciona, qué todavía no, qué quedó a mitad de camino.
• Qué falta, ordenado por prioridad, con una línea de contexto en cada cosa.
• Qué decidiste y por qué — lo que no queda registrado en ningún commit.
• Qué está sin commitear, agrupado por tema y con el mensaje de commit ya redactado.
• Un prompt listo para pegar en la sesión siguiente, con lo que costó descubrir marcado para que nadie lo vuelva a investigar.

Mañana, o dentro de tres semanas, o en una sesión que arranca sin nada de contexto: se abre un solo archivo y en cinco minutos estás produciendo de nuevo.

Sin esto, lo que se pierde no son los commits — es el razonamiento que los produjo.

Qué escribe y dónde

Qué	Dónde	Cuándo
Un snapshot del estado	docs/checkpoints/AAAA-MM-DD-slug.md	Siempre
Un índice de todos los checkpoints, el más nuevo arriba	docs/checkpoints/README.md	Siempre
Una entrada de CHANGELOG fechada	CHANGELOG.md → [Unreleased]	Solo si cambió algo que un usuario nota
Un prompt para pegar en la sesión siguiente	En el chat	Siempre

El snapshot es el documento central: contiene qué pasó, qué funciona y qué no, los pendientes ordenados por prioridad, las decisiones que se tomaron y por qué, la deuda conocida, y — lo más importante — una sola línea con el próximo paso.

No es un release. Es un savepoint, como en un videojuego.

Por qué

Hay dos formas de perder el trabajo de una sesión, y ninguna se siente como una pérdida en el momento.

El compact. Se llena la ventana de contexto, compactás, y desaparece la parte cara: el hallazgo que costó dos horas, lo que estaba trabado esperando a otra persona, la trampa del build que ya pisaste una vez. Los commits sobreviven. El razonamiento que los produjo, no.

El árbol sucio. Sobre 78 checkpoints reales en 11 repositorios, un tercio se escribió con cero commits: todo el trabajo de esas sesiones estaba sin commitear. Ese trabajo es invisible para git log, así que cualquier herramienta que resuma a partir del log describe una sesión en la que no pasó nada.

Esta skill lee las dos cosas: el log y el working tree.

Qué NO hace

No escribe en git. Nunca hace commit, add, push, tag, stash, branch ni reset.

Lo que sí hace es mostrarte lo que está sin commitear, clasificado y con los commits ya armados: agrupados por tema, con el mensaje sugerido y los paths exactos. La decisión de ejecutarlos es tuya o del agente que te esté ayudando. Así, hacer un checkpoint se convierte en el momento natural para decidir si commitear — sin que nadie toque tu repo por su cuenta.

Clasifica cada archivo sucio en cuatro grupos:

• Vale commitear — trabajo terminado que forma una unidad coherente.
• No commitear — secretos (.env, *.pem, *.key), artefactos de build, basura temporal. Si encuentra un secreto trackeado, eso pasa a ser el titular del reporte.
• Quedó a medias — trabajo a mitad de camino o roto. No se propone para commit; se describe en el snapshot para que la próxima sesión sepa qué es y si vale la pena conservarlo.
• Necesita una decisión tuya — trabajo terminado cuya relevancia está en duda: el artefacto de un enfoque que después descartaste, un directorio pesado de imágenes, un documento que otro ya reemplazó. No lo commitea, no lo tira, y no decide por vos.

También te avisa si tenés commits sin pushear, sin pushearlos.

Instalación

Personal, disponible en todos tus proyectos:

git clone https://github.com/masudj/checkpoint-skill ~/.claude/skills/checkpoint

O atada a un proyecto, versionada con el repo:

git clone https://github.com/masudj/checkpoint-skill .claude/skills/checkpoint

Reiniciá Claude Code.

Cómo se usa

Escribí /checkpoint, o simplemente decilo con tus palabras: "hagamos un checkpoint", "guardá el estado", "ordenemos esto antes de que se pierda".

Si le contás al agente que estás por compactar o por cerrar la sesión, en general va a proponer la skill por su cuenta. Lo que no pasa es que se interponga: si escribís /compact, compacta y listo — nada la dispara automáticamente. Vale la pena tomar la costumbre de hacer el checkpoint primero.

Requisitos

Ninguno.

Git es opcional: en un directorio que no es repositorio, ancla el rango a la fecha del checkpoint anterior y lee el sistema de archivos. El CHANGELOG.md también es opcional — solo lo toca si ya existe, y lo crea únicamente cuando hay algo real para escribirle.

Cómo se ve

Checkpoint — Contenido real cableado al reproductor del curso

Se conectó el catálogo a datos reales y se cerró la compuerta de acceso.

Escrito
  docs/checkpoints/2026-08-26-contenido-real.md
  CHANGELOG.md → [Unreleased], 3 entradas
  docs/checkpoints/README.md → índice actualizado

Git — mi-app (directorio actual)
  main · 2 commits sin pushear · 14 archivos sin commitear
  Vale commitear:
    src/catalog/*, tests/catalog.test.ts → "feat: catálogo contra datos reales"
    docs/img/                            → "docs: capturas del reproductor"
  Necesita una decisión tuya:
    docs/guia-vieja.html (1,0 MB) → documenta el enfoque que se descartó en julio
  No commitear: .env.local, dist/
  Quedó a medias: src/experimental/player-v2 — migración incompleta, ver snapshot

Próximo paso
  Cerrar #142 — la compuerta todavía deja pasar una compra reembolsada.

Y después el prompt de continuación, en un bloque de código, último — justo donde vas a poner el cursor para copiarlo.

Idioma

El archivo de la skill (SKILL.md) está en inglés, pero la salida no. El snapshot, el CHANGELOG y el prompt se escriben en el idioma en el que estés hablando. Si no queda claro, usa el idioma que ya tenga el CHANGELOG.md o el README.md del repositorio.

Decisiones de diseño

• Un checkpoint no es un release, pero todo lleva fecha igual. Las entradas van a [Unreleased], cada checkpoint en su propia subsección ### AAAA-MM-DD — [Unreleased] significa todavía no salió, nunca sin fecha. Cuando algo efectivamente sale a producción, el bloque entero se promueve a un encabezado fechado, con los días adentro.
• No escribir en el CHANGELOG es un resultado válido. Las sesiones de documentación, investigación, refactor o herramientas internas muchas veces no cambian nada observable. Escribir una entrada igual es cómo un changelog se convierte en ruido.
• Cada snapshot guarda el SHA de HEAD en su frontmatter. Es el ancla que usa el checkpoint siguiente para calcular su rango, en vez de adivinar por fecha de modificación de archivos.
• El trabajo no siempre pasa donde estás parado. Si la sesión editó una skill global, un dotfile o un repositorio hermano, el checkpoint reporta el estado de ese lugar también. Si no, describiría una sesión en la que no pasó nada mientras el trabajo real quedó sin commitear un directorio más allá.
• Lo sin commitear es la parte frágil. Los commits sobreviven solos. Todo lo demás vive o muere según si el snapshot lo menciona.

Licencia

MIT