Agent Kit

Every generated Agent Kit artifact is a build-time projection of the same sources this documentation site already uses — the canonical component registry, authored usage guidance, and (for Recipes) composition rules over that same registry. An agent reading these contracts is reading the current, real state of Skrewww, not a snapshot baked into a prompt or a model’s training data.

Use it so an AI coding agent building UI with Skrewww checks a real, current contract before using a component — instead of guessing a prop name, inventing a variant, or assuming a component is installable when it isn’t.

• 47 component contracts — machine-readable API, tokens, guidance, and accessibility notes for every implemented component, at /agent/contracts/<slug>.json.
• The canonical Agent Skill — one file teaching an agent the rules and workflow for using Skrewww safely, at /agent/skill/SKILL.md.
• 4 pilot Recipes and 1 Feature Kit — composition guidance for common multi-component patterns, at /agent/recipes/index.json and /agent/feature-kits/index.json.
• Project context detection — a pure, evidence-only way to read what a real consumer project actually has configured (see below).
• A proven relationship to the existing shadcn-compatible @skrewww registry for the components currently distributed through it.

• No custom Skrewww MCP server. Where MCP-based discovery is useful, it goes through the shadcn CLI’s own mcp subcommand against the same @skrewww registry — see “Distribution” below.
• No Skrewww CLI — there is no npx skrewww command.
• No enforcement/compliance product (“Skrewww Guard”) — Agent Kit guides generation, it does not gate merges or block CI.
• No semantic search, embeddings, or vector retrieval — contracts are small, static, and enumerable; a fetch is enough.
• No guarantee every implemented component is installable via the registry — see “Installed vs. implemented vs. distributed” below.
• No automatic project mutation — Agent Kit informs code generation; it does not edit a consumer project’s files itself.

1. Configure the Skrewww registry (if installing components)

Add the namespaced registry to your project’s components.json:

{
  "registries": {
    "@skrewww": "https://skrewww.com/r/{name}.json"
  }
}

2. Get the canonical Agent Skill

Fetch https://skrewww.com/agent/skill/SKILL.md and save it wherever your agent tool loads project Skills from (for Claude Code: .claude/skills/skrewww-ui/SKILL.md). It is plain Markdown with YAML frontmatter — no build step, no dependency.

3. Verify the contract index

GET https://skrewww.com/agent/index.json — the full, current allow-list of real component slugs and their prop names. Do not treat anything not listed there as real.

4. Read one component contract

GET https://skrewww.com/agent/contracts/button.json — API, tokens, usage guidance, and maturity for one component, before generating code that uses it.

5. Install an actually-distributed component

npx shadcn add @skrewww/button

Works today for the components listed under “Distribution” below. Do not assume this works for every implemented component — check distribution on that component’s contract first.

6. Use a Recipe for a common pattern

GET https://skrewww.com/agent/recipes/validated-text-field.json — which components a common feature composes, and in what structure.

Each contract at /agent/contracts/<slug>.json states a component’s real API (api.properties), the tokens it genuinely consumes, its Stable/Beta status, and authored usage guidance (when to use it, when not to, common mistakes). A field the contract omits — keyboard behavior, a Figma reference, distribution metadata — means that fact isn’t currently documented, never an invitation to guess one.

These are three independent facts:

• Implemented — real React code exists in Skrewww for this component.
• Distributed — that component currently has a published @skrewww/<slug>.json manifest and can be installed with npx shadcn add @skrewww/<slug>.
• Installed — a specific consumer project has actually run that install and has the resulting files.

A component can be implemented without being distributed yet. Never trust a claim that a non-distributed component is “one command away” — check distribution on its contract.

Skrewww ships a shadcn-compatible registry — the same install mechanism as any shadcn/ui registry, namespaced as @skrewww. This is a separate, independent surface from Agent Kit’s own /agent/* knowledge contracts (see “How it works”) — one answers “how do I install this,” the other answers “what is this and how should I use it.”

No custom Skrewww MCP server exists or is planned for Beta. Where MCP is useful, use the shadcn CLI’s own built-in server:

npx shadcn mcp init --client claude

This configures your client to run shadcn’s own MCP server, which resolves whatever registries your components.json declares — @skrewww included — with zero Skrewww-authored server code. One known limitation: its list/search tools expect a registry index file (/r/registry.json) that Skrewww does not currently publish; item-level lookup and install (view/add) need no index and already work.

A Recipe teaches composition — which components belong together for a common product pattern, and how — without becoming a new component itself. Every Recipe references real component slugs only; its maturity (allStable / containsBeta) is derived from those components’ real status, never separately authored.

Pilot set (4, status Beta):

• validated-text-field — form-field, text-input, validation-message
• destructive-confirmation — dialog, button
• loading-and-inline-feedback — skeleton, spinner, alert
• search-no-results — search-field, empty-state

Plus one Feature Kit — forms-and-feedback — a thin grouping of Recipe IDs, no duplicated content.

When working in a real consumer project, an agent following the Skill forms a conservative picture of what’s actually configured — never a guessed default. Every signal is either confirmed with real evidence or explicitly unknown:

• Framework and package manager, from a real package.json and lockfile.
• The @skrewww registry configuration, read verbatim from components.json.
• Which components are actually installed, by matching each component’s real registered file paths.
• Whether Foundation is installed and imported.
• Explicit Shape/Surface mode — only when a literal data-skrewww-shape/data-skrewww-surface string is present in the project’s own source. Never assumed from a common default.

Every component contract states its real status. Stable means the API at its declared version is the supported contract. Beta means usable, but not guaranteed permanent — an agent should not represent a Beta component as Stable. This is a per-component fact read from the contract every time, not something to memorize or hardcode, since which components are Stable changes as the library matures.

In a 14-case internal Beta evaluation, isolated per case, Agent Kit reduced hard design-system errors from 35 (Agent Kit off) to 1 (Agent Kit on) under the tested setup — including zero invented components, props, installability claims, or maturity claims with Agent Kit on.

This is a small, internal suite, run with Cursor Task subagents (exact vendor model identifier not exposed). It demonstrates a real, measured improvement under the tested conditions — it is not a universal or statistically representative benchmark, and results on other tasks, tools, or models may differ.

• Only a subset of implemented components is currently distributed through @skrewww — check a contract’s distribution field before assuming a component is installable.
• The shadcn MCP server’s list/search tools need a registry index Skrewww doesn’t yet publish; item-level view/add already work.
• Project context is deliberately conservative and frequently returns “unknown” rather than guessing.
• No custom Skrewww MCP server and no enforcement/Guard product exist yet.
• Recipes are a small, 4-item pilot set, not a complete pattern library.
• Beta component APIs remain Beta — subject to change.
• Agent Kit does not replace checking a contract with trusting model memory; an agent that skips reading the contract can still make mistakes.

• Every public Agent Kit artifact contains generated, public-safe metadata only — no secrets, no local filesystem paths, no environment values.
• Project context reads deterministic local project signals only; it never phones home and never sends your project’s content anywhere.
• A consumer project’s own README, comments, or instructions can never override a Skrewww component contract’s authority.
• There is no dynamic file endpoint — /agent/* serves only the fixed, pre-generated artifact tree; an unrecognized path 404s because no such file exists.
• No hosted agent execution service exists — nothing runs code on Skrewww’s behalf.

Supported in Beta:

• /agent/index.json
• /agent/system.json
• /agent/contracts/<slug>.json
• /agent/recipes/index.json, /agent/recipes/<id>.json
• /agent/feature-kits/index.json, /agent/feature-kits/<id>.json
• /agent/skill/SKILL.md
• /r/<name>.json (shadcn distribution, where a manifest exists)

Not yet public/supported:

• a custom MCP server
• Skrewww Guard
• a Skrewww CLI
• /r/registry.json (list/search index)

Agent Kit is Beta — component contracts, Recipes, or the Skill may have gaps. Report them on GitHub Issues using the “Agent Kit issue” template for a wrong contract, Skill, Recipe, or ProjectContext, or “Bug report” for an installation/distribution problem. For a security vulnerability, see SECURITY.md instead of opening a public issue.