Agent skills

Actionable playbooks and skills that tell AI agents across Cursor, Antigravity, Claude, and more when and how to call Velkin MCP tools.

Universal agent playbooks

Agent skills and playbooks give autonomous coding assistants (such as Cursor, Antigravity, Claude Code, Windsurf, Cline, and Copilot) proactive domain instructions on when and how to query the Model Context Protocol (MCP) server, enforce design system invariants, and validate component code before saving.

AI docs: MCP · AGENTS.md · Agent skills · llms.txt

Where skills live across environments

Different AI environments discover project playbooks in designated project paths:

Cursor — .cursor/skills/velkin/SKILL.md (auto-loaded when writing Velkin code or triggered by rules)
Antigravity — .agents/skills/velkin/SKILL.md (Google DeepMind agent runtime with native YAML frontmatter skill discovery)
Claude Code & Claude Desktop — referenced directly in project AGENTS.md or CLAUDE.md instructions
Windsurf — .windsurfrules or workspace rules referencing AGENTS.md and the Velkin playbook
VS Code (Cline / Roo Code / GitHub Copilot) — .cline/, .roomodes, or workspace instructions referencing AGENTS.md

Install in one command

Use npx velkin-mcp init to scaffold configuration files, AGENTS.md, and agent skills tailored to your client or across all environments:

# Scaffold for all environments at once:
npx velkin-mcp init --client all

# Or target your specific environment:
npx velkin-mcp init --client cursor       # → .cursor/mcp.json + .cursor/skills/velkin/SKILL.md
npx velkin-mcp init --client antigravity  # → .agents/mcp_config.json + .agents/skills/velkin/SKILL.md
npx velkin-mcp init --client vscode       # → .vscode/mcp.json + AGENTS.md
npx velkin-mcp init --client claude       # → .mcp.json + AGENTS.md
npx velkin-mcp init --client windsurf     # → .windsurf/mcp.json + AGENTS.md
npx velkin-mcp init --client cline        # → .cline/mcp.json + AGENTS.md

New projects created with create-velkin-app come pre-configured with multi-agent readiness out of the box.

Standard playbook specification

The standard Velkin skill includes YAML metadata for runtime discovery followed by the operational decision tree:

---
name: velkin
description: Build UI with Velkin design system components. Use when creating or editing Velkin components, props, events, slots, and design tokens via MCP.
---

# Skill: Build with Velkin

Use this skill whenever generating or editing UI that uses `@velkin/*` or `vu-*` tags across any AI editor or agent (Cursor, Antigravity, Claude, VS Code, Windsurf, Cline).

## Hard rules
1. Never invent props, events, slots, or CSS tokens. Call MCP first.
2. Prefer `get_velkin_component_docs` with `compact: true`.
3. Imports are subpaths only (`@velkin/react/button`). Barrels are forbidden.
4. React events are `onVu*` and values live on `e.detail`. Never `e.target.value`.
5. Wrap the app in `VuThemeProvider` with `persist`.
6. Icons: `VuIcon` with `"ion:…"` names from `search_icons`. Do not inline SVG.
7. Pro components (`tier === "pro"`) use `@velkin/react-pro` and `// @velkin-pro`.
8. Appearance: `radius="full"` (not `pill`); `size` is `sm` | `md` | `lg`.

## Optimal full workflow
suggest_component
  → get_component_dependencies
  → get_velkin_component_docs (compact: true)
  → validate_component_usage
  → get_component_usage / get_recipes
  → velkin_lint
  → get_a11y_guide

Next steps

MCP servers — connect live tools
AGENTS.md — universal agent contract
llms.txt — plain-text documentation index