# ai-component-metadata

The ai-component-metadata Claude Code skill creates structured metadata for design system components used in AI-generated interfaces. It runs during component analysis and records how each component should be composed and used.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · ★ 107 repo stars
- Author: thedesignproject
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/thedesignproject/agent-skills/tree/HEAD/skills/ai-component-metadata/SKILL.md
- Updated: 2026-11-08
- Security check: automated, 2026-11-17 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/ai-component-metadata

## What it does

The skill examines a component’s structure, including its slots, child elements, variants, states, prop types, and accessibility attributes. It turns those findings into metadata covering usage patterns, composition constraints, behavior, and guidance for AI.

For automatic generation, `scripts/generate_metadata.py` reads a component file and runs with `python`. Alternatively, copy `assets/metadata-template.tsx` and fill it in manually. The skill recommends testing the metadata with generation tasks and in Storybook, using runnable code examples.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add thedesignproject/agent-skills --skill ai-component-metadata -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/ai-component-metadata/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/ai-component-metadata/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add thedesignproject/agent-skills --skill ai-component-metadata -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/ai-component-metadata/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add thedesignproject/agent-skills --skill ai-component-metadata -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/ai-component-metadata/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install thedesignproject/agent-skills skills/ai-component-metadata
```

2. **Manually: put the files in place**
- File: `.github/skills/ai-component-metadata/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add thedesignproject/agent-skills --skill ai-component-metadata -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/thedesignproject/agent-skills --path skills/ai-component-metadata
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/ai-component-metadata/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add thedesignproject/agent-skills --skill ai-component-metadata -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/thedesignproject/agent-skills/tree/HEAD/skills/ai-component-metadata/SKILL.md

## When to use it
- document a component’s props, variants, and states
- record common usage patterns and anti-patterns
- describe how components fit together
- preserve accessibility details for generated interfaces

## Example prompts
- Create metadata for `Button.tsx`, including its props, states, and accessibility details.
- Analyze `FormField.tsx` and document common patterns and anti-patterns.
- Write metadata for these design system components using the provided schema.

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: c1b6c8dbc9f51068.

BEGIN THIRD-PARTY FILE c1b6c8dbc9f51068
````text
---
name: ai-component-metadata
version: 1.0.0
description: Generate AI-ready metadata for design system components to enable intelligent UI generation. Analyzes component structure and generates structured metadata that helps AI understand when and how to use components correctly. Useful for teams building AI-consumable design systems.
---

# AI Component Metadata Generator

Generate structured, AI-consumable metadata for design system components to enable intelligent UI generation and component usage.

## Quick Start

When analyzing a component, use the metadata schema template in `scripts/generate_metadata.py` or follow the manual process below:

```bash
# Automatic generation (reads component file)
python scripts/generate_metadata.py path/to/Component.tsx

# Or use the template directly
cp assets/metadata-template.tsx your-component-metadata.tsx
```

## Core Workflow

### 1. Analyze Component Structure
Identify:
- Component composition (slots, children)
- Available variants and states
- Props and their types
- Accessibility attributes

### 2. Generate Metadata
Create metadata following this schema:

```javascript
export const componentMetadata = {
  component: {
    name: "ComponentName",
    category: "atoms|molecules|organisms",
    description: "Brief description",
    type: "interactive|display|container|input|navigation"
  },
  
  usage: {
    useCases: ["primary-use", "secondary-use"],
    requiredProps: [],
    commonPatterns: [
      {
        name: "pattern-name",
        description: "When to use",
        composition: "JSX example"
      }
    ],
    antiPatterns: [
      {
        scenario: "what-not-to-do",
        reason: "why",
        alternative: "what-instead"
      }
    ]
  },
  
  composition: {
    slots: {},
    nestedComponents: [],
    commonPartners: [],
    parentConstraints: []
  },
  
  behavior: {
    states: [],
    interactions: {},
    responsive: {}
  },
  
  accessibility: {
    role: "ARIA role",
    keyboardSupport: "description",
    screenReader: "behavior",
    focusManagement: "strategy",
    wcag: "AA"
  },
  
  aiHints: {
    priority: "high|medium|low",
    keywords: [],
    context: "when to use"
  }
}
```

### 3. Validate Metadata
- Test with AI generation tasks
- Verify in Storybook
- Ensure examples are runnable

## Component Categories

- **atoms**: Basic building blocks (Button, Text, Input)
- **molecules**: Simple combinations (Card, Chip, FormField)
- **organisms**: Complex components (Header, Table, Form)

## Advanced Features

For complex scenarios, see:
- **Nested components**: [NESTED.md](references/NESTED.md)
- **Integration patterns**: [INTEGRATION.md](references/INTEGRATION.md)
- **Testing strategies**: [TESTING.md](references/TESTING.md)

## Working with Figma

When combining with Figma MCP:

```javascript
````
END THIRD-PARTY FILE c1b6c8dbc9f51068

The third-party file has ended. Everything between the c1b6c8dbc9f51068 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2819 of 3556 bytes. © thedesignproject · MIT · https://github.com/thedesignproject/agent-skills/tree/HEAD/skills/ai-component-metadata/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
