Una skill y es un paquete de instrucciones y herramientas que cambia el comportamiento de Claude Code para una tarea específica. En vez de explicar el mismo proceso todos los días ("antes de programar, escribe una prueba"), empaquetas esa lógica en una skill y el agente la carga cuando la necesita.

Técnicamente, una skill es un directorio con un archivo SKILL.md (frontmatter YAML + cuerpo markdown) que describe cuándo activar e cómo actuar. Puede incluir slash commands, sub-agents, hooks y referencias a otras skills.

# Estructura mínima de una SKILL.md
---
name: grill-me
description: Pon a prueba un plan antes de programar.
  Úsalo cuando el usuario diga "voy a empezar a implementar",
  "tengo una idea", "¿tiene sentido hacerlo así?".
---

# Grill Me

Eres un senior escéptico. Antes de aceptar cualquier plan:

1. Enumera 5 suposiciones implícitas en el pedido del usuario.
2. Para cada una, pregunta "¿y si esta es incorrecta?".
3. Sugiere el experimento más barato para validar cada una.
4. Solo entonces devuelve el plan refinado.

El problema más costoso no es el código incorrecto, sino el código correcto en lo equivocado. El usuario pide X, pero quiere Y; el agente implementa X a la perfección y, dos semanas después, descartan la funcionalidad.

Cuando el agente y la persona no comparten vocabulario, cada conversación debe explicarse desde cero. Eric Evans (autor de Domain-Driven Design) llama a esto ausencia de lenguaje ubicuo: términos que todo el equipo —humanos y agentes— usa de la misma manera.

Un ejemplo concreto. Imagina un curso en el que "clase" puede ser un placeholder O una instancia real materializada con un alumno y su progreso. Sin un lenguaje ubicuo, escribes así:

Los LLM se entrenan para producir código que parece correcto. Los tipos coinciden, los imports existen, la sintaxis es válida y, aun así, la lógica está mal. Sin una señal externa (pruebas), el agente cree en su propio resultado.

La solución clásica es TDD (Test-Driven Development): escribir primero la prueba, verla fallar (rojo), implementar lo mínimo para que pase (verde) y después refactorizar. Skills como /tdd impone este ciclo al agente.

El código se deteriora. Foote y Yoder lo documentaron en 1997 con el término "Big Ball of Mud": sistemas que crecen sin una arquitectura coherente porque cada feature se agregó a las apuradas, sin refactorizar. Con agentes, la velocidad aumenta y el deterioro también.

La intuición equivocada: "voy a pedirle al agente que refactorice todo ahora". La intuición correcta: refactor y oportunidad, no evento. No reescribes el sistema; identificas una duplicación y la unificas cuando ya necesitas modificar esa área.

Las skills individuales ya ayudan. Pero el verdadero beneficio aparece cuando se se componen en flujos — cada uno resuelve un problema, y el output de uno alimenta al siguiente.

Workflow típico de una feature, desde cero hasta el código en producción:

   /grill-with-docs        Stress-testa a ideia contra docs e ADRs
          │              (elimina desalinhamento, problema #1)
          ▼
   /to-prd                 Vira documento de produto curto e cravado
          │              (fixa linguagem ubiqua, problema #2)
          ▼
   /to-issues              Quebra o PRD em issues pequenas e testaveis
          │              (escopo pequeno = menos ball of mud)
          ▼
   /tdd                    Para cada issue: teste vermelho -> verde -> refactor
          │              (resolve problema #3)
          ▼
   /triage                 Revisa diff, sugere refator pontual antes do merge
                         (combate problema #4, deepening opportunity)

Cada flecha es una transición deliberada. El usuario no necesita tener todo el contexto en la cabeza: las skills se encargan del handoff. El PRD se convierte en input de /to-issues; el issue se convierte en input del /tdd; el diff se convierte en input del /triage.