/ai-component-description

name: ai-component-description
description: "Write a six-section prose description (purpose, props, anti-patterns, composition, accessibility, examples) for a Figma component's description field so LLMs read it via MCP. Triggers: describe this component for AI, Figma MCP description. JSON metadata files: use metadata-schema-generator."
allowed-tools: Read, Write, Grep, Glob, Bash(cat:*), Bash(find:*), Bash(head:*), Bash(ls:*), Bash(sort:*), Bash(tail:*), Bash(wc:*)
references:
  - ../../knowledge-notes/ai-readiness.md
  - ../../knowledge-notes/component-bestiary-reference.md
  - ../../knowledge-notes/mcp-setup-guide.md
  - ../../knowledge-notes/output-discipline.md

AI component description

A skill for generating structured component descriptions optimised for consumption by LLMs via Figma's MCP server. Output is a six-section description that gives an AI agent the information it needs to understand, compose, and generate from a component accurately — without relying on implicit knowledge, visual inference, or team context.

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

Most component descriptions are written for human designers discovering the component for the first time: "use this to show important information", "works great in cards". An LLM reading a description needs to know what the component is, what it takes, what it prohibits, how it relates to other components, and what failure modes look like. Human-readable descriptions skip most of this.

The six-section format came from watching AI agents misuse components that had perfectly fine human documentation. Each section addresses a specific class of LLM error.

---

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:

• `integrations.figma`, `integrations.storybook`, `integrations.github` and `integrations.documentation` — which sources Step 0 can read automatically

Step 0: Check data sources and existing description

Use every source that is available:

1. **`.ai/metadata/<Component>.metadata.json`** (from `metadata-schema-generator`), if present: the props and the accessibility contract, each with a provenance marker. This is the extraction; the description renders from it and carries the markers through. Don't re-derive what it holds. 2. **Figma** (MCP connected, or `integrations.figma` with a `file_key`): the component node, its variants, layer structure (for composition) and existing description. The official Figma MCP reads the current selection or a node URL, so if it returns nothing, ask the user to select the component or paste the node link. 3. **Storybook** (`integrations.storybook`): prop types, defaults and arg types from the story metadata. 4. **Source** (repo access or `integrations.github`): prop definitions from TypeScript interfaces or PropTypes, the rendered element, ARIA attributes, key handlers and focus calls. Where Figma, Storybook and source disagree on the API, say so rather than picking one silently. 5. **None of the above:** stop and ask for one. A description written from the user's memory of the component will be wrong in the places that matter (defaults, ARIA, keys), and an agent will trust it.

If a source is configured but fails (connection error, invalid node, nothing selected), note the error and carry on with what you have. Do not retry in a loop.

**Provenance rule.** Every prop, default, ARIA role, key binding and focus behaviour in the description comes from source, Storybook, Figma or the user. Anything you can't trace is left out or marked "unverified" in the text, the same way inferred anti-patterns are marked "anticipated" (Section 3). Never fill the Props or Accessibility sections from what components of this kind usually do. See "Every figure and fact needs a source" in the output-discipline knowledge note.

**Existing description.** If the description field has content (anything other than null, an empty string or whitespace), quote it to the user before doing anything else: "This component already has a description: [text]. Want me to rewrite it in the six-section format, improve what's there, or start fresh?" If it already follows the six-section format, offer a completeness review instead. Never claim there is no description when there is one, and never silently discard it. Treat it as a starting point, not a source of truth: it often holds institutional knowledge worth keeping, but being there doesn't make it accurate.

---

Step 1: Gather component information

Confirm the following from the Step 0 sources, and ask the user only for what they didn't supply:

• Component name
• Component category (e.g. navigation, feedback, form, layout, data display)
• Available props/variants and their accepted values
• Default state
• Any composition relationships (what it contains, what it can be placed inside)
• Accessibility requirements already defined for the component
• Known misuse patterns observed in production (if any)

Step 2: Write the six-section description

Write each section in plain prose. No bullet markers or nested lists inside the description itself: AI agents parse prose better than nested lists in this context, and Figma's plain-text field doesn't render them. Where a section holds parallel items (props, anti-patterns), put each on its ow