Agent-Ready Design System Audit and Scaffold
Audits or scaffolds your component library so AI coding agents pick the right component, valid props, and real tokens.
Before & after
Same prompt, same agent — the only difference is the skill.
Component libraries are important for consistency across a product. You might document what props each component accepts and what they do. There are tools for generating documentation automatically from code. You could also think about creating guidelines for when to use each component and how variants differ. Some teams write storybooks or live component explorers. Keeping documentation up to date is often a challenge though, and it can get out of sync with actual code pretty quickly.
AGENTIC COMPONENT AUDIT OUTPUT:
METADATA GENERATION
For each component, produce machine-readable spec:
Component: ButtonPrimary
Purpose: "High-emphasis actions (submit, save, critical workflows)"
Anti-patterns: [
"Do not use for navigation (use Link component)",
"Do not stack more than 2 ButtonPrimary per section",
"Avoid in modals with destructive actions (use ButtonDanger)"
]
Props: {
size: enum"sm|md|lg" (required),
disabled: boolean (optional),
loading: boolean (optional, shows spinner)
}
Slot: label (text only, no nested elements)
Component: DataTable
Limitations: "Max 5 columns visible; use column selector for 6+"
Required props: ["rows", "columns", "onSort"]
Gotchas: "Column.accessor must match row key exactly"
AI-READINESS CHECKLIST
• Slot naming is explicit and unambiguous
• Boolean props never default to confusing values
• Error states documented (e.g., TextInput with error-message prop)
• Nesting rules clear (modals must be portaled, never nested in overflow:hidden)
• CSS class naming avoids AI confusion (use bem.is-active not .active)
AUDIT REPORT
Components ready for agent use: 24 of 31
Components needing revision: TabBar (no ARIA), Dialog (missing onClose)
Metadata coverage: 94percent
About this skill
Your agent keeps hardcoding hex colors, importing the deprecated Modal, inventing variants that don't exist, and shipping icon-only buttons with no label. Writing more guidelines doesn't help, because agents skim prose and ignore it. This skill moves your design system's rules into the places agents actually read and can't skip: type definitions, lint errors, and a compact component manifest.
What it does
- Audits components for agent-hostile patterns, including
stringprops, near-duplicate components and variants, and accessibility rules nothing enforces, ranked P0-P2 - Rewrites prop types as literal and discriminated unions so invalid usage fails typecheck (for example, icon-only buttons must have
aria-label) - Generates per-component manifest entries with use-when, don't-use-when plus the alternative, aliases, composition limits, a11y requirements, and status
- Writes token rules and lint configs that block raw hex, px, and primitive tokens, with error messages that tell the agent the fix
- Builds a short agent index (AGENTS.md / CLAUDE.md / llms.txt) that points to details instead of dumping docs into context
- Designs a before/after agent eval: task prompts plus a violation tally by anti-pattern ID
What you get
A findings table that names the enforcement layer for every fix, plus ready-to-paste type diffs, manifest entries, lint rules, and agent index lines for the components you share.
Best for
Design engineers and frontend platform teams whose component library is now consumed by Claude Code, Cursor, or other coding agents, and who are tired of cleaning up off-system UI.
SKILL.md preview
---
name: agent-ready-design-system
description: Audits, scaffolds, or extends a component library so AI coding agents pick the right component, use only valid props and tokens, and compose correctly. It does this by encoding usage rules as types, lint rules, and a generated component manifest instead of prose. Use when the user says "make our design system AI-friendly", "audit our components for agent use", "write an AGENTS.md for our UI library", "Claude keeps hardcoding hex colors instead of tokens", "Cursor keeps using the deprecated Modal", "the agent invents props that don't exist", "generate component metadata for an MCP server", "our AI-generated UI never matches the design system".
… (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.