ai-component-metadata — Claude Code skill: 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.
MIT ★ 107 updated 2026-11-08
npx skills add thedesignproject/agent-skills --skill ai-component-metadata -a claude-codeWhat ai-component-metadata 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.
What it helps with
- 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 for the agent
- Create metadata for
Button.tsx, including its props, states, and accessibility details. - Analyze
FormField.tsxand document common patterns and anti-patterns. - Write metadata for these design system components using the provided schema.
How to install ai-component-metadata
1Skills CLI (Vercel)
npx skills add thedesignproject/agent-skills --skill ai-component-metadata -a claude-code2Manually: put the files in place
~/.claude/skills/ai-component-metadata/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/ai-component-metadata/
1Skills CLI (Vercel)
npx skills add thedesignproject/agent-skills --skill ai-component-metadata -a codex2Manually: put the files in place
.agents/skills/ai-component-metadata/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add thedesignproject/agent-skills --skill ai-component-metadata -a cursor2Manually: put the files in place
.cursor/skills/ai-component-metadata/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install thedesignproject/agent-skills skills/ai-component-metadata2Manually: put the files in place
.github/skills/ai-component-metadata/SKILL.md1Skills CLI (Vercel)
npx skills add thedesignproject/agent-skills --skill ai-component-metadata -a gemini-cli2Platform CLI
gemini skills install https://github.com/thedesignproject/agent-skills --path skills/ai-component-metadataManually: put the files in place
.devin/skills/ai-component-metadata/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add thedesignproject/agent-skills --skill ai-component-metadata -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about ai-component-metadata
How do I install ai-component-metadata in Claude Code?
Run npx skills add thedesignproject/agent-skills --skill ai-component-metadata -a claude-code. The skill file is located at ~/.claude/skills/ai-component-metadata/SKILL.md.
What does ai-component-metadata do?
It analyzes component structure and creates metadata about usage, composition, behavior, and accessibility. AI can use that information to select and apply design system components during interface generation.
Can ai-component-metadata be used with Figma MCP?
Yes. Figma MCP can supply visual design context, while the component metadata describes behavior; AI can combine both.
Source text
SKILL.md · MIT
---
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
// Figma provides visual context
const figmaContext = await Figma.get_design_context();
// Your metadata provides behavioral context
const componentMetadata = components.Button.metadata;
// AI combines both for complete understanding
```
## Best Practices
1. **Keep examples real** - Use actual, runnable code
2. **Focus on patterns** - Document common usage patterns
3. **Include anti-patterns** - Help AI avoid mistakes
4. **Validate through usage** - Test with actual AI generation
## Success Metrics
Your metadata is effective when:
- AI uses existing components instead of recreating
- Correct variants are selected based on context
- Accessibility is maintained in generated code
- Patterns are consistent across AI outputs
© thedesignproject · MIT · thedesignproject/agent-skills