Add doc validation skills for ui-extensions

[rennyG]

Closes https://github.com/shop/issues-learn/issues/1073

Supercedes #4084

Adds Claude Code skills for validating documentation updates in this repo. Used by the docs team.

Skills added

• ui-extensions:router — entry point, routes to correct skills by page type
• ui-extensions:style-lint — mechanical text checks (contractions, punctuation, formatting, capitalization, file references)
• ui-extensions:examples — example quality checks covering only what the automated script can't (uniqueness, description pattern, usefulness) + live schema validation via MCP
• ui-extensions:components — component description format, best practices, limitations + live schema validation via MCP
• ui-extensions:apis — API descriptions, JSDoc authoring quality, supported tags, shared component docs
• ui-extensions:type-definitions — JSDoc quality, slots, events, architecture patterns
• ui-extensions:cross-surface — consistency across checkout and customer account
• ui-extensions:link-validation — link verification via MCP tools (run separately)
• ui-extensions:build-verification — docs generation and JSON verification

Design

• Scoped to checkout and customer account surfaces only
• All skills invoked manually, not auto-triggered
• Output format: Validation Report (what's good / needs attention / can't verify / must fix / recommendation)
• style-lint and examples are split so Claude doesn't context-switch between mechanical scanning and subjective judgment
• Example validation defers to the existing automated script for syntax/rendering checks
• Verification protocol: Skills cross-reference every description against the actual .d.ts type definitions — if a description mentions a prop, method, or behavior that doesn't exist in the type, it's flagged as a must-fix. Claims that can't be verified are flagged explicitly, with a recommendation to confirm or remove.
• Live schema validation: Examples and components skills use validate_component_codeblocks MCP tool to verify HTML examples against the published Shopify component schema

Testing — how to review these skills

You'll need Claude Code with this branch checked out. The skills live in .claude/skills/ and are available automatically once you open a terminal in this repo.

To try a skill, open a Claude Code session in this repo and ask it to validate a file. Name the skill explicitly in your prompt:

Use ui-extensions:style-lint to validate docs/surfaces/checkout/reference/components/button.doc.ts

Use ui-extensions:components and ui-extensions:type-definitions to validate docs/surfaces/checkout/reference/components/modal.doc.ts

Use ui-extensions:router to figure out which skills I need for this file: docs/surfaces/customer-account/reference/apis/buyer-identity.doc.ts

Not sure where to start? Pick any component or API .doc.ts file that's been updated recently and run ui-extensions:style-lint on it. The output format is a short Validation Report — it should feel useful and specific, not a wall of checkboxes.

Link validation (uses MCP tools, slower): invoke ui-extensions:link-validation separately and pass it a file with documentation links.

What to check as a reviewer:

• Does the output feel like a useful code review, or is it too mechanical/noisy?
• Are the "Must fix" items actually blockers, or are they over-flagged?
• Are there real issues the skill misses that you'd expect it to catch?

Not in scope — follow-up skills for shopify-dev repo

The following skills were intentionally left out because the content they validate lives in shopify-dev, not this repo. They'll be added in a separate PR against that repo:

1. Example rendering validation — verifies examples render without errors in the shopify-dev preview (this repo only generates JSON; rendering happens in shopify-dev)
2. .mdx component prop validation — validates props on components like <Chip>, <ExtensionSupports>, <ExampleSwitcher>, <AccordionLabel>, <ExpandableImage> used in shopify-dev .mdx pages
3. Targets index page validation — frontmatter, resource section structure, accordion structure, alphabetical order, {API_VERSION} placeholders, no duplicate accordion IDs
4. Targets page validation — frontmatter, page structure, target group sections, <ExtensionSupports>, <ExampleSwitcher>, example quality, best practices/limitations
5. Target identifier matching — verifies target identifiers in .mdx pages match the official target API

[mcvinci]

Thanks for putting this together, @rennyG! I left one quick suggestion and one consideration regarding the mentions of doc.ts files, which are going away in short order.

[rennyG]

For all of skills where it's relevant to do so, we should validate against the live schema. We should also ensure the LLM is indicating what it can't verify, what should change, and if it doesn't know what should change, it recommends we remove the claim