Aprende

aprende — Learn from this conversation / Aprende de esta conversación

> EN — A skill that turns finished conversations into durable, structured > learnings: memories, anti-patterns (Reflexion-style), skill stubs, and > project-doc updates. Confirmation-first. Never auto-writes. > > ES — Un skill que convierte conversaciones terminadas en aprendizajes > durables y estructurados: memorias, anti-patrones (estilo Reflexion), stubs > de skills, y actualizaciones a project-docs. Confirmación primero. Nunca > escribe automáticamente.

---

1. Purpose / Propósito

EN. Coding agents repeat mistakes across sessions because the corrections a user makes in one conversation evaporate when the session ends. aprende fixes that. When invoked, it reviews the current conversation, identifies what is worth preserving across four well-defined categories, and writes those learnings to the right files — in the format the user's existing memory system already reads — only after the user picks the items to keep.

Guiding principle: a false positive locked into memory is worse than repeating a correction three times. Be liberal at surfacing candidates, strict at confirming them, and conservative at writing them. Prefer false negatives.

ES. Los agentes de código repiten errores entre sesiones porque las correcciones que el usuario hace en una conversación se evaporan cuando esa sesión termina. aprende arregla eso. Al activarse, revisa la conversación actual, identifica qué vale la pena preservar a través de cuatro categorías bien definidas, y escribe esos aprendizajes en los archivos correctos — en el formato que ya usa el sistema de memoria del usuario — solo después de que el usuario elija qué guardar.

Principio rector: un falso positivo cristalizado en la memoria es peor que repetir una corrección tres veces. Sé liberal al proponer candidatos, estricto al confirmarlos, y conservador al escribirlos. Prefiere los falsos negativos.

---

2. When to invoke / Cuándo activarse

EN — Trigger on any of:

• The user types /aprende or /learn (the English alias).
• The user types phrases like: "reflect on this", "save what we learned",

"remember this for next time", "let's capture that", "make a note of this", "don't forget X next session".

• The user has corrected the agent on the same thing twice in a session —

proactively suggest running /aprende (one line, in the assistant turn); do not run it without permission.

• The session is wrapping up (the user says "we're done", "good, ship it",

"commit and push") and signals have been captured by the optional PostToolUse hook (.aprende-signals.md exists with content).

ES — Activa con cualquiera de estos:

• El usuario escribe /aprende o /learn (alias en inglés).
• El usuario escribe frases como: "reflexiona sobre esto", "guarda lo que

aprendimos", "recuérdalo para la próxima", "captura esto", "que no se nos olvide X".

• El usuario corrigió al agente sobre lo mismo dos veces en la sesión —

proactivamente sugiere correr /aprende (una línea, en el turno del asistente); no lo ejecutes sin permiso.

• La sesión está cerrando ("ya terminamos", "listo, súbelo", "commit y push")

y el hook PostToolUse capturó señales (existe .aprende-signals.md con contenido).

---

3. The four categories / Las cuatro categorías

| # | Category / Categoría | Lives at / Vive en | When / Cuándo | |---|---------------------|--------------------|---------------| | 1 | memory | ~/.claude/projects//memory/.md (metadata.type: user \| project \| reference \| feedback) | Durable facts, preferences, project context, external references. Hechos durables, preferencias, contexto del proyecto, referencias externas. | | 2 | lesson (anti-pattern) | Same folder, metadata.type: lesson | A mistake happened. We know what, why, and how to avoid. Un error pasó. Sabemos qué, por qué, y cómo evitar. | | 3 | skill (stub) | ~/.claude/skills//SKILL.md or ./.claude/skills// | A reusable multi-step workflow surfaced. Apareció un workflow multi-paso reutilizable. | | 4 | project-doc | ./CLAUDE.md + ./AGENTS.md (dual-write) — or ~/.claude/CLAUDE.md + ~/.claude/AGENTS.md for global | Build commands, repo conventions, gotchas worth telling every future agent. Comandos de build, convenciones del repo, gotchas que vale la pena contarle a cada agente futuro. |

One example each / Un ejemplo de cada:

• memory — "User prefers pnpm over npm in all JS projects." / "El usuario prefiere pnpm sobre npm en todos los proyectos JS."
• lesson — "Assumed localStorage works inside a WebView purchase flow; it does not — caused silent purchase failures. Use IndexedDB instead." / "Asumí que localStorage funciona dentro de un flujo de compra en WebView; no funciona — causó fallos de compra silenciosos. Usa IndexedDB."
• skill — /verify-rls — a 6-step Supabase RLS verification workflow that came up three times today. / un workflow de 6 pasos para verificar RLS en Supabase que apareció tres veces hoy.
• project-doc — "Run tests with pnpm run test:unit, not npm test. The latter triggers the e2e suite which needs a running DB." / "Corre tests con pnpm run test:unit, no npm test. El último dispara la suite e2e que necesita una DB activa."

---

4. Workflow (5 passes) / Workflow (5 pases)

Run these in order. Do not skip. Each pass has a hard output shape.

Ejecuta en orden. No saltes pasos. Cada pase tiene una forma de output estricta.

Pass A — Scan / Escaneo

EN. Read the conversation transcript silently. Look for the patterns in references/signal-patterns.md (multi-language). The high-signal classes:

1. Explicit user corrections (high confidence) — "no, do X instead",

"actually that's wrong", "always do Y", "never do Z", "stop doing W", "the convention here is", and their Spanish counterparts in references/signal-patterns.md.

1. Error → fix sequences (high) — a tool call failed, a different call

succeeded shortly after. The delta between them is the lesson.

1. Repeated attempts (medium) — three or more Edits to the same file in a

row, three or more Bash retries of the same command with variations.

1. **User explanations of why** (high — Reflexion gold) — "the reason is",

"because", "the gotcha is", "porque", "el detalle es", "la trampa es".

1. Workflows the user described step-by-step (medium, candidate for a

skill stub) — four or more sequential tool calls that the user explicitly walked through.

If ~/.claude/projects//.aprende-signals.md exists and is non-empty, prepend its contents to the scratch list — those are signals captured by the PostToolUse hook earlier in this session.

ES. Lee la transcripción de la conversación en silencio. Busca los patrones de references/signal-patterns.md (multi-idioma). Las clases de alta señal:

1. Correcciones explícitas del usuario (high) — "no, mejor X", "eso está

mal", "siempre Y", "nunca Z", "deja de hacer W", "la convención aquí es".

1. Secuencias error → arreglo (high) — una llamada falló, otra distinta

funcionó después. El delta es la lección.

1. Intentos repetidos (medium) — tres o más Edits al mismo archivo en

fila, tres o más reintentos de Bash con variaciones.

1. **Explicaciones de por qué del usuario** (high — oro de Reflexion) —

"porque", "el detalle es", "la trampa es", "the reason is".

1. Workflows que el usuario explicó paso a paso (medium, candidato a

skill stub) — cuatro o más llamadas secuenciales que el usuario detalló.

Si ~/.claude/projects//.aprende-signals.md existe y no está vacío, anteponé su contenido a la lista — son señales capturadas por el hook PostToolUse antes en esta sesión.

Pass B — Generate / Generar

For each signal, draft a candidate item with this internal shape:

Para cada señal, draftea un candidato con esta forma interna:

{
  "category": "memory" | "lesson" | "skill" | "project-doc",
  "title": "",
  "rationale": "",
  "confidence": "high" | "medium" | "low",
  "source_excerpt": ""
}

Confidence derivation (mandatory):

• high — explicit user feedback in the conversation, OR error→fix with a

user explanation, OR the same correction repeated by the user.

• medium — inferred pattern, single user comment without elaboration,

error→fix without explanation.

• low — guess, single observation the model thinks might matter.

Be liberal at this pass. It's cheaper to filter at confirmation than to miss a real learning. Cap the candidate list at 15 items per run; if you find more, keep the 15 highest-confidence and tell the user to re-run.

Sé liberal en este pase. Es más barato filtrar en la confirmación que perder un aprendizaje real. Limita la lista a 15 items por corrida; si encuentras más, conserva los 15 de mayor confidence y dile al usuario que vuelva a correr.

Pass C — Dedup / Deduplicar

Before showing the list, check overlaps without dropping silently:

Antes de mostrar la lista, chequea overlaps sin dropear en silencio:

1. Read ~/.claude/projects//memory/MEMORY.md if it exists. For each

candidate, do a title + topic similarity check against existing bullets.

1. For skill candidates, ls ~/.claude/skills/ and ls ./.claude/skills/

(if the project-local folder exists).

1. For project-doc candidates, grep -i against ./CLAUDE.md and

./AGENTS.md (if either exists).

1. If a candidate looks like a near-duplicate of an existing entry, **do not

drop it**. Annotate it [overlaps with: ] in the numbered list so the user can decide whether to skip, edit, or replace.

Pass D — Confirm / Confirmar

Output exactly this template (substitute values, keep the structure):

Imprime exactamente esta plantilla (sustituye valores, mantén la estructura):

Found N candidate learnings from this conversation.
Encontré N aprendizajes candidatos en esta conversación.

Reply with: numbers (e.g. 1,3,5), ranges (1-4), "all", "none", or
"edit N: " / "drop low" / "skip N".

Responde con: números (ej. 1,3,5), rangos (1-4), "all", "none", o
"edit N: " / "drop low" / "skip N".

 1. [memory]       —   ()
 2. [lesson]       —   ()  [overlaps with: ]
 3. [skill]        —   ()
 4. [project-doc]  —   ()
 ...

>

Then wait. Do not call Write, Edit, or any file-mutating tool until the user replies. This is the most important rule in this skill.

Después espera. No llames Write, Edit, ni ninguna herramienta que modifique archivos hasta que el usuario responda. Esta es la regla más importante del skill.

Accepted inputs / Inputs aceptados:

• Comma-separated numbers: 1,3,5
• Ranges: 1-4 or 1-3,7,9-11
• all — accept everything as shown
• none — accept nothing, exit cleanly
• edit 5: — replace the candidate's rationale/title before saving
• skip 3 — accept all except the listed numbers
• drop low — filter out everything below the named confidence band (drop low, drop medium)

If the input is ambiguous, ask once. Do not guess.

Si el input es ambiguo, pregunta una vez. No adivines.

Pass E — Execute / Ejecutar

For each confirmed candidate, run the category-specific write procedure:

Para cada candidato confirmado, ejecuta el procedimiento de escritura por categoría:

memory

1. Determine ` for the current project: read pwd`, then convert

/Users/soyenrique/Desktop/aprende-skill to -Users-soyenrique-Desktop-aprende-skill (replace / with -, drop leading dash, keep dashes). The folder is ~/.claude/projects//memory/. Create it if missing (mkdir -p).

1. Pick a filename: kebab-case slug from the title, prefixed by metadata.type

(e.g. feedback_pnpm-over-npm.md, project_supabase-rls-policy.md). If a file with that name exists, append -2, -3, ... Never overwrite.

1. Write the file with the frontmatter and body spec from

references/memory-format.md.

1. Append a one-line entry to ~/.claude/projects//memory/MEMORY.md:

- [](.md) — .

lesson

1. Same folder as memory. Filename starts with lesson_ (e.g.

lesson_webview-assumed-localstorage.md).

1. Use the strict frontmatter and four mandatory subheads from

references/lesson-format.md:

• **What happened / Qué pasó:**
• **Why it happened / Por qué pasó:**
• **How to avoid / Cómo evitar:**
• **Detection signal / Señal de detección:**

1. Append to MEMORY.md under a ## Lessons / Lecciones subsection (create

the subsection if missing).

skill (stub)

1. Decide scope: user-global (~/.claude/skills//) by default;

project-local (./.claude/skills//) only if the workflow references repo-specific paths or tools.

1. Create the folder. Write SKILL.md as a stub, not a full skill — use

references/skill-stub-template.md. Fill in only what the conversation shows; mark the rest [STUB — fill in: ...].

1. Print a one-line reminder: "Skill stub written at ``. Run the

skill-creator plugin (or edit manually) to flesh it out before publishing."

project-doc

1. Decide scope: project-level (./CLAUDE.md and ./AGENTS.md — dual-write)

by default; global (~/.claude/CLAUDE.md and ~/.claude/AGENTS.md) only if the candidate is repo-agnostic.

1. Extra confirmation for global writes: prompt the user one more time

before touching ~/.claude/CLAUDE.md or ~/.claude/AGENTS.md. Global docs affect every session on this machine.

1. Read the target file. Find the best existing section (e.g. ## Commands,

## Conventions). Append under it.

1. If no good section exists, create a ## Learnings (added by /aprende)

section at the end of the file.

1. Mark each appended line with an HTML comment for later audit:

``.

1. Dual-write to both CLAUDE.md and AGENTS.md. If one doesn't exist,

create it with the entry alone. Content is identical between the two.

After all writes, emit one confirmation line per write:

Después de cada escritura, imprime una línea de confirmación:

✓ memory   → ~/.claude/projects/.../feedback_pnpm-over-npm.md  (+MEMORY.md)
✓ lesson   → ~/.claude/projects/.../lesson_webview-localstorage.md  (+MEMORY.md)
✓ skill    → ~/.claude/skills/verify-rls/SKILL.md  (stub — finish before use)
✓ project  → ./CLAUDE.md + ./AGENTS.md  (## Commands)

End with a one-paragraph summary of what was learned and a pointer to /aprende --review for later pruning.

Termina con un párrafo resumen de lo aprendido y un puntero a /aprende --review para podar después.

---

5. Output formats / Formatos de salida

The strict specs live in separate references so this file stays scannable:

Las especificaciones estrictas están en references separadas para que este archivo siga siendo fácil de escanear:

• references/memory-format.md — frontmatter + body for type: user|project|reference|feedback.
• references/lesson-format.md — frontmatter + 4 mandatory subheads (Reflexion).
• references/skill-stub-template.md — bare SKILL.md scaffold.
• references/signal-patterns.md — multi-language correction phrases and detection heuristics.
• references/review-workflow.md — semantics of /aprende --review.

The lesson format is the most important; here it is inline as well:

El formato lesson es el más importante; aquí va inline también:

---
name: lesson_
description: One-sentence summary of the mistake and its corrective rule.
metadata:
  type: lesson
  confidence: high | medium | low
  status: active   # active | retired | superseded-by-
  createdAt: YYYY-MM-DD
  lastValidated: YYYY-MM-DD
  originSessionId: 
---

**What happened / Qué pasó:** 

**Why it happened / Por qué pasó:** 

**How to avoid / Cómo evitar:** 

**Detection signal / Señal de detección:** 

Related: [[other-memory-name]]

---

6. --review mode / modo --review

When invoked as /aprende --review:

Cuando se invoca como `/apre

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Hainrixz
• Source: Hainrixz/aprende-skill
• License: MIT
• Homepage: https://www.tododeia.com

Install and usage instructions live in the source repository linked above.