feat(docs): add SKILL.md for agent integration of scaffold-ui

[technophile-04]

Summary

Lands the SKILL.md that the discoverability infra in #104 was already designed to pick up. With this in, https://ui.scaffoldeth.io/SKILL.md becomes the agent-facing integration guide and /.well-known/agent-skills/index.json goes from { "skills": [] } to a single-entry index pointing at it.

The SKILL.md is deliberately scoped to what the docs don't shout about loud enough — not a re-documentation of every prop and hook (those already live in llms-full.txt). It captures the integration gotchas that bite agents in practice:

• Peer-dep ordering between @scaffold-ui/components and @scaffold-ui/hooks
• The styles.css import as a silent failure mode
• Provider wrapping order (WagmiProvider → QueryClientProvider → optional RainbowKitProvider)
• ssr: true for Next.js App Router
• The chain defaulting rule (default to first chain in wagmi config, fallback mainnet) — this is the one that catches agents most often, since they reflexively pass chain={mainnet} everywhere
• style prop memoization
• When to opt into @scaffold-ui/debug-contracts and when to skip it

The first line of the body redirects agents to llms-full.txt for full API docs, so the SKILL stays focused and small (~110 lines body, well under Anthropic's 500-line guidance).

Description field

Optimised for triggering accuracy following Anthropic's skill-authoring best practices:

• Third person, "use when" pattern
• Lists every package name and hook name explicitly so keyword matches work
• Includes a deliberate "even if they don't explicitly ask to install" cue, since Claude tends to undertrigger skills
• ~860 chars, under the 1024 limit

Files changed

• docs/public/SKILL.md (new, 117 lines including frontmatter)
• vercel.json (+1/-1) — adds </SKILL.md>; rel="alternate"; type="text/markdown" to the Link header so agents discover it on the same HEAD request as llms.txt and the skills index

Test plan

• pnpm build from docs/ — confirm docs/dist/SKILL.md exists and docs/dist/.well-known/agent-skills/index.json shows 1 skill entry with a valid sha256 digest
• After deploy: curl -s https://ui.scaffoldeth.io/SKILL.md | head -5 returns the frontmatter
• After deploy: curl -s https://ui.scaffoldeth.io/.well-known/agent-skills/index.json | jq '.skills | length' returns 1
• After deploy: curl -sI https://ui.scaffoldeth.io/ | grep -i ^link shows the new SKILL.md entry alongside the existing four
• Independent digest check: shasum -a 256 <(curl -s https://ui.scaffoldeth.io/SKILL.md) should match the digest in the index
• Vibe-test: hand the URL to a fresh Claude instance and ask it to integrate scaffold-ui into a Next.js app — see if it follows the gotchas

Why this is a separate PR from #104

Kept the discoverability infra purely structural so reviewers could verify the scripts and headers in isolation. This PR is the content that flows through that infra. They could have shipped together but stacking made the diffs cleaner to review.

Out of scope (future)

• A navigable Vocs page version of the SKILL (currently it's only the static /SKILL.md); could add /build-with-ai/skill later if humans want to read it nicely in the docs UI
• Sub-skills for specific patterns (e.g. "scaffold-ui + RainbowKit", "scaffold-ui + Privy"); the current single skill covers the integration surface

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
scaffold-ui-docs	Ready	Preview, Comment	May 6, 2026 9:53am

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
scaffold-ui-example	Skipped		May 6, 2026 9:53am

[rin-st]

Working great!

Test plan checkpoints: ✅

Vibe test:

Asked to add AddressInput and EtherInput to the main page of the pure next.js app. Everything was installed right, but EtherInput wasn't working first because default http() transports with eth.merkle.io was failing. So EtherInput was disabled. I asked claude just like "EtherInput is disabled, fix it" and then it found the bug and fixed it. After that I asked to add debug page, and it added the page for mainnet WETH. Not sure why WETH but it works as expected

[technophile-04]

Merging this! thanks @rin-st for the review