/metadata-schema-generator

name: metadata-schema-generator
description: "Generate per-component JSON metadata files (.ai/metadata/) from source: props, behaviour, composition, a11y contract, prohibited prop combinations. Triggers: component metadata schema, machine-readable component JSON, manifest for MCP/codegen. Prose for Figma: use ai-component-description."
allowed-tools: Read, Write, Grep, Glob, Bash(cat:*), Bash(find:*), Bash(head:*), Bash(ls:*), Bash(npx react-docgen-typescript:*), Bash(npx custom-elements-manifest:*), Bash(npx vue-component-meta:*), Bash(npx ajv:*)
references:
  - ../../knowledge-notes/ai-readiness.md
  - ../../knowledge-notes/component-bestiary-reference.md
  - ../../knowledge-notes/output-discipline.md

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).

Boundaries

This skill is the pack's one extraction of component facts. It generates structured JSON metadata for tooling — not human-readable documentation (`usage-guidelines`, `pattern-documentation`) or LLM-facing prose (`ai-component-description`); those two read `.ai/metadata/` when it exists and render from it, so the props and accessibility contract are derived once. If the system has no component inventory yet, run `codebase-index` first. If no component source is in reach, stop and ask for it: metadata can't be extracted from a description. If the team has no consumer for the files yet (no `AGENTS.md` pointing at them, no MCP server, no lint integration), say so and suggest `agent-instructions` as the first consumer rather than generating files nothing reads.

---

Configuration

If `.ds-ops-config.yml` exists, follow the configuration-and-recurring knowledge note (`../../knowledge-notes/configuration-and-recurring.md`) for loading, integration fallbacks and recurring runs. This skill reads:

• `system.framework` — determines prop extraction approach (React, Vue, Svelte, etc.)
• `system.component_paths` — directs scanning to component source files
• `integrations.*` — component data (see below)
• `metadata.schema_version` — locks the output schema version for compatibility
• `metadata.output_directory` — overrides default output location
• `metadata.include_business_context` — toggles the business context layer (default: false; see Step 4)

Auto-pull integrations

**Figma MCP** (`integrations.figma.enabled: true`):

• Read component properties, variant structures, and descriptions from `integrations.figma.file_key`
• Cross-reference Figma component properties against code props to detect mismatches
• Extract accessibility annotations if present

**Storybook** (`integrations.storybook.enabled: true`):

• Fetch prop tables and arg types from story metadata
• Extract documented states and control definitions
• Pull interaction test definitions if available

**Source** (always attempted, with the tool that fits):

• **React with TypeScript:** `react-docgen-typescript` gives name, type, required, default and description per prop; hand-read only what it can't resolve (complex generics), and say so
• **Vue:** `vue-component-meta`
• **Web Components:** the Custom Elements Manifest (`npx custom-elements-manifest analyze`, or an existing `custom-elements.json`)
• **Anything else:** read the interfaces, PropTypes and JSDoc by hand, and note under Scope that extraction was manual

---

Step 1: Select components and assess existing metadata

Ask f