Christian Ramírez's blog

How to Turn Your Design System into a skill.md to Supercharge AI-Powered Design

contact@ramirezchristian.com (Christian Ramírez) — Sat, 31 Oct 2026 00:00:00 GMT

AI-powered development tools are changing the way digital products are designed and built. Tools such as Cursor, Claude Code and Codex can generate interfaces, write code and help teams move from an idea to a working product faster than ever.

However, speed does not automatically mean quality or consistency. Without the right context, AI can make arbitrary design decisions, introduce inconsistent components, ignore established patterns or generate interfaces that do not follow the product’s visual language.

This is where your Design System becomes essential.

By transforming your Design System into an AI Skill, you can give AI agents structured knowledge about your design principles, tokens, components and patterns. Instead of relying on generic instructions in every conversation, the agent can use a reusable set of guidelines to make decisions that are much closer to the standards of your product.

In this article, we’ll explore how to prepare your Design System, structure a SKILL.md file, generate it with AI and integrate it into tools such as Cursor, Claude Code and Codex.

1. What is a Skill, and why does your Design System need one?

A Skill is a structured set of instructions and resources that an AI agent can use to perform a specific task or work within a particular context.

Unlike a simple prompt, which provides instructions for a single interaction, a Skill is reusable. It gives the agent access to a consistent set of rules, workflows and supporting documentation that can be applied whenever the relevant task comes up.

For a Design System, this means defining how the AI should use your design language: which tokens to apply, which components are available, how they should be combined, what patterns to follow and which decisions should be avoided.

A well-structured Skill helps reduce several common problems:

Inconsistent interfaces: the AI uses the same design rules across different screens and features.
Invented components: the agent is encouraged to reuse existing components instead of creating unnecessary alternatives.
Incorrect token usage: colors, typography, spacing and other values follow the established system.
Repeated instructions: teams do not need to explain the same design rules in every prompt.
Faster implementation: the agent can spend more time solving the actual problem instead of guessing how the product should look.

The important distinction is that a Skill does not replace your Design System or become its ultimate source of truth. Your official documentation, design files, tokens and component code remain the authoritative sources. The Skill acts as a structured knowledge layer that helps AI understand and apply them correctly.

2. Analyse your Design System before creating the Skill

Before writing a SKILL.md, you need to understand what your Design System contains and which information an AI agent actually needs.

A common mistake is to simply export all existing documentation and give it to the AI. More information does not necessarily mean better results. The objective is to identify the rules and resources that have the greatest impact on design and implementation decisions.

I recommend organising the audit into five areas.

1. Foundations and design tokens

Start with the foundations of your visual language. Identify the tokens that define the system, including:

Colour palettes and semantic colour tokens.
Typography families, sizes, weights and line heights.
Spacing and sizing scales.
Border radii and borders.
Shadows and elevation.
Breakpoints and responsive behaviour.

Whenever possible, use the actual token names and values from your source files. Avoid manually recreating them, as this can introduce inconsistencies.

2. Components

Document the components available in your system, including their purpose, variants, states and usage rules. Prioritise the most frequently used components, such as buttons, inputs, navigation, cards, modals and tables.

The agent should understand not only what a component looks like, but also when and how to use it.

3. Patterns

Patterns describe how components work together to solve recurring interface problems. Examples include forms, filters, search experiences, data tables, onboarding flows and navigation structures.

This information is particularly valuable because AI often generates technically valid interfaces that lack a coherent user experience.

4. Principles and accessibility

Include the principles that guide your product decisions: hierarchy, consistency, usability, responsive behaviour and accessibility.

Document relevant requirements such as keyboard navigation, focus states, colour contrast, labels and semantic HTML.

5. Sources and implementation

Finally, identify where the official information lives. This might include Figma libraries, a token repository, Storybook, component documentation or an internal website.

The Skill should point the agent towards these resources rather than becoming a disconnected copy that is difficult to maintain.

3. Define the structure of your Skill

A Skill should be easy for an AI agent to understand, navigate and maintain. The recommended approach is to keep the main SKILL.md focused on essential instructions and move detailed documentation into separate reference files.

A practical structure could look like this:

design-system/
├── SKILL.md
├── references/
│   ├── foundations.md
│   ├── color-tokens.md
│   ├── typography.md
│   ├── components.md
│   ├── patterns.md
│   └── accessibility.md
├── assets/
│   └── examples/
└── scripts/
    └── validate-tokens.js

Each folder has a specific purpose:

SKILL.md: the main entry point. It defines the agent's role, rules, workflow and links to supporting resources.
references/: detailed documentation about tokens, components, patterns and accessibility.
assets/: visual examples, diagrams or other supporting resources.
scripts/: optional tools for checking tokens, validating files or automating repetitive tasks.

This modular structure makes the Skill easier to update. You can change a component reference without rewriting the entire instruction file.

4. Build your SKILL.md

The SKILL.md file is the core of the Skill. It should explain what the agent is expected to do, when the Skill applies and which rules it must follow.

For example, imagine a fictional Design System called Nova Design System. Its main objective is to help AI agents create interfaces that are consistent with the product's established visual language.

A simplified but practical example could look like this:

---
name: nova-design-system
description: >
  Use this skill when designing, implementing or reviewing
  user interfaces that must follow the Nova Design System.
---

# Nova Design System

## Purpose

You are working with Nova Design System, the official
design language for our digital products.

Your responsibility is to create consistent, accessible
and responsive interfaces by following the existing
design tokens, components and interaction patterns.

## Core principles

- Always prioritise existing components.
- Never invent design tokens when an official token exists.
- Follow semantic colour and typography definitions.
- Maintain consistent spacing and visual hierarchy.
- Design for responsive behaviour.
- Follow accessibility best practices.

## Design tokens

Before using visual values, consult:

- references/foundations.md
- references/color-tokens.md
- references/typography.md

Never introduce arbitrary colours, spacing values
or typography styles when an equivalent token exists.

## Components

Use the components documented in:

- references/components.md

Before creating a new component:

1. Check whether an existing component can be reused.
2. Check whether an existing variant solves the problem.
3. Only propose a new component when necessary.

Do not create alternative versions of existing
components without a clear justification.

## Patterns

Follow the established interaction and layout patterns
documented in:

- references/patterns.md

Prioritise consistency over unnecessary visual variation.

## Accessibility

All interfaces must follow the guidelines in:

- references/accessibility.md

Consider keyboard navigation, focus states,
semantic structure, labels and colour contrast.

## Workflow

When asked to create or modify an interface:

1. Understand the requirements and user goal.
2. Review the relevant design tokens and components.
3. Identify existing patterns that can be reused.
4. Build the interface using the Design System.
5. Check responsive behaviour and accessibility.
6. Review the result for visual consistency.

## Final validation

Before completing the task, verify that:

- Official tokens have been used.
- Existing components have been prioritised.
- No unnecessary styles or components were introduced.
- The interface follows the established patterns.
- Accessibility and responsive behaviour have been considered.

This example provides the agent with a clear framework for making decisions. The detailed documentation remains in the reference files, while the main Skill defines how that information should be used.

The result is not simply a collection of instructions. It is a reusable way of working that gives the agent a consistent design context.

5. Use AI to generate your Skill

You do not need to write the entire Skill manually. AI can help audit your existing documentation, extract relevant information and organise it into a suitable structure.

However, it is important to work in stages. Asking an agent to generate a complete Skill from a large collection of files in a single prompt can produce incomplete or inaccurate documentation.

I recommend a three-stage process.

Stage 1: Audit the existing Design System

Give the agent access to your repository, documentation or exported design system files.

Use a prompt such as:

Analyse this Design System and identify its foundations, design tokens, components, variants, states, interaction patterns and accessibility guidelines.
Do not invent missing information. Use the existing source files as the reference and identify any inconsistencies, gaps or undocumented areas.
Organise the findings into a structured report that can be used to create an AI Skill.

Stage 2: Generate the documentation

Once the audit is complete, ask the agent to create the reference files.

Based on the audit, generate a structured documentation system for an AI Skill.
Create separate Markdown files for foundations, colour tokens, typography, components, patterns and accessibility.
Preserve official token names and values. Document component variants, states and usage rules.
If information is missing, explicitly mark it as undocumented instead of making assumptions.

Stage 3: Generate and validate SKILL.md

Finally, ask the agent to create the main instruction file.

Create a SKILL.md file that uses the generated documentation as its reference.
Define the Skill's purpose, activation description, core principles, implementation rules and workflow.
The instructions must prioritise existing components and tokens, prevent unnecessary design decisions and require accessibility and responsive validation.
Check that all referenced files exist and that the Skill follows the Agent Skills specification.

The final step is important: review the generated documentation against the actual Design System. AI can help organise information, but it should not be trusted to invent rules or resolve ambiguities without validation.

6. Integrate the Skill into your AI tools

One of the advantages of the Agent Skills format is that it provides a reusable structure that can work across compatible AI tools.

The exact installation method depends on the tool and its current support, but the following locations are useful starting points.

Cursor

Cursor supports Agent Skills and project-level configuration. You can place your Skill in the project's .agents/skills/ directory:

your-project/
└── .agents/
    └── skills/
        └── nova-design-system/
            ├── SKILL.md
            └── references/

Cursor can then use the Skill when a task matches its description.

Documentation: https://cursor.com/docs/skills

Claude Code

Claude Code supports Skills through the .claude/skills/ directory:

your-project/
└── .claude/
    └── skills/
        └── nova-design-system/
            ├── SKILL.md
            └── references/

You can also install Skills at user level when you want to reuse them across projects.

Documentation: https://code.claude.com/docs/en/skills

Codex

Codex supports Agent Skills and can discover project-level Skills from .agents/skills/:

your-project/
└── .agents/
    └── skills/
        └── nova-design-system/
            ├── SKILL.md
            └── references/

Documentation: https://developers.openai.com/codex/skills/

For cross-tool compatibility, follow the Agent Skills specification and check the latest documentation for each platform. Although the format is designed to be portable, individual tools may have additional conventions or differences in how they discover and execute Skills.

Specification: https://agentskills.io/specification

7. Take your Skill further with Figma, MCP and your code repository

A SKILL.md is a strong starting point, but its potential increases when the agent can access the actual resources behind your Design System.

Connect Figma through MCP

The Model Context Protocol (MCP) allows AI applications to connect to external tools and data sources through a standardised interface.

With a suitable Figma MCP integration, an agent can retrieve design information and inspect relevant files, depending on the capabilities and permissions of the integration.

This helps bridge the gap between design documentation and implementation. Instead of relying exclusively on written descriptions, the agent can work with additional design context.

Connect the token repository

If your Design System stores tokens in JSON, CSS variables or another structured format, give the agent access to those files.

For example:

:root {
  --color-primary: #2563eb;
  --color-text: #172033;
  --spacing-md: 16px;
  --radius-md: 8px;
}

The values above are illustrative. In a real project, the agent should use the actual tokens from your repository rather than copying example values.

Use Storybook and component documentation

If your project uses Storybook, include its documentation and component examples as references. This gives the agent a clearer understanding of available components, their properties and their expected behaviour.

The combination of a Skill, design documentation, Figma context and real implementation files creates a much more reliable environment for AI-assisted work.

8. Validate and maintain your Skill

A Skill is not something you generate once and forget. Design Systems evolve, components change and new patterns emerge. Your AI instructions must evolve with them.

I recommend incorporating a validation process into your regular Design System maintenance.

Check that:

Every referenced documentation file exists.
Token names and values match the official source.
Component variants and states are up to date.
Deprecated components are clearly identified.
Accessibility requirements are still valid.
The agent is not introducing arbitrary styles or unnecessary components.

You can also test the Skill with a small set of representative tasks: create a form, build a responsive dashboard, implement a navigation menu or review an existing screen.

Compare the results against your Design System guidelines. If the agent repeatedly makes the same mistake, improve the relevant instruction or reference documentation.

Whenever possible, automate the checks that can be verified programmatically, such as token consistency, missing references and deprecated values.

9. Your Design System is also knowledge for AI

The real opportunity is not simply getting AI to generate interfaces faster. It is giving AI the context it needs to make better design and implementation decisions.

A Design System already contains a significant amount of knowledge: visual rules, interaction patterns, accessibility requirements, component behaviour and product conventions. However, that knowledge is often distributed across Figma, documentation, code repositories and the experience of individual team members.

A well-designed Skill helps bring that knowledge into the AI workflow in a structured and reusable way.

It does not replace designers, design decisions or the Design System itself. Instead, it gives AI agents a more reliable framework to work within, reducing arbitrary decisions and making their output more consistent with the product.

As AI becomes an increasingly important part of digital product development, the quality of the context we provide will become just as important as the capabilities of the models themselves.

The better your Design System communicates its rules, the better AI can apply them.

Official resources

SEO

SEO title: How to Turn Your Design System into a SKILL.md for AI

Slug: design-system-skill-md-ai

Meta description: Learn how to turn your Design System into a reusable SKILL.md for Cursor, Claude Code and Codex. A practical guide to tokens, components, AI workflows and consistent interfaces.

Estimated reading time: 12–15 minutes.

The new role of the designer in the age of artificial intelligence

contact@ramirezchristian.com (Christian Ramírez) — Tue, 13 Oct 2026 00:00:00 GMT

The new role of the designer in the age of artificial intelligence

For years we have talked about the need for designers to learn to code in order to better understand the digital product. Today, artificial intelligence is changing the rules of the game and, with them, the way we understand the role of the designer should change too. AI is making it far more accessible to develop an application: generating code, creating components, building interfaces, connecting services or catching bugs are tasks that can increasingly be done with ease using these tools. The barrier to entry for building software is dropping considerably, and here an interesting paradox appears: the easier it is to build software, the more important it becomes to know which software is worth building.

Code is becoming a medium

Using AI in development is no longer experimental. According to the 2025 Stack Overflow survey, 84% of the developers surveyed use or plan to use AI tools in their development process. However, 46% say they distrust the accuracy of the results, and 66% point to solutions that are "almost right" as their main frustration. This shows something important: generating code is getting easier all the time, but deciding whether the result is good still takes human judgment.

An AI can build a perfectly functional interface and still make it hard to use, barely accessible, or unable to properly solve the user's problem. An application can be technically well built and still be a bad experience. And that is where the designer takes on a new dimension.

Designing is much more than designing screens

The value of a product designer has never been only knowing how to use Figma. A good designer has to understand the problem, know their users, structure information, design flows, anticipate errors and make an experience understandable, accessible and pleasant. That means mastering disciplines such as information architecture, usability, accessibility, interaction design, visual hierarchy, responsive design and the consistency of design systems.

The W3C itself includes within UX aspects such as user journeys, information architecture, wireframes and prototypes, and treats accessibility as something that should be part of the design process, not just a technical check at the end. That is why, when we can ask an AI to build an application for us, the truly important question should not only be how to build it, but what experience it should offer and what problem it should solve.

The designer as orchestrator

Traditionally, the process of creating a digital product could be summed up as problem, design, development and product. With the new AI tools, the process can evolve into a model in which the designer defines the strategy, designs the solution, sets its rules and uses AI to generate a first implementation that is then tested, evaluated and improved iteratively.

Their value is not necessarily in writing every line of code, but in knowing how to steer the process towards a good solution. This opens a possibility that was much harder a few years ago: a designer with a solid grasp of product can take an idea all the way to a working application without mastering all the languages and frameworks traditionally needed to develop it. AI is, to a certain extent, democratizing the ability to build software and allowing designers to take a much more direct part in bringing their ideas to life.

Development knowledge as a multiplier

This does not mean designers no longer need to learn development. On the contrary, I believe that understanding technology can become an even bigger advantage. A designer who understands HTML, CSS, JavaScript, components, APIs, databases, architecture or the limitations of a technology has an advantage over someone who uses AI as a black box. They don't need to become the best programmer on the team, but they do need to understand the medium they are working in well enough.

That knowledge lets them design technically more viable solutions, spot errors in AI-generated implementations, write more precise instructions, critically evaluate technical decisions, prototype faster and communicate better with developers when the project needs specialists. That is why I don't believe the future is a competition between designers and developers, or that AI will make the latter unnecessary. The real opportunity lies in expanding the capabilities of both profiles and using technology to work better.

When building is cheap, judgment gets expensive

For a long time, one of the great barriers to turning an idea into a digital product was the technical ability needed to build it. Today that barrier is shrinking, and a person with product and design knowledge can have a building capacity that would previously have required a much larger team. However, this also means it will be easier and easier to create mediocre applications.

When anyone can generate an interface, write code and build a prototype, differentiation is no longer only about who can do it, but about who knows what to build and how to build it well. AI can generate code, components and interfaces and even propose solutions, but someone has to decide which one makes sense, understand the user, spot a confusing interaction, question a decision, take accessibility into account and recognize which elements are surplus. That someone can be the designer.

From interface designers to product builders

Perhaps we are entering a stage in which the designer stops being only the person who designs and hands over specifications, and also becomes a builder and orchestrator of digital products. A designer can imagine a solution, design it, use AI to build a first version, test it, spot problems and iterate again. The distance between having an idea and having something working that can be tested is shrinking enormously.

In this context, a designer without deep development knowledge can use AI to build much more than they could before. But a designer who also understands development can better grasp the possibilities, spot the limitations and steer what the AI produces more precisely. Technical knowledge does not disappear: it becomes a multiplier of the designer's capability.

That is why I don't believe artificial intelligence is reducing the value of design, but changing where that value lies. When producing software gets cheaper, judgment becomes more important. And when building an application is within reach of more people, knowing what to build, for whom, why and how to make it really work can become one of the most valuable skills in digital product.

Perhaps the future of design is not only about designing and handing over, but about imagining, defining, building, testing, learning and building again. In that scenario, the designer does not lose relevance: they widen their field of action.

Why you should start using Figma for your UX/UI design projects

contact@ramirezchristian.com (Christian Ramírez) — Sat, 16 Mar 2024 00:00:00 GMT

In the world of UX/UI design, choosing the right tool can make the difference between a successful project and one that isn't. In this sense, Figma has stood out as a leading option that has earned the trust of designers all over the world. Here I'll explain why you should consider using Figma for your next projects:

1. Real-time collaboration

Figma gives you the ability to collaborate in real time with colleagues and clients, which makes the design process much easier. Unlike other tools where heavy files are constantly sent and received, Figma lets several users work on the same project at the same time, which speeds up workflows and encourages smoother communication.

2. Accessibility and cross-platform support

One of Figma's biggest advantages is its accessibility. As a cloud-based application, you can access your projects from any device with an Internet connection. This removes the barriers related to file compatibility and guarantees that you can work without problems on your desktop computer as well as on your mobile device or tablet.

3. Interactive prototyping

Figma offers powerful prototyping tools that let you create interactive user experiences quickly and easily. With features such as linking screens, transitions and animations, you can accurately simulate what the final user experience will be like, which helps you identify and fix usability problems before the design is implemented.

4. Shared libraries and components

Figma makes it easy to create and manage shared libraries of components and styles, which guarantees visual consistency and efficiency in design. You can create reusable components, such as buttons or navigation bars, and share them between different projects or teams. This not only speeds up the design process, but also helps keep consistency across your whole application or website.

Success stories

Numerous well-known companies and design teams have adopted Figma as their main tool for UX/UI projects. Notable examples include the design teams of companies such as Airbnb, Slack and Uber. These organizations have praised Figma's ability to improve collaboration, efficiency and design quality, which has contributed to the success of their products.

In short, Figma offers a complete and flexible platform that adapts to the needs of modern UX/UI designers. With its real-time collaboration, cross-platform accessibility, powerful prototyping tools and component management, Figma has become the preferred choice for those who want to take their design projects to the next level.