Design System: Add portable agent skills

[ciampo]

Closes #77209

What?

Adds four portable WordPress Design System skills and scoped maintainer guidance for the Design System packages.

Why?

UI work should assess whether the documented Design System already meets the user need, including when a change does not yet use its packages. Package changes need a separate, source-aware workflow.

How?

• Adds UI composition and review skills that assess public Design System use for any UI/UX change.
• Adds contribution and package-review skills for @wordpress/components, @wordpress/ui, and @wordpress/theme.
• Adds scoped AGENTS.md routing and a concise cross-package contributor guide.

Testing Instructions

1. Read skills/design-system-ui-review/SKILL.md; confirm it applies to UI/UX diffs even when they have no existing Design System imports.
2. Read skills/design-system-ui-composition/SKILL.md; confirm an external consumer records an upstream request when a public API is missing, while a Gutenberg checkout routes the work to package contribution.
3. Open a Design System package directory and confirm its AGENTS.md points maintainers to the package-specific guidance.

Use of AI Tools

Codex was used to implement and validate this change. The resulting content was reviewed against the target package documentation and contributor guidance.

[github-actions]

Size Change: 0 B

Total Size: 7.75 MB

_{compressed-size-action}

[Copilot]

Pull request overview

Copilot reviewed 16 out of 16 changed files in this pull request and generated no new comments.

[ciampo]

Update: rebased and included changes from #81400. I also incorporated the useful parts of #77264 without adding static component inventories or blanket migration rules.

I asked an agent to create and execute a blinded local benchmark, which found a focused, repeatable improvement: 2 PR wins, 0 trunk wins, and 3 ties, with no critical errors. The clearest gain was correct guidance for Design System tokens in block-facing front-end CSS.

Changes and evaluation details

Changes after the rebase

• Kept the four scoped skills for consumer composition, consumer review, package contribution, and package review.
• Kept the cross-package Design System guide and the checks for target versions, public versus private APIs, compatibility, external consumers, portals and iframes, documentation, generated files, and releases.
• Preserved UI: Add initial agents guidance mapping to contributing guidelines #81400's minimal packages/ui/AGENTS.md. Package-level AGENTS.md files remain routers to maintained guidance rather than copied summaries.
• Dropped the root AGENTS.md change because trunk now covers that routing.
• Clarified that @wordpress/components remains supported and that recommendations are selected component by component. The guidance points to the Design System MCP, Storybook metadata, and maintained lint sources instead of copying a package/component table.
• Incorporated the useful token distinction from AGENTS.md: Add design system package guide #77264:
  • --wpds-* for Design System interface styling.
  • --wp--preset--* for theme.json presets and block-facing styles.
• Did not retain AGENTS.md: Add design system package guide #77264's static root table, blanket @wordpress/ui preference, visual-inconsistency claim, or DataViews import warning.
• Ran an adversarial self-review and addressed all actionable findings.

Blinded control-versus-PR evaluation

Each valid run used a clean arm-neutral checkout, a fresh ephemeral agent, the same model and reasoning effort, zero retries, and the same WordPress Design System MCP access. Memories, plugins, and apps were disabled. Fresh graders scored neutral X/Y outputs against rubrics frozen before the runs.

Task	PR	Trunk	Result
Implement a controlled checkbox consumer	9	9	Tie
Review external block CSS using bare WPDS tokens	10	6	PR win
Route a proposed DataExplorer contribution	10	10	Tie
Review a source-only Theme token patch	9	10	Tie; below the two-point win threshold
Repeat the external block-token review	10	8	PR win

The repeatable gain came from the new namespace guidance. Both trunk agents found the missing-token runtime problem, but the PR agents also distinguished Design System interface tokens from block-facing theme presets. This prevented advice to load admin Design System assets merely to satisfy front-end block declarations.

The other task families were neutral: trunk already selected the correct public checkbox, routed the higher-level data interface to @wordpress/dataviews, and caught missing generated Theme outputs and changelog work.

For transparency, I discarded the first evaluation wave when I detected local memory leakage. I also discarded an original token test after repository evidence showed that its expected answer ignored Gutenberg's build-time fallback injection. The replacement standalone-plugin test and rubric were fixed before either replacement arm ran.

So the evidence supports a narrow claim: this PR improves token-boundary reviews without showing regressions in the other sampled Design System workflows. It is not yet evidence that every agent task improves.

[aduth]

I'm curious to try this out and iterate 👍 Though I also share some of the trepidation around whether the improvements are measurable, and look forward to more quantitative ways of tracking this (e.g. #80758). I like how a lot of what's being proposed here is linking together documentation that already exists in ways that helps lead agents to established guidance, and that we continue to expose new guidance in ways that is accessible to humans as well (the design system packages guide). I'll be honest and say that a lot of the content reads as heavy LLM-speak to me in ways that felt hard for me to parse, but I also can't discount that perhaps this is okay if humans are not necessarily the target audience of the content.

[aduth]

Noting that this isn't totally aligned with where else we document the packages of the design system: i.e. excludes @wordpress/icons, includes @wordpress/components, doesn't distinguish packages like @wordpress/admin-ui or @wordpress/dataviews as being part of the design system.

Including @wordpress/components might be pragmatic for now, but I don't know that we'd want it here long-term?

[aduth]

On this note too, I wonder if it would be valuable to include the Design System "Introduction" Storybook page as one of the reference links here.

[ciampo]

The opening now links to the Design System introduction as the source for the full foundational and compositional package map.

It also explains this guide's narrower scope, ie. @wordpress/components is included because it remains a supported public package during the current component transition, not to redefine the overall Design System package taxonomy.

[aduth]

Will these root-relative URLs work everywhere the documentation is shown (e.g. the developer site)? Elsewhere we use relative paths.

[ciampo]

I followed these docs.

We should probably do a repo-wide scan to ensure we use paths consistently

[aduth]

In human terms, what exactly are we asking people to do here?

[ciampo]

😅 I rewrote it in a hopefully more concrete manner:

The section now asks contributors to identify where the package comes from in production, then covers three cases: a Gutenberg checkout, an application-bundled package, or a package supplied by the minimum supported WordPress version. It also defines “externalized” before asking readers to inspect build metadata.

[aduth]

This might work for human readers, but AI won't be able to scrape the live Storybook and would probably be better pointed to the Storybook source files.

[ciampo]

Good point. The fallback now directs agents to the component's *.story.* source file and its componentStatus metadata in the target checkout. The rendered Storybook remains linked as the human-readable companion.

[aduth]

I'd be curious if we need this line: If an agent harness touches files in tokens/, we should expect it will automatically load tokens/AGENTS.md. And if it doesn't, it wouldn't be reading this file to begin with.

[ciampo]

Removed, following your reasoning.

[aduth]

Similarly, if an agent knows what skills it has and when they should be triggered, I wouldn't expect that we'd need to tell them about them here as well.

[ciampo]

Also removed