Qué cambia realmente la capacidad
Una capacidad es un conjunto de instrucciones que se carga cuando es relevante en lugar de en cada solicitud: es la parte bajo demanda del stack de archivos del agente. La capacidad de diseño frontend se carga cuando solicita trabajo de UI y orienta al modelo hacia valores predeterminados más sólidos.
En la práctica, las diferencias que aparecen con más consistencia son estas, y son reales en lugar de cosméticas:
- El espaciado adquiere un ritmo. Los valores empiezan a provenir de una escala en lugar de elegirse por elemento, por lo que el ritmo vertical se mantiene en toda la página.
- La jerarquía se vuelve deliberada. El tamaño, el peso y el color se utilizan conjuntamente para separar niveles, en lugar de usar solo el tamaño.
- Menos diseños genéricos. La cuadrícula reflexiva de tres tarjetas iguales aparece con menos frecuencia cuando el contenido no sugiere realmente tres elementos pares.
- Se gestionan los estados. Los estados hover, focus, disabled y error aparecen sin haber sido solicitados, que es donde la mayoría de los componentes generados suelen ser deficientes.
Se trata de una mejora significativa y es la razón por la que vale la pena instalar la capacidad. También es todo su alcance.
La brecha: el criterio no es lo mismo que los valores
Una capacidad define *cómo decidir*. No define *qué se decidió*. Esta distinción parece académica hasta que se comparan dos sesiones lado a lado.
La capacidad indicará fiablemente al modelo que una acción primaria necesita suficiente contraste con su superficie y no debe competir con una secundaria. No tiene forma de saber que su color primario es oklch(0.55 0.19 45), porque nunca se lo ha indicado y no hay ningún lugar en una capacidad para que esa información resida. Por lo tanto, elige algo defendible. En la siguiente sesión, elige otra opción igualmente defendible.
Dos sesiones, dos botones buenos, dos azules diferentes. Ninguno es un error. Juntos, representan un problema de marca.
| Capacidad de diseño | DESIGN.md + tokens | |
|---|---|---|
| Aporta | Criterio: cómo decidir | Valores: qué se decidió |
| Espaciado | Usa una escala | Define qué escala |
| Color | Elige algo con buen contraste | Define su rampa exacta |
| Persiste en una sesión nueva | Sí, como comportamiento | Sí, como los mismos valores |
| Dos pantallas coinciden | Solo por coincidencia | Por construcción |
Reprodúzcalo usted mismo
No se fíe de mi palabra: la prueba es corta y el resultado es inequívoco.
- 1
Solicite una tarjeta de precios en una sesión nueva
Con la skill activa y sin un sistema de diseño presente. Guarde el resultado.
- 2
Inicie una sesión genuinamente nueva
No un mensaje nuevo, sino una sesión nueva, para que no se arrastre nada.
claude - 3
Solicite un panel de ajustes para el mismo producto
Use la misma redacción sobre el producto, sin hacer referencia al primer componente.
- 4
Compare ambos resultados
Compare el color primario, el border radius, el tamaño de fuente base y el espacio vertical entre la etiqueta y el control.
- 5
Analice el resultado con honestidad
Ambos parecerán competentes. En nuestras pruebas, tres o cuatro de esos cuatro valores difieren, y cada uno es, individualmente, una elección razonable.
Si sus dos resultados coinciden estrechamente, compruebe si hay algo más proporcionando constantes: un archivo de tema existente, una librería de componentes ya presente en el repo o una sesión prolongada. Ese es el punto: que los resultados coincidan significa que los valores provienen de algún lugar duradero, no de la skill.
Cerrando la brecha
Conserve la skill. Está realizando una tarea que nada más hace. Añada la capa que la skill no puede contener: un conjunto de design tokens más un archivo DESIGN.md en el repo, que el agente lea al inicio de cada sesión.
La división del trabajo es clara una vez que ambos están implementados. El archivo responde a *qué* azul, *qué* radio, *qué* escala tipográfica. La skill responde a cómo componerlos en una pantalla que se lea bien. Ninguno sustituye al otro, y el error común es asumir que la skill hace que el archivo sea innecesario.
- 1
Instale un kit en el repo
Esto escribe el archivo DESIGN.md y los archivos de tokens que leerá su agente.
npx --yes identityforge@latest install --client claude-code - 2
Aplique el kit que desee
Los kits gratuitos no requieren cuenta.
identityforge apply ambient-sage - 3
Vincule AGENTS.md hacia él
Una sola línea, para que el contrato de diseño sea descubrible en lugar de incidental.
Never hardcode theme colors. Use the semantic tokens in DESIGN.md. - 4
Repita la prueba de las dos sesiones
Mismo procedimiento que el anterior. Los valores ahora deberían coincidir exactamente, ya que se leen en lugar de decidirse de nuevo.
Dé a la skill un motivo para ser consistente
Un kit instala los tokens y el archivo DESIGN.md que la skill de diseño no tiene forma de transportar. La skill sigue aportando la ejecución técnica; el archivo aporta su marca.
¿Respetará la base de código y el tema existentes, o hará lo que quiera?
Esta es la pregunta que la gente se hace realmente sobre las habilidades de diseño, y casi nada de lo escrito al respecto la responde. La respuesta honesta: una habilidad respeta su tema solo en la medida en que dicho tema exista como valores que pueda leer. Una habilidad es un conjunto de instrucciones sobre cómo trabajar. No es la fuente de sus valores.
Esa distinción determina el resultado en una base de código existente:
| El tema existe como design tokens + DESIGN.md | El tema existe en Figma y en la cabeza de las personas | |
|---|---|---|
| Lo que lee la habilidad | Sus valores reales | Nada; no tiene fuente |
| Lo que produce | Componentes de su sistema | Componentes plausibles basados en los valores por defecto de la librería |
| Entre sesiones | Estable: se vuelve a leer en cada ocasión | Diverge y continúa divergiendo |
| Qué solucionar primero | Nada | Los valores ausentes, no la habilidad |
Una habilidad no puede proporcionar valores que nunca recibió
Si una habilidad produce resultados fuera de marca en una base de código con tema, la causa habitual es que el tema no es legible desde el repositorio. Añadir una habilidad mejor no soluciona esto. Añadir los valores, sí.
Existe una versión medible de esto. Analizamos 299 archivos DESIGN.md públicos y descubrimos que, de los 72 que describían un sistema visual, el 86% no utilizaba nombres de roles de color semánticos; enumeraban códigos hex o nombraban los colores por su tono. Una habilidad a la que se le asigna --primary puede aplicar su sistema a un componente que nadie haya descrito. Una habilidad a la que se le da una tabla de códigos hex solo puede copiar, y es al copiar donde empieza a adivinar.
- 1
Compruebe si su tema es legible
Busque un archivo DESIGN.md o un archivo de tokens en la raíz del repositorio. Si la única fuente es Figma, la funcionalidad no tendrá una base sobre la cual trabajar.
- 2
Haga que los valores sean semánticos
Use roles en lugar de tonos, para que la habilidad pueda ubicarlos correctamente en casos que usted nunca haya documentado.
- 3
Indíquelos desde AGENTS.md como una prohibición
Never hardcode theme colors, spacing or radii. Use the tokens in DESIGN.md. - 4
Ejecute la misma construcción en una sesión nueva
Si mantiene el mismo color primario y el mismo radio, significa que está leyendo. Si hay ligeras variaciones, significa que está recordando, y la memoria se degrada.
¿Habilidad, plugin o un listado en un marketplace?
La mayor parte de lo escrito sobre esto son resúmenes, y estos usan los tres términos indistintamente. No son lo mismo, y la diferencia determina si lo que ha instalado puede siquiera cargarse.
| Qué es | Cómo llega al modelo | |
|---|---|---|
| Una habilidad | Un directorio con un SKILL.md: una descripción más instrucciones | El modelo lo carga cuando la descripción coincide con lo que usted ha solicitado |
| Un plugin | Un paquete que puede agrupar skills, comandos, subagentes y hooks | Se instala una sola vez; todo lo que agrupe queda disponible |
| Un anuncio en el marketplace | Una entrada de índice que apunta a un plugin publicado por alguien | No se carga nada desde un anuncio: es una página de catálogo |
La consecuencia práctica es la condición de carga. El modelo selecciona una skill basándose en su descripción, por lo que solo interviene cuando su solicitud parece un trabajo de diseño. Si pide "una página de ajustes", se activa. Si pide "corregir el padding en la línea 40", es posible que no lo haga, porque eso parece una edición y no una tarea de diseño; en ese caso, obtendrá una edición ordinaria sin la calidad artesanal para la que instaló la skill.
Forma sencilla de saber si se ha activado
Ejecute la misma solicitud dos veces en sesiones nuevas: una redactada como tarea de diseño y otra como edición mecánica. Si los resultados difieren en el ritmo del espaciado y la cobertura de estados, y no solo en la redacción, está viendo cómo la skill se activa y desactiva. Ese es el fallo que la gente reporta como "a veces funciona".
Cuando la skill y su archivo DESIGN.md no coinciden
Esta es la pregunta que las comparativas suelen omitir por completo, y es la que importa una vez que se tienen ambos. Entran en conflicto porque están escritos por personas diferentes para propósitos diferentes. Su archivo indica que el color primario es oklch(0.55 0.19 45). El criterio de la skill indica que un color primario debe superar un umbral de contraste respecto a la superficie sobre la que se asienta. En una tarjeta clara, ambos coinciden. En su superficie oscura elevada, puede que no sea así.
Ninguna de las dos capas está equivocada y no hay un árbitro integrado: el modelo lo resuelve y, por defecto, prioriza la instrucción que sea más específica y se haya leído más recientemente. Por eso la resolución debe quedar escrita en lugar de darse por sentada:
- Los valores no son negociables; la composición sí. Indíquelo así en
AGENTS.md. El hex, el radio y la escala tipográfica provienen del archivo. Cómo se organizan en una pantalla es decisión de la skill. - Dé al archivo la vía de escape que la skill necesita. El conflicto anterior solo existe porque el sistema tiene un único color primario. Implemente un primario que también sea legible en sus superficies oscuras, o un par documentado, y el desacuerdo desaparecerá en lugar de ser juzgado sesión a sesión.
- Escriba prohibiciones, no preferencias. "Preferir tokens semánticos" pierde frente a un argumento de contraste específico. "Nunca hardcodear colores del tema" no pierde, porque no deja margen de ponderación.
- Espere silencio en caso de conflicto. El modelo no le avisará de que ha anulado su token. La única detección fiable es buscar mediante grep en el diff los valores literales de color y espaciado.
# the only conflict detector that actually fires: literals in the diff
git diff | grep -nE '#[0-9a-fA-F]{3,8}|oklch\(|rgb\(|[0-9]+px'Ejecute esto en cada diff generado por un agente. Un resultado limpio significa que los valores fueron leídos. Cualquier coincidencia es un lugar donde el criterio ha sustituido silenciosamente una decisión que usted ya había tomado; es la misma deriva que en la prueba de las dos sesiones, solo que llega por una puerta diferente.
¿Merece la pena instalar la skill?
Sí. Mejora sensiblemente la calidad de las pantallas individuales y no cuesta nada probarla. El argumento aquí es contra el hecho de tratarla como una solución completa, no contra la skill en sí.
¿Hace que un sistema de diseño que la skill sea redundante?
No, y este es el error simétrico. Los tokens indican al agente qué valores usar; no dicen nada sobre cómo componer una pantalla que se lea bien. Los proyectos con un sistema sólido pero sin guía de diseño producen diseños alineados con la marca pero con una jerarquía débil.
¿Solucionará un prompt más largo la inconsistencia entre sesiones?
Solo dentro de una misma sesión, y cada vez menos a medida que la sesión crece. Una sesión nueva comienza de cero, por lo que cualquier cosa que quiera que perdure debe residir en un archivo.
Si solo pudiera elegir uno, ¿la skill de diseño o un DESIGN.md?
El archivo, sin ninguna duda. Sin él, cada sesión redefine su marca y el resultado diverge permanentemente. Sin la skill, obtiene pantallas alineadas con la marca pero con una jerarquía más débil, lo cual es un techo de calidad y no un problema acumulativo. Solucione primero el problema acumulativo.
¿Se aplica esto también a Cursor y otros agentes?
La skill específica es de Claude Code, pero la naturaleza del problema no lo es. Cualquier mecanismo que aporte criterio de diseño sin valores de diseño produce la misma inconsistencia entre sesiones.