Repository navigation
Design System: Provide agent skills for design system usage workflows #77209
Description
Sub-issue of: #77205
What problem does this address?
Today, working with AI agents to achieve a task that uses the design system, agents often struggle to know how to accomplish those tasks.
Workflows such as:
- Adapting a design to implementation (from Figma, etc.)
- Proposing a feature or contributing to the design system, including context-gathering of past discussions and decisions
- Code review of a design system contribution
- Implementing a component with best practices
What is your proposed solution?
We should provide a set of agent skills for accomplishing design system-adjacent tasks. These should be usable both within Gutenberg as well as external projects.
Agent Skills are a standardized format for giving AI agents the informed capability to accomplish tasks like those described above.
Caution: We should acknowledge that the workflows described above are those which a human should want to understand and follow as well, and we should seek to reduce duplication and avoid preferential treatment to one audience over another.
This is separate-but-complementary from an MCP server (#77206), which would describe the resources available within the design system. The scope of agent skills should cover how to accomplish design system tasks.
Prior art:
There already is a "WordPress Design System Skill", and I would recommend that this improve and replace it:
- A single, monolithic "mega-skill" for the design system is likely not as effective as task/workflow-specific skills, as this is fundamentally how skills work in activating
- A skill should ideally be useful without a paired dependency on an MCP server, though it's likely that it would complement and use MCP tools if available
Open Questions:
- It's unclear if the implementation should live here in Gutenberg alongside the implementation of Gutenberg, or in WordPress/agent-skills along with other WordPress agent skills. This may also influence the distribution vehicle, since WordPress/agent-skills provides its own custom setup process using a custom "skillpack" build script.
Implementation notes:
As described in "Open Questions", the specific implementation may vary depending on where it lives.
At the end of the day, skills are just Markdown files with a bit of metadata.
But we should be conscious that a design system is an evolving thing, and there's a challenge both in how skills are incorporated into projects that use the design system, as well as how those skills are updated over time. We also likely won't want to maintain or prefer one AI environment over another, and skills discovery is often proprietary per vendor (e.g. .claude/skills vs. .cursor/skills). A tool like Vercel's skills CLI may be useful to document the setup and update workflows in a tool-agnostic manner.
Activity
Adi-ty commentedon Apr 13, 2026
Hey @aduth, wanted to get clarity on the location question since it affects basically everything else.
The way I see it, the workflows listed here span two different audiences:
@wordpress/ui— same crowd as the existing skills in WordPress/agent-skillsSo I'm wondering if the intent is to cover both, or if the scope is primarily contributor-facing?
Also, since #77159 is in progress should the skills reference the MCP tools (
get_component_detailsetc.) and degrade gracefully without them, or can we assume they'll be used together?aduth commentedon Apr 13, 2026
Great questions @Adi-ty ! I think some of this will become clearer once we start iterating and seeing what does and doesn't work.
To your specific questions:
We'll probably want both. And that could even mean that contributor-facing skills live in a different place from the consumer-facing skills, if it makes sense to do so. On the other hand, that could introduce some unwanted complexity. We may want to be pragmatic and work on them as a collective set. I think this will also be partially informed by other factors like proximity to the source: Generally I lean toward implementing them somewhere in this project because it'll be easier to maintain the skills alongside the source implementation.
As mentioned in the initial issue description, I don't think there should be a strong dependency for the MCP server from a skill. Ideally it should be usable on its own. But: I do like the idea that it could progressively enhance if the MCP server is available. Generally I think we can expect that someone would have better results if they're also using the MCP server, so maybe the skills content should allude to using those tools if they're available, or even go as far as to encourage a user to set up an MCP server (again, not requiring, but encouraged to get the best results).
Adi-ty commentedon Apr 15, 2026
Hey @aduth, thanks for the clarity! That makes a lot of sense. I want to bounce a proposed directory structure off you to make sure we are aligned on the placement and format. I'm thinking of a vendor-agnostic, modular approach using an
.agents/skills/directory. Since you mentioned avoiding a "monolithic mega-skill", we could split it out exactly by the core workflows discussed:This way we aren't heavily preferring .claude, .cursorrules, or Copilot. Since these are specifically Design System skills, should this structure live at the repository root (e.g., /.agents/skills/), or should it live directly inside the package (e.g., packages/components/.agents/skills/) to keep it as close to the source implementation as possible? Let me know what you think of this direction!