Cómo convertir tu Design System en una skill.md para potenciar tus diseños con IA
Aprende a convertir tu Design System en una Skill.md compatible con Cursor, Claude Code y Codex. Guía práctica con estructura, ejemplos e implementación.
17 min de lectura
La inteligencia artificial puede generar interfaces en cuestión de minutos, pero conseguir que esas interfaces respeten un sistema de diseño, mantengan la coherencia visual y sigan los criterios de un producto real es un reto completamente diferente.
Los Design Systems llevan años resolviendo este problema mediante un lenguaje común entre diseñadores y desarrolladores. Sin embargo, con la llegada de herramientas como Cursor, Claude Code y OpenAI Codex, aparece una nueva necesidad: conseguir que los agentes de inteligencia artificial también conozcan, comprendan y apliquen ese lenguaje.
Aquí es donde entran en juego las Agent Skills y, concretamente, el archivo SKILL.md.
Una Skill permite trasladar los principios, tokens, componentes, patrones y restricciones de nuestro Design System a un formato que los agentes de IA pueden consultar y utilizar durante sus tareas.
En este artículo veremos cómo transformar un Design System existente en una Skill reutilizable, desde la extracción de información hasta su implementación y validación en diferentes herramientas de inteligencia artificial.
1. ¿Qué es una Skill y por qué es importante para un Design System?
Una Skill es un conjunto de instrucciones y recursos que permite especializar el comportamiento de un agente de inteligencia artificial en una tarea determinada.
Su elemento principal es un archivo SKILL.md, que describe qué debe hacer el agente, cuándo debe utilizar la Skill y cómo debe desarrollar el trabajo. Puede complementarse con documentación, ejemplos, scripts y otros recursos.
Este formato forma parte del estándar abierto Agent Skills, utilizado por herramientas como Cursor, Claude Code y OpenAI Codex.
A diferencia de un prompt convencional, una Skill no necesita que repitamos todas las instrucciones en cada conversación. El agente puede identificar cuándo resulta útil, consultar sus instrucciones y utilizar los recursos asociados.
¿Qué problemas resuelve?
Imaginemos que pedimos a una IA que diseñe un dashboard para nuestro producto. Sin contexto específico, puede generar una interfaz visualmente atractiva, pero probablemente introduzca decisiones que no coincidan con nuestro sistema:
Colores que no pertenecen a nuestra paleta.
Tipografías y tamaños arbitrarios.
Espaciados inconsistentes.
Componentes inventados o duplicados.
Variantes que no existen en nuestra biblioteca.
Patrones de interacción diferentes a los establecidos.
Una Skill permite reducir estos problemas proporcionando al agente las reglas necesarias para trabajar dentro de nuestro lenguaje visual.
Es importante diferenciar algunos conceptos:
Recurso | Función |
|---|---|
Prompt | Define una tarea concreta. |
AGENTS.md / Rules | Establece instrucciones generales del proyecto. |
Documentación | Explica cómo funciona el Design System. |
SKILL.md | Enseña al agente cómo aplicar ese conocimiento. |
MCP | Conecta el agente con herramientas y fuentes externas. |
La Skill no sustituye a la documentación, al código ni a MCP. Los complementa, proporcionando un procedimiento para utilizar correctamente esos recursos.
El objetivo es que la IA deje de generar interfaces genéricas y empiece a diseñar siguiendo las reglas de nuestro producto.
2. Analizar nuestro Design System antes de crear la Skill
El primer paso es recopilar y estructurar el conocimiento del sistema de diseño.
No basta con exportar los colores y las tipografías. Un Design System contiene decisiones visuales, funcionales y técnicas que debemos trasladar correctamente.
Recomiendo analizar cinco grandes áreas:
2.1. Design Tokens
Debemos identificar los valores que definen la identidad visual:
Colores primarios, secundarios y semánticos.
Tipografías, pesos y escalas.
Espaciados y tamaños.
Border radius y bordes.
Sombras y elevaciones.
Grid y breakpoints.
Transiciones y animaciones.
Es importante documentar tanto el valor como su finalidad.
Por ejemplo, no basta con indicar que existe un color #2457D6. Debemos explicar si corresponde a una acción principal, un enlace o un elemento seleccionado.
2.2. Componentes
Debemos recopilar los componentes disponibles y documentar:
Nombre y finalidad.
Variantes y tamaños.
Propiedades.
Estados: hover, focus, active, disabled y loading.
Comportamientos.
Restricciones.
Ejemplos de uso.
Por ejemplo, para un botón necesitamos saber si existen variantes primary, secondary, tertiary y destructive, qué tamaños admite y cómo debe comportarse en cada estado.
2.3. Patrones de diseño
Los componentes individuales no explican cómo construir una interfaz completa. También necesitamos documentar patrones como:
Formularios.
Tablas de datos.
Dashboards.
Navegación.
Filtros y búsquedas.
Modales.
Estados vacíos.
Mensajes de error.
2.4. Principios y accesibilidad
Finalmente, debemos incorporar las reglas que definen cómo debe comportarse nuestro producto:
Jerarquía visual.
Diseño responsive.
Contraste y accesibilidad.
Navegación por teclado.
Uso de iconografía.
Densidad de información.
Criterios de usabilidad.
2.5. Identificar las fuentes de información
La información puede estar distribuida entre Figma, Storybook, repositorios de código, archivos JSON, CSS y documentación interna.
Antes de extraerla, debemos establecer qué fuente tiene prioridad:
Información | Fuente recomendada |
|---|---|
Tokens | Repositorio oficial de variables |
Componentes visuales | Biblioteca de Figma |
Propiedades técnicas | Código / Storybook |
Comportamientos | Documentación funcional |
Patrones UX/UI | Documentación de producto |
Esto evita que la IA utilice información obsoleta o contradictoria.
3. Crear la estructura de nuestra Skill
Una vez recopilada la información, debemos organizarla.
Aunque podríamos introducir todo en un único SKILL.md, no es recomendable. Lo ideal es separar las instrucciones principales de la documentación detallada.
Propongo esta estructura:
design-system-ui/
│
├── SKILL.md
│
├── references/
│ ├── foundations.md
│ ├── color-tokens.md
│ ├── typography.md
│ ├── spacing-and-layout.md
│ ├── components.md
│ ├── interaction-states.md
│ ├── responsive-guidelines.md
│ ├── accessibility.md
│ ├── patterns.md
│ └── do-and-dont.md
│
├── assets/
│ ├── design-system-tokens.json
│ └── component-examples/
│
└── scripts/
└── validate-tokens.jsCada directorio tiene una función:
SKILL.md: contiene las instrucciones principales y el flujo de trabajo.
references: almacena la documentación detallada.
assets: contiene recursos reutilizables.
scripts: incluye herramientas para automatizar comprobaciones.
Esta organización permite que el agente consulte únicamente la información necesaria para cada tarea, evitando cargar toda la documentación permanentemente en su contexto.
Por ejemplo, para crear un formulario consultará los componentes, los patrones de formularios y las reglas de accesibilidad. Para desarrollar un dashboard necesitará también las referencias de layout y composición.
4. Construir nuestro archivo SKILL.md
Ahora vamos a crear el archivo principal.
Toda Skill comienza con un bloque de metadatos YAML que identifica su nombre y describe cuándo debe utilizarse.
4.1. Definir la Skill
---
name: design-system-ui
description: >
Apply the official Design System when designing,
generating, implementing or reviewing user interfaces.
Use for frontend development, UX/UI design, components,
layouts, forms, dashboards and responsive screens.
---La descripción es especialmente importante porque ayuda al agente a identificar cuándo debe activar la Skill.
Conviene utilizar una descripción específica que indique qué tareas cubre y en qué circunstancias debe utilizarse.
4.2. Establecer las reglas
Después del bloque YAML definimos el comportamiento que esperamos del agente:
# Design System UI
## Purpose
Apply the official Design System consistently
across all user interface design and development tasks.
## Core principles
1. Always reuse existing components.
2. Use official design tokens.
3. Never invent undocumented variants.
4. Follow established interaction patterns.
5. Maintain visual consistency.
6. Prioritize accessibility.
7. Ensure responsive behavior.
8. Respect existing project architecture.
## Restrictions
- Do not introduce arbitrary colors.
- Do not invent component properties.
- Do not duplicate existing components.
- Do not modify global tokens without approval.
- Do not ignore accessibility requirements.
If a required component or specification
is missing, identify the limitation
before proposing a new solution.Estas reglas constituyen la base del comportamiento de nuestra Skill.
4.3. Definir el flujo de trabajo
No queremos que la IA empiece a implementar una interfaz inmediatamente. Necesitamos que siga un proceso similar al de un diseñador y desarrollador experimentado.
## Workflow
### 1. Analyze
Understand the requirements and user goals.
### 2. Inspect
Review the project structure, framework,
components and available tokens.
### 3. Research
Consult the relevant Design System references.
### 4. Plan
Define hierarchy, layout, components
and responsive behavior.
### 5. Implement
Use official components and tokens.
### 6. Validate
Check visual consistency, accessibility,
responsive behavior and interaction states.
### 7. Report
Summarize the implementation and
identify any deviations.4.4. Indicar qué documentación consultar
Finalmente, debemos relacionar las tareas con los archivos de referencia:
## Documentation
Consult the following references when needed:
- references/foundations.md
- references/color-tokens.md
- references/typography.md
- references/spacing-and-layout.md
- references/components.md
- references/interaction-states.md
- references/responsive-guidelines.md
- references/accessibility.md
- references/patterns.md
- references/do-and-dont.md
Read only the documentation required
for the current task.
Never assume undocumented behavior.Con esto tenemos una primera versión funcional de nuestra Skill. El siguiente paso será completar los documentos de referencia con la información real de nuestro Design System.
5. Generar la Skill utilizando inteligencia artificial
Una de las posibilidades más interesantes es utilizar herramientas como Cursor, Claude Code o Codex para analizar nuestro repositorio y generar automáticamente gran parte de la documentación.
Mi recomendación es hacerlo en tres fases.
Fase 1. Auditar el Design System
Proporcionamos acceso al repositorio y pedimos al agente que identifique los tokens, componentes, patrones y convenciones existentes.
Podemos utilizar este prompt:
Quiero convertir el Design System de este proyecto
en una Agent Skill compatible con el estándar
abierto Agent Skills.
Analiza el repositorio e identifica:
1. Design tokens.
2. Colores y variables semánticas.
3. Tipografía y espaciados.
4. Grid y breakpoints.
5. Componentes y variantes.
6. Propiedades y estados.
7. Patrones de composición.
8. Reglas de accesibilidad.
9. Convenciones de implementación.
Identifica las fuentes oficiales de cada elemento.
No inventes información. Diferencia entre datos
confirmados, inferidos y no documentados.
Genera un informe de auditoría con el inventario
completo y las carencias detectadas.
No modifiques los archivos originales.El objetivo es obtener una visión completa antes de generar la Skill.
Fase 2. Generar la documentación
Una vez realizada la auditoría, solicitamos que organice la información:
Utilizando el informe anterior, genera documentación
estructurada para nuestro Design System.
Crea los siguientes documentos:
- foundations.md
- color-tokens.md
- typography.md
- spacing-and-layout.md
- components.md
- interaction-states.md
- responsive-guidelines.md
- accessibility.md
- patterns.md
- do-and-dont.md
Utiliza exclusivamente información verificada.
Conserva los nombres originales de los tokens
y las propiedades reales de los componentes.
Incluye ejemplos cuando existan.
No inventes valores ni comportamientos.
Identifica claramente cualquier información
que no esté documentada.
Guarda los archivos en una carpeta temporal.Fase 3. Crear y validar la Skill
Por último, pedimos al agente que construya el paquete:
Convierte la documentación generada en una
Agent Skill llamada design-system-ui.
Crea esta estructura:
design-system-ui/
SKILL.md
references/
assets/
scripts/
Incluye:
- Frontmatter YAML válido.
- Instrucciones generales.
- Reglas de diseño.
- Flujo de trabajo.
- Restricciones.
- Referencias a la documentación.
- Checklist de validación.
Comprueba que todos los archivos existen,
que las referencias son correctas y que
no hay instrucciones contradictorias.
La Skill debe ser compatible con Cursor,
Claude Code y OpenAI Codex.
No añadas información que no esté respaldada
por la documentación original.Este proceso permite convertir un trabajo de documentación que podría ser muy laborioso en un flujo asistido por IA.
Eso sí, debemos revisar los resultados. La IA puede interpretar incorrectamente una propiedad, omitir una variante o generar documentación incompleta. La validación del equipo sigue siendo imprescindible.
6. Integrar la Skill en Cursor, Claude Code y Codex
Una de las ventajas del estándar Agent Skills es que podemos reutilizar la misma documentación en diferentes herramientas.
No necesitamos mantener tres sistemas de instrucciones completamente distintos.
Cursor
Cursor permite utilizar Skills dentro del proyecto.
Podemos ubicarlas en:
.agents/skills/design-system-ui/SKILL.mdTambién admite:
.cursor/skills/design-system-ui/SKILL.mdUna vez instalada, podemos invocarla desde el agente mediante su nombre o dejar que se active automáticamente cuando detecte una tarea relacionada.
Documentación oficial de Cursor Skills
Claude Code
En Claude Code podemos utilizar:
.claude/skills/design-system-ui/SKILL.mdTambién podemos instalarla globalmente en:
~/.claude/skills/design-system-ui/SKILL.mdEsto permite utilizar la misma Skill en diferentes proyectos.
Documentación oficial de Claude Code
OpenAI Codex
Codex utiliza la siguiente estructura:
.agents/skills/design-system-ui/SKILL.mdTambién podemos utilizar Skills personales desde el directorio correspondiente del usuario.
La Skill puede descubrirse automáticamente o invocarse explícitamente desde la conversación.
Documentación oficial de Codex
Mi recomendación: mantener una única versión centralizada dentro del repositorio del Design System y distribuirla a las diferentes herramientas mediante enlaces o sincronización controlada.
Así evitamos que cada equipo termine utilizando una versión diferente de las instrucciones.
7. Potenciar la Skill conectándola con nuestras herramientas
La Skill ya proporciona contexto y reglas, pero podemos mejorar considerablemente sus capacidades conectándola con las herramientas que utilizamos habitualmente.
Figma mediante MCP
Conectar Figma mediante Model Context Protocol permite que el agente acceda a información de diseño y componentes, siempre que la integración disponga de las operaciones necesarias.
Podemos combinar:
Skill: define cómo aplicar el Design System.
Figma MCP: permite consultar diseños y componentes.
Repositorio: proporciona los tokens y la implementación.
Storybook: permite consultar las especificaciones técnicas.
Así conseguimos que el agente no dependa exclusivamente de documentación estática.
Tokens directamente desde el repositorio
Otra buena práctica es mantener los Design Tokens en su fuente original, por ejemplo, archivos JSON o variables CSS.
La Skill explica cómo utilizarlos, pero los valores reales se consultan desde el repositorio.
De esta manera evitamos duplicar información y reducimos el riesgo de utilizar tokens obsoletos.
Scripts de validación
También podemos incorporar scripts para detectar errores automáticamente:
Colores que no pertenecen a la paleta.
Espaciados no autorizados.
Tipografías incorrectas.
Tokens inexistentes.
Componentes duplicados.
Por ejemplo, un pequeño script podría comprobar si un color pertenece a una lista de tokens permitidos:
const allowedColors = [
"var(--color-brand-primary)",
"var(--color-text-primary)",
"var(--color-text-secondary)",
"var(--color-background-primary)"
];
function validateColor(value) {
return allowedColors.includes(value);
}Es un ejemplo simplificado, pero podemos evolucionarlo para analizar directamente los archivos CSS y los componentes del proyecto.
8. Validar y mantener nuestra Skill
Crear la Skill es solamente el principio. Necesitamos comprobar que realmente está mejorando los resultados.
Recomiendo preparar un conjunto de pruebas con tareas habituales:
Prueba | Qué evaluar |
|---|---|
Crear un botón | Variantes y tokens |
Crear un formulario | Componentes y validaciones |
Diseñar un dashboard | Composición y jerarquía |
Crear una tabla | Patrones y densidad |
Diseñar una pantalla móvil | Responsive |
Revisar una interfaz | Detección de inconsistencias |
También podemos utilizar herramientas como Playwright y axe-core para comprobar aspectos funcionales y de accesibilidad.
La revisión visual sigue siendo importante: utilizar los componentes correctos no garantiza que la composición final sea correcta.
Mantener la Skill actualizada
Cada vez que evolucione nuestro Design System debemos revisar su documentación.
Un proceso recomendable sería:
Se modifica un token o componente.
Se actualiza su documentación.
Se actualizan las referencias de la Skill.
Se ejecutan los scripts de validación.
Se comprueba que las instrucciones siguen siendo correctas.
Se publica una nueva versión.
Lo ideal es mantener la Skill versionada junto al propio Design System, facilitando que todo el equipo trabaje con la misma fuente de conocimiento.
9. El Design System como fuente de conocimiento para la IA
La incorporación de Skills representa un cambio importante en la forma de entender los sistemas de diseño.
Hasta ahora, un Design System era principalmente una herramienta para mantener la coherencia entre diseño y desarrollo. Con los agentes de IA, podemos convertirlo también en una fuente de conocimiento que guía sus decisiones.
Imaginemos que un diseñador solicita una nueva funcionalidad y el agente:
Analiza los requisitos.
Consulta el Design System.
Identifica componentes y patrones existentes.
Recupera los tokens necesarios.
Propone una estructura de interfaz.
Implementa la solución.
Comprueba su consistencia visual y técnica.
En este escenario, la IA no sustituye al sistema de diseño ni al criterio del diseñador. Trabaja con ellos.
Además, podemos utilizar estos mismos agentes para detectar inconsistencias, localizar componentes duplicados, identificar documentación obsoleta o descubrir carencias en nuestro propio Design System.
El resultado es un sistema más accesible, reutilizable y preparado para trabajar con diferentes herramientas de inteligencia artificial.
Conclusión
Convertir un Design System en una SKILL.md no consiste simplemente en proporcionar a la IA una guía de estilos. Consiste en transformar el conocimiento que hay detrás de nuestro sistema de diseño en instrucciones estructuradas que los agentes puedan comprender y aplicar.
El proceso requiere analizar las fuentes originales, documentar tokens y componentes, establecer patrones, definir restricciones y validar los resultados. También requiere mantener esa información sincronizada con la evolución del producto.
La ventaja es que podemos reutilizar ese conocimiento en Cursor, Claude Code, OpenAI Codex y otras herramientas compatibles con Agent Skills, sin tener que reconstruir las instrucciones para cada una.
El verdadero potencial no está en conseguir que la IA genere interfaces más rápido, sino en conseguir que las genere respetando nuestro lenguaje de diseño, nuestras decisiones y la identidad de nuestros productos.
El Design System deja de ser exclusivamente una biblioteca para diseñadores y desarrolladores y empieza a convertirse también en el contexto operativo de nuestros agentes de inteligencia artificial.
