One portable Skill for Claude Code, Codex, Cursor and Lovable, plus the two CLI commands that install it and let an agent inspect a project before it writes any UI code.
Proper UI ships one authored Skill — skills/properui/SKILL.md in the repo — that works across Claude Code, Codex, Cursor and Lovable. It encodes the same workflow every integration page already documents by hand: inspect the project, search the registry before writing markup, prefer a full-page example for a whole screen, keep semantic tokens and accessibility intact, verify before reporting done. Two CLI commands make that Skill installable and the project it targets inspectable.
properui agent init
Installs the Skill for one or more AI coding tools. Run it once per project, per tool:
npx @properui/cli@latest agent init --client claude
npx @properui/cli@latest agent init --client codex
npx @properui/cli@latest agent init --client cursor
npx @properui/cli@latest agent init --client lovable
Or install for everything at once — this is also the default when --client is omitted:
npx @properui/cli@latest agent init --client all
What each client gets
| Client | Files written | Notes |
|---|---|---|
| Claude Code | .claude/skills/properui/SKILL.md + a short pointer appended to CLAUDE.md (created if missing) | Claude Code loads project skills from .claude/skills/ automatically — no further setup. |
| Codex | .agents/skills/properui/SKILL.md + a rules block appended to AGENTS.md (created if missing) | Codex discovers skills under .agents/skills/, and reads AGENTS.md for every session regardless. |
| Cursor | .cursor/rules/properui.mdc (alwaysApply: true) | Cursor's rules system only reads .mdc files with frontmatter from .cursor/rules — it does not read SKILL.md — so the same guidance is written as a Cursor rule instead. |
| Lovable | Nothing written locally | Lovable runs in the browser with no access to this checkout. agent init --client lovable prints the Skill's public GitHub URL and what to paste into Lovable's knowledge / custom instructions panel. |
CLAUDE.md and AGENTS.md are never overwritten wholesale — the block agent init adds lives between a pair of HTML comment markers, so re-running the command updates that section in place and leaves the rest of the file untouched. Running agent init again after an update to the Skill is always safe.
Command options
| Option | Description |
|---|---|
--client <name> | claude, codex, cursor, lovable, or all (default). |
--overwrite | Replace the installed SKILL.md / rule file even if it already exists and differs — useful after editing the Skill upstream. Does not affect the CLAUDE.md/AGENTS.md marker block, which is always kept in sync. |
-y, --yes | Accept every default; never prompt. |
--cwd <path> | Run against a directory other than the current one. |
properui info --json
Reports everything an agent needs before touching UI code: detected framework, TypeScript, Tailwind version, package manager, the components.json aliases and theme CSS path (when the project has been through init), which registry entries are already installed, and the installed versions of @properui/ui and the properui CLI itself.
npx @properui/cli@latest info --json
{
"framework": "next-app",
"typescript": true,
"tailwindVersion": 4,
"packageManager": "pnpm",
"config": {
"present": true,
"aliases": { "components": "@/components", "utils": "@/utils", "ui": "@/components/base", "hooks": "@/hooks" },
"theme": "src/styles/theme.css",
"css": "src/app/globals.css",
"registry": "https://properui.dev/r"
},
"packages": {
"@properui/ui": { "installed": null, "declared": null },
"properui": { "installed": "0.1.0", "declared": null }
},
"installed": [{ "name": "badges", "layer": "base", "type": "component" }]
}
installed is computed the same way properui diff finds local components: every non-example entry in the registry index is checked against the project's files, and anything present is reported. Without --json, the same data prints as a short human-readable report instead — useful for a quick check from your own terminal, not just from an agent.
Command options
| Option | Description |
|---|---|
--json | Print machine-readable JSON instead of the formatted report. |
--registry <source> | Registry directory or base URL for this run (see docs/cli.md). |
--cwd <path> | Run against a directory other than the current one. |
The Skill itself tells an agent to run this before deciding anything — whether to run init first, which alias to use in hand-written imports, and which components are already installed and shouldn't be re-added.