AGENTS.md

Repo-root contract for agents: imports, events, appearance, and the MCP loop.

What it is

AGENTS.md at the repo root tells coding agents how to use Velkin: subpath imports, onVu* / e.detail, appearance rules, and “call MCP before inventing props.” It does not connect MCP — do that on MCP servers.

AI docs: MCP · AGENTS.md · Cursor skill · llms.txt

Get the file

# Preferred: scaffold into the app
npx velkin-mcp init --client cursor

# Or copy the live contract
curl -o AGENTS.md https://velkinui.com/AGENTS.md

Live file: https://velkinui.com/AGENTS.md. Same template ships in @velkin/mcp and create-velkin-app.

Must include

Subpath imports only — never @velkin/react root barrels
React: onVuChange + e.detail (not e.target.value)
radius="full" (no pill); color vs tone on separate axes
Before UI: MCP get_velkin_component_docs → validate_component_usage → velkin_lint
Link https://mcp.velkinui.com/mcp and Events / Appearance

Prefer the live /AGENTS.md over maintaining a long copy-paste in this guide — keep your repo file in sync with that contract.

Per IDE

Cursor — loads root AGENTS.md automatically; pair with MCP + skill
VS Code — commit AGENTS.md; MCP in .vscode/mcp.json
Claude — commit AGENTS.md; MCP in .mcp.json
CI / headless — commit the file; pass the MCP URL when the runner supports tools

Next steps