Component Usage Metadata for AI Coding Agents
Reads your component source and usage, then writes per-component metadata so AI agents pick the right component with valid props.
Before & after
Same prompt, same agent — the only difference is the skill.
Component libraries need documentation so people know when and how to use each component. You could write descriptions of what each component does and when to use it. Including information about props, variants, and state helps developers understand the API. Some teams create interactive storybooks that let you see components in different states. Automating this documentation from code comments can save work. However, the documentation needs to stay in sync with actual component implementations as they change.
AI COMPONENT METADATA OUTPUT:
METADATA GENERATION (sample 3 components)
COMPONENT: Button
Purpose: "User-initiated action triggering immediate response (submit form, toggle feature)"
When_to_use: [
"Primary action on a page or dialog",
"Form submission",
"Dismissible modal confirmations"
]
When_NOT_to_use: [
"Navigation within app (use Link instead)",
"Opening menus or dropdowns (use MenuButton)",
"Toggling binary state (use Toggle or Checkbox)"
]
Props: {
variant: "primary|secondary|danger (default: primary)",
size: "sm|md|lg (default: md)",
disabled: "boolean (prevents interaction, grays out)",
loading: "boolean (shows spinner, disables click)"
}
COMPONENT: Card
Purpose: "Self-contained content container with optional actions"
Common_patterns: [
"Card(title, description, action_button) for list items",
"Card(metric, trend_arrow, footer) for dashboard widgets"
]
Anti_patterns: [
"Never nest Card inside Card",
"Never put scrollable content directly inside Card (use CardContent wrapper)"
]
Nesting_rules: "Can contain Button, Badge, Link. Cannot contain Dialog, Modal, or Drawer."
COMPONENT: Modal
Purpose: "Center overlay blocking background interaction until closed"
Accessibility: "Traps focus, auto-focused on first interactive element, ESC key closes"
Key_props: {
isOpen: "boolean (controls visibility)",
onClose: "function (must be called on ESC, backdrop click, or close button)",
title: "string (announced to screen readers)"
}
Gotchas: [
"onClose MUST close the modal (component doesn't auto-close)",
"Backdrop click closes by default (set closeOnBackdropClick=false to disable)"
]
AI-READINESS COMPLIANCE REPORT
Total components: 40
Fully documented: 38 (95percent)
Needs revision: 2 (Breadcrumb: missing a11y labels, Tabs: unclear active indicator logic)
Metadata coverage: 98percent (all components have purpose, props, when_to_use)
DELIVERABLE FORMAT
Output: components.ai.json (machine-readable schema)
Size: 145KB
Consumable by: Claude Code, code generation agents
About this skill
Your AI coding agent keeps opening a Modal when your team uses a Drawer. It passes props that don't exist, and it rebuilds a Combobox you already ship. The fix is not more docs. The agent needs a short usage contract per component that says when to pick it over its look-alike. This skill writes that contract from your actual source code.
What it does
- Groups components into clusters an agent is likely to confuse (actions, overlays, choice inputs, feedback, containers) and writes whenToUse/whenNotToUse pairs that name the right sibling to use instead
- Takes props from your types, not your docs: exact literal unions, real defaults, controlled/uncontrolled pairs, and mutually exclusive props
- Captures the composition rules agents get wrong without any error: required providers, compound parts, what must never nest
- Records each component's accessibility contract and token constraints, so agents stop re-implementing focus traps and stop inlining hex values
- Tags every claim by source (types, usage, docs, inferred) and returns a review list of anything it inferred
- Keeps each entry short enough to load whole into agent context, and adds an index plus the line that wires it into your rules file
What you get
YAML (or Markdown) metadata entries for the requested components, a one-line-per-component index, and a short list of inferred claims for a human to confirm. If you paste existing metadata, you get a correction list instead.
Best for
Frontend and design system teams whose component library is used by Claude Code, Cursor, or other coding agents, especially teams already seeing duplicated or misused components in AI-generated UI.
SKILL.md preview
---
name: component-usage-metadata-for-ai-agents
description: Reads design system component source, types, and real call sites, then writes compact per-component metadata (task-language intent, whenToUse/whenNotToUse naming the right sibling, type-verified props, composition, a11y contract, provenance tags) that AI coding agents can route on. Use when the user says "generate metadata for our components", "make our design system AI-ready", "Claude keeps using Modal when it should use Drawer", "the agent invents props that don't exist", "Cursor keeps rebuilding components we already have", "write component guidance for AGENTS.md", "document Button and IconButton for the agent".
---
… (sign up to view the full skill)More development skills
View all Development skills →Frontend Component UX and Accessibility Review
Severity-ranked fixes with code for UI components: states, keyboard, focus, ARIA, touch targets, contrast, and responsive breakage.
Three.js Click-to-Learn 3D Game Builder
Build click-to-learn 3D games in Three.js: TSL materials, reliable object picking, and an accessible quiz overlay fed by content data.
Angular Standalone Features and State Architecture
Build Angular standalone features with lazy routes, scoped state, safe RxJS flows, and targeted tests.
shadcn/ui Component Building and Theming
Build, theme, and debug shadcn/ui components the way the library is designed to work, with Tailwind v3 and v4 theming handled correctly.