Metadata schema generator

A skill for generating structured JSON metadata schemas for design system components. These schemas encode everything an AI agent, MCP server, code generator, or testing framework needs to work with a component programmatically — props, behavioural rules, composition constraints, accessibility contracts, and (where the team supplies it) business context — in a format that does not require natural language parsing.

Before you begin: verify references

Confirm that every path in this skill's frontmatter references: exists relative to this SKILL.md. If any is missing, stop: the install is incomplete, usually because a flattening installer (for example npx skills install) dropped the repo-root knowledge-notes/ directory. Tell the user to reinstall by a method in 1-INSTALL.md and run verify-install.sh from the install root. Proceed without the references only if the user explicitly says to, and then say in the output that it was produced without the pack's reference material.

Context

Component documentation serves humans. Component metadata serves machines. The distinction matters because the information needs are different, the format requirements are different, and the failure modes are different.

A human reading a component's documentation can infer that "this button triggers the primary action" means it should be visually prominent and placed in the expected location. A code generation agent reading that same string cannot infer any of that — it needs explicit data: { "role": "primary_action", "visual_weight": "high", "placement": ["form_footer", "dialog_footer", "page_header"] }.

Most design systems have one layer of machine-readable data: TypeScript interfaces or PropTypes declarations that define prop names and types. This is necessary but insufficient. A TypeScript interface tells a tool that a Button accepts a variant prop of type "primary" | "secondary" | "ghost" — but it does not tell the tool when to use primary vs secondary, which combinations of props are prohibited, where the component can be placed in a layout, or what accessibility contract it must honour.

Structured metadata fills this gap. It encodes the knowledge layer between "what the component accepts" (TypeScript) and "how the component should be used" (documentation) as machine-readable data that tooling consumes directly.

The ai-component-description skill produces text descriptions optimised for LLM consumption. This skill produces structured data optimised for programmatic consumption. Together they serve the two modes of AI interaction: conversational (descriptions) and deterministic (metadata).