version: "1.0.0"

04 — Anatomía de una skill

Antes que nada, lo honesto:

Una skill es contexto bien escrito. No es un programa.

No hay compilador, no hay runtime, no hay tipos. Una skill es una carpeta con un SKILL.md —markdown con frontmatter— que el agente lee cuando cree que aplica, y que a partir de ese momento vive en su ventana de contexto como si tú lo hubieras tecleado.

Todo lo demás son variaciones sobre cuánto texto metes, cómo lo partes, y si acompañas ese texto con scripts que sí son programas de verdad.

El extremo corto: frontend-design de Anthropic

La skill oficial de Anthropic para construir interfaces cabe en una página de markdown. Sin scripts, sin archivos de referencia, sin comandos slash. Su carpeta pública tiene exactamente dos archivos: SKILL.md y LICENSE.txt.

Y funciona. ¿Qué hay adentro?

• Una sección de Design Thinking con cuatro preguntas previas al código: propósito, tono, restricciones, diferenciación.
• Una lista de tonos extremos a los que el agente debe comprometerse: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian.
• Cinco ejes de ejecución: Typography, Color & Theme, Motion, Spatial Composition, Backgrounds & Visual Details.

La lección de diseño de esta skill es la palabra extremos. Si le das al modelo una lista de opciones tibias, promedia. Si le das una lista donde toda opción es un compromiso fuerte, tiene que elegir uno, y elegir es lo contrario de promediar. Toda la skill es, básicamente, un mecanismo para prohibir el punto medio.

Se auto-activa por descripción cuando pides construir componentes o páginas. No tiene comandos porque no los necesita.

El extremo largo: impeccable y hallmark

impeccable, de Paul Bakaus (creador de jQuery UI, ex-Developer Advocate de Google), va en la dirección opuesta: expone 23 comandos bajo /impeccable, agrupados en cinco familias — Create (craft, impeccable, shape), Evaluate (audit, critique), Refine (animate, bolder, colorize, delight, layout, overdrive, quieter, typeset), Simplify (adapt, clarify, distill), Harden (harden, onboard, optimize, polish) y System (document, extract, init, live).

hallmark, de Together AI, tiene un SKILL.md de 67 KB más 28 archivos de referencia organizados en subcarpetas (components/, genres/, macrostructures/, themes/, verbs/).

Advertencia honesta: 23 comandos son demasiados para memorizar. En la práctica el 90% del valor de impeccable está en init + craft + critique + polish. Y ninguna de las dos elimina el slop — lo reduce.

Lo que sí es programa

Aquí está la distinción que importa. Dentro de estas skills grandes hay dos cosas mezcladas:

Texto (probabilístico). "Prefiere ease-out en entradas." El agente puede ignorarlo, malinterpretarlo, o perderlo cuando el contexto se llena.

Scripts (deterministas). El detector de impeccable son 46 reglas sin LLM, con exit codes usables en un check de PR. Eso no es contexto: es un linter. No opina, falla.

gate.mjs de este repo está del lado determinista a propósito. Si tu motion.json prohíbe animar width y hay un transition: width en tu CSS, sale exit 1. No hay negociación posible con un exit code.

La estructura mínima que funciona

mi-skill/
├── SKILL.md            # frontmatter (name, description) + el criterio, corto
└── references/         # se cargan SOLO cuando el SKILL.md las manda a leer
    ├── presets.md
    └── anti-patterns.md

El campo description del frontmatter es lo único que el agente ve siempre. Es la carnada. Si dice "ayuda con diseño", nunca se activa. Si dice qué problema resuelve y con qué palabras lo pide el usuario, se activa cuando debe.

Cinco reglas para escribir la tuya

1. Prohibiciones antes que sugerencias. "Nunca uses h-screen, usa h-dvh" se cumple. "Considera usar unidades dinámicas" no.
2. Números antes que adjetivos. "Feedback de interacción nunca pasa de 200ms" es verificable. "Que se sienta rápido" no.
3. `SKILL.md` corto, referencias bajo demanda. El contexto es un presupuesto. Cada token que gastas en instrucciones es un token menos para el código.
4. Si se puede verificar con un script, hazlo script. Un contador de valores de radio en tu CSS es 15 líneas de Node y no falla nunca.
5. Cierra el loop. El patrón deliver-and-verify —render → screenshot → revisar— hace que el agente inspeccione su propio output en vez de asumir que salió bien. Vale para animación, vale para todo.

Las tres skills de criterio

• `design-contract` — corre la entrevista de 8 preguntas y escribe brand.json, voice.json, motion.json, brand.css y COMPONENT_RULES.md.
• `design-audit` — corre gate.mjs y traduce cada fallo a lenguaje humano con el fix concreto. La diferencia con los auditores de terceros: hallmark e impeccable juzgan contra su criterio; éste juzga contra tu contrato.
• `ui-vocabulary` — glosario ES↔EN de componentes, offline y en español.

→ Sigue con 05 — Vocabulario de UI.