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 · Agent skills · llms.txt

Get the file

# Preferred: scaffold into the app for your client (or --client all)
npx velkin-mcp init --client all

# Or copy the live universal 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.

Universal support across environments

Cursor — reads root AGENTS.md automatically; pair with MCP + agent skill (.cursor/skills/velkin/SKILL.md)
Antigravity — reads AGENTS.md and auto-discovers .agents/skills/velkin/SKILL.md with MCP in .agents/mcp_config.json
VS Code (GitHub Copilot, Cline, Roo Code) — commit AGENTS.md to repo root; MCP in .vscode/mcp.json or cline_mcp_settings.json
Claude (Code CLI & Desktop) — commit AGENTS.md; MCP configured in project .mcp.json or global developer settings
Windsurf — commit AGENTS.md; MCP in .windsurf/mcp.json
Gemini CLI & Codex CLI — commit AGENTS.md; connects via gemini.config.json or .codex/mcp.json
CI / headless agents — commit AGENTS.md; pass the MCP remote URL https://mcp.velkinui.com/mcp when the runner supports tools

Next steps

MCP servers — connect tools
Agent skills — playbooks across environments
Open live /AGENTS.md

Get the file

# Preferred: scaffold into the app for your client (or --client all)
npx velkin-mcp init --client all

# Or copy the live universal 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.

Universal support across environments

Cursor — reads root AGENTS.md automatically; pair with MCP + agent skill (.cursor/skills/velkin/SKILL.md)
Antigravity — reads AGENTS.md and auto-discovers .agents/skills/velkin/SKILL.md with MCP in .agents/mcp_config.json
VS Code (GitHub Copilot, Cline, Roo Code) — commit AGENTS.md to repo root; MCP in .vscode/mcp.json or cline_mcp_settings.json
Claude (Code CLI & Desktop) — commit AGENTS.md; MCP configured in project .mcp.json or global developer settings
Windsurf — commit AGENTS.md; MCP in .windsurf/mcp.json
Gemini CLI & Codex CLI — commit AGENTS.md; connects via gemini.config.json or .codex/mcp.json
CI / headless agents — commit AGENTS.md; pass the MCP remote URL https://mcp.velkinui.com/mcp when the runner supports tools