README + DESIGN.md: entity block, prompt-library backlinks, demo, disambiguator

GEO/AEO discoverability pass on the skill README (SEO-023):
- Add a structured "What is Superdesign?" entity block for clean LLM extraction
  (what / who for / how it differs vs style-preset skills / two ways in).
- Add prompt-library hyperlinks (superdesign.dev/library) in the Inspiration
  section and Links — a backlink to our #1 traffic surface (was CLI-only).
- Add a demo video embed (clickable thumbnail) at the top.
- Add a one-line disambiguator vs the legacy superdesigndev/superdesign IDE
  extension (the two same-org repos conflate in search).
- New DESIGN.md documenting the design-system-file convention the skill uses.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MT9K241p4XsXdSeHmQUVsP

DESIGN.md

@@ -0,0 +1,42 @@
+# DESIGN.md — a design system file for AI coding agents
+
+Coding agents write great code and mediocre interfaces. One reason: they have no persistent sense of
+*how this product is supposed to look*. `AGENTS.md` and `CLAUDE.md` tell an agent how your code
+works. **A design system file does the same for how your product looks** — colors, typography,
+spacing, motion, component patterns, and the product context behind them — so every UI the agent
+ships is consistent with the last one instead of reinventing a generic look each time.
+
+This is the design equivalent of `llms.txt` or `AGENTS.md`: a single, human-readable file an agent
+reads before it designs.
+
+## What goes in it
+
+A good design system file is **implementable without the codebase** — an agent (or a person) should
+be able to build on-brand UI from it alone:
+
+- **Product context** — what's being built, who it's for, the core value, key user journeys.
+- **Design tokens** — colors, typography, spacing, radius, shadows.
+- **Motion** — animation and interaction patterns.
+- **Components** — the real patterns your product uses, with usage notes.
+
+## How Superdesign uses it
+
+The [Superdesign skill](./README.md) reads and writes this file at
+`.superdesign/design-system.md`. It can:
+
+- **Extract** one from your existing codebase (tokens, components, patterns), or
+- **Create** a new one from references when you're improving current UI.
+
+If the file is missing, the skill runs **Design System Setup** first, then designs against it — so
+every draft on the canvas inherits the same system. See the README for the full workflow.
+
+## Why it matters
+
+A design system file is the difference between an agent that produces *default-shadcn-everything* and
+one that produces UI that looks considered. Capture it once; every design after that is consistent,
+on-brand, and faster to ship.
+
+---
+
+Part of [Superdesign](https://superdesign.dev), the AI product design agent. Browse the
+[prompt library](https://superdesign.dev/library) for ready-made style and component direction.

README.md

@@ -6,6 +6,23 @@ Install it once and your agent (Claude Code, Cursor, Codex, and 70+ others) can
 
 > Powered by [superdesign.dev](https://superdesign.dev), the AI product design agent.
 
+[![Superdesign skill demo](https://i.ytimg.com/vi/AZYJWyWZ6pQ/maxresdefault.jpg)](https://youtu.be/AZYJWyWZ6pQ)
+
+*▶ Watch the skill in action.*
+
+---
+
+## What is Superdesign?
+
+**Superdesign is an AI product design agent.** It gives coding agents (Claude Code, Cursor, Codex, and 70+ others) real design judgment, so the UI they ship looks considered instead of generic.
+
+- **What it does** — finds design direction, sets up a design system from your codebase, and generates + iterates high-quality UI drafts on an infinite canvas, all from your terminal.
+- **Who it's for** — developers, indie hackers, and product/UI designers who want to go from idea to shippable UI fast without leaving their coding agent.
+- **How it's different** — style-preset skills just swap in a theme or a component library. Superdesign designs *into* your existing design system: it reads your code for context, gathers real style references, and produces branchable drafts you refine.
+- **Two ways in** — this skill from any coding agent, or the web app at [superdesign.dev](https://superdesign.dev).
+
+> **Not the legacy IDE extension.** The archived open-source `superdesigndev/superdesign` VS Code extension is an older, separate project. This skill and [superdesign.dev](https://superdesign.dev) are the current, maintained product.
+
 ---
 
 ## Install
@@ -51,7 +68,7 @@ The skill handles the rest: it reads your code for context, gathers real style r
 
 ### A) Inspiration & Style Tools (generic, always available)
 
-Use these to discover style direction, references, and brand context:
+Use these to discover style direction, references, and brand context. Browse the full [prompt library](https://superdesign.dev/library) in the web app, or query it from the CLI:
 
 - **Search prompt library** (style/components/pages)
 
@@ -279,6 +296,8 @@ superdesign create-design-draft --project-id <id> --title "X" -p "..." --json
 ## Links
 
 - Web app: [superdesign.dev](https://superdesign.dev)
+- Prompt library: [superdesign.dev/library](https://superdesign.dev/library)
+- Design system convention: [DESIGN.md](./DESIGN.md)
 - Skill install for 70+ agents: [vercel-labs/skills](https://github.com/vercel-labs/skills)
 
 ## License