Cómo Crear una Skill de Claude para Gobernanza de Tokens

Una skill de Claude (Agent Skill) es una carpeta - SKILL.md más scripts y recursos opcionales - que Claude Code, Claude.ai o la API de Claude cargan automáticamente cuando una tarea coincide con la descripción de la skill. Empaquetamos nuestro propio flujo de escaneo, auditoría de cobertura y contraste, exportación DTCG y sincronización de código en exactamente ese tipo de skill.

Esto no es una lista de skills para instalar. Documenta la función real de Agent Skills que lanzó Anthropic - el formato SKILL.md, cómo Claude descubre y carga una skill, y cómo escribimos una alrededor de la arquitectura de tokens Primitivos → Atoms que ya gobernamos en Figma.

Lectura relacionada: la guía de tokens de diseño para la jerarquía de tokens que esta skill asume, auditoría de cobertura vs valores sin tokenizar y auditoría de contraste para las comprobaciones que la skill aplica, y paridad diseño-código para el pipeline de DTCG a repositorio que verifica.

Qué es realmente una skill de Claude

Las Agent Skills son una función propia de Anthropic, no una convención de la comunidad: una carpeta que Claude carga dinámicamente para mejorar en una tarea especializada y repetible, publicada como patrón abierto en el repositorio anthropics/skills. Cada skill es autocontenida - un archivo SKILL.md más los scripts o archivos de referencia que necesite - y Claude decide por sí mismo cuándo usar una, igual que decide si llama a una herramienta.

Esto está en una capa distinta a los paquetes de reglas en Markdown que cubrimos en Skills de IA para Diseñadores - esas son reglas de tono de UX writing y accesibilidad que Claude Code o Cursor cargan en cada sesión. Una Agent Skill es procedimental: no se carga por defecto, se descubre por su descripción y se invoca para una tarea concreta, y puede llevar scripts ejecutables junto a sus instrucciones. La nuestra no le dice a Claude cómo escribir copy - le dice el orden de operaciones para tocar un componente tokenizado.

Formato SKILL.md: name, description y divulgación progresiva

Toda skill necesita exactamente un archivo obligatorio: SKILL.md, que abre con frontmatter YAML. Dos campos son obligatorios - name (máximo 64 caracteres) y description (máximo 200 caracteres) - y la descripción lo es todo: es lo que Claude lee para decidir si tu skill aplica a la tarea que tiene delante. Si la descripción es demasiado vaga, Claude nunca invoca la skill; si es demasiado amplia, Claude la invoca para la tarea equivocada.

---
name: nombre-de-tu-skill
description: Una descripción clara de qué hace esta skill y cuándo usarla
---

# Nombre de tu Skill

[Añade aquí las instrucciones que Claude seguirá cuando esta skill esté activa]

## Ejemplos
- Ejemplo de uso 1
- Ejemplo de uso 2

## Guías
- Guía 1
- Guía 2

Esa estructura en dos niveles es deliberada. Anthropic la llama divulgación progresiva: al inicio de la sesión, Claude solo mantiene en contexto el name y la description de cada skill - unas pocas docenas de tokens - y lee el cuerpo completo en Markdown solo cuando una tarea coincide. Si el cuerpo apunta entonces a un archivo de recursos o un script, Claude carga ese tercer nivel solo cuando realmente lo necesita. Una skill con un cuerpo largo no cuesta nada hasta el momento en que es relevante.

El flujo de cuatro pasos que empaquetamos como skill

Antes de escribir una línea de SKILL.md, ya teníamos el flujo. Escaneamos archivos de Figma en busca de valores sin tokenizar, ejecutamos una auditoría de cobertura y una auditoría de contraste para confirmar que el archivo está limpio, exportamos el resultado como JSON W3C DTCG y lo sincronizamos con el código. Empaquetar eso como skill no cambió los pasos - cambió quién hace cumplir el orden.

1. Escanear valores sin tokenizar - encontrar fills, strokes, espaciado y tipografía que aún guardan valores hex o píxeles en bruto en lugar de una variable de Figma vinculada.
2. Ejecutar la auditoría de cobertura y la auditoría de contraste - confirmar qué porcentaje de propiedades está vinculado a variables, y que cada par texto/fondo sigue cumpliendo el contraste WCAG, antes de exportar.
3. Exportar JSON DTCG - el formato de token estándar del W3C que Style Dictionary y pipelines equivalentes consumen sin un parser a medida.
4. Sincronizar con código - generar custom properties de CSS, SCSS, constantes de TypeScript o presets de Tailwind, y llevar la actualización al repositorio mediante sincronización bidireccional.

Cómo escribir SKILL.md para gobernanza de tokens de diseño

El instinto es escribir el cuerpo de la skill como una copia de los cuatro pasos anteriores. Eso es necesario pero no suficiente - esos pasos ya ocurren en Figma, dentro de un plugin, con la cadencia que controla el equipo de diseño. Lo que Claude Code necesita de la skill no es un tutorial para ejecutar una auditoría; es una barrera: qué comprobar en el repositorio antes de generar o editar un componente, y qué debe negarse a hacer si esa comprobación falla.

---
name: design-token-governance
description: Verifica que los tokens DTCG exportados y tokens.css estén actualizados antes de generar o editar componentes. Úsala antes de cualquier cambio que toque colores, espaciado, radios o tipografía.
---

# Gobernanza de Tokens de Diseño

## Cuándo usar esta skill
Invócala antes de escribir o editar código de UI que referencie tokens de diseño, y antes de abrir un PR que toque el estilado de componentes.

## Pasos
1. Lee `tokens/tokens.json` (DTCG) y confirma que se regeneró después de la última auditoría de cobertura y contraste en Figma - compara el timestamp de exportación en la cabecera del archivo con la última entrada de `tokens/CHANGELOG.md`.
2. Ejecuta `scripts/check-dtcg-freshness.sh` y detente si reporta una exportación desactualizada.
3. Cruza cualquier literal nuevo de color, espaciado o radio en el diff contra `tokens/tokens.css`. Si ya existe un token que cubre ese valor, usa el token - no introduzcas un literal nuevo.
4. Si ningún token cubre el valor, márcalo en la descripción del PR en lugar de inventar un nombre `var(--*)` puntual.

## Guías
- Nunca inventes un nombre de token que no esté presente en `tokens/tokens.css`.
- Trata una exportación DTCG desactualizada como un bloqueante, no como una advertencia.
- Prefiere tokens semánticos (`color-surface-elevated`) sobre primitivos (`gray-950`) en el código de componentes.

El script se mantiene deliberadamente pequeño - una comprobación de shell que compara la fecha de modificación del archivo DTCG contra la última nota de auditoría en git, no una reimplementación de la lógica de escaneo de nuestro plugin. Lo guardamos en una carpeta scripts/ junto a SKILL.md. La guía de empaquetado de Anthropic es comprimir la skill con el nombre de la carpeta coincidiendo con el name de la skill, y la propia carpeta como raíz del ZIP, no como subcarpeta:

design-token-governance/
├── SKILL.md
├── scripts/
│   └── check-dtcg-freshness.sh
└── resources/
    └── token-naming-conventions.md

token-naming-conventions.md es el tercer nivel - un archivo de referencia al que apunta el cuerpo de la skill pero que Claude solo abre para un caso límite (una cadena de alias, un nombre de primitivo obsoleto) que de otro modo saturaría las instrucciones principales. Prueba la invocación antes de confiar en esto en un PR real: prueba prompts que deberían activar la skill, lee el razonamiento de Claude para confirmar que realmente la cargó, y ajusta la descripción si no lo hizo.

Agent Skills vs paquetes AGENTS.md vs prompts puntuales

Los equipos de design system ya manejan tres formas de dirigir un asistente de código con IA, y es fácil usar la equivocada. La tabla siguiente es la distinción que importa antes de empaquetar nada.

Agent Skills vs paquetes de reglas AGENTS.md vs prompts puntuales

Las tres capas no compiten entre sí. AGENTS.md sigue siendo dueño de la política de todo el repo - rutas de tokens, nomenclatura, lo que un PR nunca debe hacer - el mismo terreno que cubrimos en Skills de IA para Diseñadores. Una Agent Skill se sitúa por encima como un procedimiento que Claude invoca para un trabajo recurrente; un prompt es lo que escribes cuando el trabajo no va a pasar dos veces.

Dónde encaja la skill en el pipeline de tokens

Una skill es tan fiable como aquello que comprueba. Si el archivo de Figma detrás de tokens.json todavía tiene fills sin tokenizar, la skill puede confirmar que la exportación está fresca y aun así dar el visto bueno a un componente que referencia un color que nadie vinculó a una variable - la exportación DTCG era correcta, el archivo de Figma no. La gobernanza en Figma tiene que ocurrir antes de que la skill tenga algo fiable que comprobar.

Variables de Figma (Primitivos → semánticos → componente)
        ↓ escaneo de valores sin tokenizar + auditoría de cobertura / contraste
JSON DTCG  +  tokens.css  (git)
        ↓
design-token-governance/SKILL.md  (name, description, scripts/check-dtcg-freshness.sh)
        ↓
Claude Code  (invoca la skill antes de tocar componentes tokenizados)
        ↳ opcional: Figma Dev Mode MCP para contexto de selección en vivo

Lee el diagrama como una cadena de dependencia, no como una checklist que se ejecuta una sola vez. Cada vez que cambia la biblioteca de Figma, la exportación tiene que volver a ejecutarse antes de que la comprobación de frescura de la skill signifique algo - por eso mismo la skill comprueba un timestamp en lugar de confiar en que alguien se acordó.

Errores que evitar al empaquetar un flujo como skill

• Escribir una descripción tan genérica que Claude nunca la invoca - “ayuda con tokens de diseño” no coincide con nada; “verifica que los tokens DTCG exportados estén actualizados antes de editar componentes estilados” coincide con un momento real dentro de un PR.
• Enviar un script que asume rutas que tu repo no tiene - prueba la skill contra la ubicación real de tokens.json antes de confiar en ella.
• Saltarte la auditoría de cobertura y contraste en Figma y esperar que la skill detecte una deriva que no puede ver - una skill lee lo que hay en git, no lo que está sin vincular en el lienzo.
• Construir una skill gigante que intenta cubrir escaneo, exportación y revisión de código a la vez - skills más estrechas que se combinan son más fáciles de elegir correctamente para Claude que una que intenta hacerlo todo.
• No probar nunca la invocación - prueba varios prompts que deberían activar la skill, lee el razonamiento de Claude para confirmar que se cargó, y luego itera sobre la descripción si no lo hizo.

Veredicto final - Skill de Claude para tokens de diseño

Una skill de Claude no va a arreglar un archivo de Figma donde los colores todavía se escriben como hex - nada invocado después del hecho deshace la gobernanza que te saltaste antes. Lo que hace bien es convertir un flujo que tu equipo ya ejecuta por costumbre - escanear, auditar, exportar, sincronizar - en algo que Claude Code comprueba cada vez, sin que un compañero tenga que acordarse de preguntarlo. Escribe la descripción con precisión, mantén la skill enfocada en un solo trabajo, y prueba la invocación antes de confiar en ella en un PR real.

FAQ

Para la arquitectura de tokens que esta skill asume, empieza por la guía de tokens de diseño. Para los pasos de gobernanza que comprueba, consulta auditoría de cobertura vs valores sin tokenizar y auditoría de contraste. Para la capa de reglas que gobierna cómo Claude escribe código día a día, consulta Skills de IA para Diseñadores. ¿Tienes preguntas generales? Consulta las preguntas frecuentes de Atomize.