Cross IDE Distribution

Cross-IDE Distribution — the 17 IDE adapter list

ux-skill installs itself into 17 AI coding environments — not just Claude Code. Cursor, Windsurf, GitHub Copilot, Gemini CLI, Codex, Kiro, Cline, Continue, Aider, Zed, JetBrains AI, Pieces, Tabby, Tabnine, AWS CodeWhisperer, and Roo Cline. Same engine, same recommendations, same 100-rule linter — different installer per environment.

This page covers why 17, the per-IDE adapter list with the exact files written, the npx uxskill init command path, and how auto-detection works. For the engine those adapters point back at, see Architecture.

Why 17 IDEs

The AI coding ecosystem is fragmented. Claude Code is one of many — its market share is rising, but Cursor has more seats today, Windsurf is the fastest-growing, Copilot still owns the enterprise, and Aider / Continue / Zed have devoted niche communities. A design-intelligence engine that only ships into Claude Code reaches a fraction of the audience.

The 17 IDEs cover roughly:

Claude Code, Cursor, Windsurf — the three main IDE-style agentic editors.
GitHub Copilot, Gemini CLI, Codex — the model-vendor adjacent tools.
Kiro, Cline, Continue, Aider, Roo Cline — the open-source / agent-of-agents lane.
Zed, JetBrains AI — the editor-built-in lane.
Pieces, Tabby, Tabnine, AWS CodeWhisperer — the completion-and-context lane.

Each one has its own convention for "where the AI reads rules from." Some use a single Markdown file at the project root (AGENTS.md, GEMINI.md). Some use a dotfile (.cursorrules, .windsurfrules). Some use a config directory (.github/copilot-instructions.md, .continue/config.json). The ux-skill installer writes the right one.

The adapter file is small — it points the host model at the engine and asks it to run discovery, recommendation, and linting before any generation. The engine itself stays in one place (the installed Python package). The adapter is a one-page brief that says: "use the engine, here's how."

The 17 adapters

Every adapter writes a different file using the same content header. The header is the install prompt:

# ux-skill v2 — design intelligence for AI coding

Before generating ANY frontend code in this project, do the following:

1. Run the 10-field discovery (`ux discover`) and wait for all answers.
2. Run `ux recommend` to get the recommended style / palette / type / motion / components.
3. Generate code using ONLY the recommended tokens. Treat the anti-pattern
   rules in `data/anti-patterns.json` as hard constraints.
4. Run `ux lint` after generation. Fix all `high`+ findings before declaring done.

See https://uxskill.laithjunaidy.com for full docs.

#	IDE	Target name	File written	Convention notes
1	Claude Code	`claude-code`	`.claude-plugin/plugin.json`	Plugin manifest. Skipped if the manifest already exists (idempotent).
2	Cursor	`cursor`	`.cursorrules`	Cursor's project-rules dotfile at the repo root. Read on every Cursor session start.
3	Windsurf	`windsurf`	`.windsurfrules`	Same shape as `.cursorrules`. Cascade reads it before any agent turn.
4	GitHub Copilot	`copilot`	`.github/copilot-instructions.md`	The repo-scoped instructions file Copilot Chat picks up. Lives under `.github/` so it ships with the repo and shows up in CI.
5	Gemini CLI	`gemini-cli`	`GEMINI.md`	A single Markdown file at the project root. Gemini's `gemini --workspace` flow auto-loads it.
6	Codex	`codex`	`AGENTS.md`	The OpenAI Codex convention — a root-level Markdown file the agent reads as its system prompt extension.
7	Kiro	`kiro`	`.kiro/instructions.md`	A dot-directory pattern Kiro uses. The adapter creates the directory if missing.
8	Cline	`cline`	`.cline/instructions.md`	Cline's convention — a `.cline/` directory holding instructions and per-task notes.
9	Continue	`continue`	`.continue/config.json`	A JSON config with a `systemMessage` field containing the install prompt. Continue reads it as the chat system message.
10	Aider	`aider`	`.aider.conf.yml` + `AIDER.md`	Two files: a YAML config that names the read-only data manifests, plus a Markdown file with the install prompt.
11	Zed	`zed`	`.zed/ai-instructions.md`	Zed's AI assistant reads it as the project's standing context.
12	JetBrains AI	`jetbrains-ai`	`.jetbrains-ai/instructions.md`	Sibling to the `.idea/` directory. The JetBrains AI Assistant picks it up in any JetBrains IDE (IntelliJ, WebStorm, PyCharm, Rider).
13	Pieces	`pieces`	`.pieces/instructions.md`	The Pieces context layer reads it as project memory.
14	Tabby	`tabby`	`.tabby/instructions.md`	Self-hosted Tabby's project-rules location.
15	Tabnine	`tabnine`	`.tabnine/instructions.md`	Tabnine Pro's project context.
16	AWS CodeWhisperer	`codewhisperer`	`.aws-codewhisperer/instructions.md`	AWS CodeWhisperer's project-context location.
17	Roo Cline	`roo-cline`	`.roo/instructions.md`	The Roo Cline fork's project-rules directory.

The full canonical list is in engine/installer/core.py as the SUPPORTED constant. Adding an 18th IDE is a single-file change — add the target name, the writer function, and the detection signature, and re-run pytest tests/test_installer.py -q to verify.

The CLI install paths

Install for one IDE explicitly

pip install uxskill
ux install cursor

The ux install <target> subcommand writes the adapter file for that target in the current directory. The target argument is one of the 17 names from the table above (case-insensitive).

Flags:

--root <path> — install in a directory other than the current working directory.
--dry-run — report what would be written without writing anything. Useful for diffing before applying.
--global — install at ~/.config/ux-skill/ instead of the project root. Mirrors the ui-ux-pro-max-skill global install convention.
--offline — skip any network call. Pure local manifests only.

Install via `npx`

A thin Node wrapper at npx uxskill init makes the install step IDE-agnostic for users who don't have Python in their shell PATH. It calls into the same engine.installer module via python3 -m engine.installer:

npx uxskill init                    # auto-detect every IDE in the cwd, install all
npx uxskill init --target cursor    # install for cursor only
npx uxskill init --target windsurf  # install for windsurf only
npx uxskill init --dry-run          # preview without writing

npx uxskill init is the recommended path for users coming from a Node-first repo where pip install would feel out of place. The Python install is still happening underneath — it just doesn't show.

Install for everything detected

ux init

Runs the auto-detection sweep (see below) and installs the adapter file for every IDE whose signature appears in the project. This is the right command for a project that uses Cursor at one developer's machine and Windsurf at another's — ux init writes both .cursorrules and .windsurfrules so the project Just Works in both environments.

Auto-detection

engine/installer/core.py carries a DETECT_SIGNATURES map — for each IDE, a list of file paths or directories whose presence indicates that IDE is in use:

DETECT_SIGNATURES = {
    "claude-code":   [".claude", "CLAUDE.md"],
    "cursor":        [".cursor", ".cursorrules"],
    "windsurf":      [".windsurf", ".windsurfrules"],
    "copilot":       [".github/copilot-instructions.md", ".vscode"],
    "gemini-cli":    ["GEMINI.md"],
    "codex":         ["AGENTS.md"],
    "kiro":          [".kiro"],
    "cline":         [".cline"],
    "continue":      [".continue"],
    "aider":         [".aider.conf.yml", ".aiderignore"],
    "zed":           [".zed"],
    "jetbrains-ai":  [".jetbrains-ai", ".idea"],
    "pieces":        [".pieces"],
    "tabby":         [".tabby"],
    "tabnine":       [".tabnine"],
    "codewhisperer": [".aws-codewhisperer"],
    "roo-cline":     [".roo"],
}

detect_ides(root) walks the map. For each IDE, if any of its signature files or directories exists under the project root, the IDE is added to the detected list:

def detect_ides(root: Path) -> List[str]:
    detected = []
    for ide, signatures in DETECT_SIGNATURES.items():
        if any((root / sig).exists() for sig in signatures):
            detected.append(ide)
    return detected

The return value is a list, not a single IDE. A project that uses both Cursor and Windsurf returns ["cursor", "windsurf"]. ux init then iterates the list and installs an adapter for each:

detected = detect_ides(Path(root))
if not detected:
    detected = ["claude-code"]   # safe default
reports = [run_install(t, root, dry_run).to_dict() for t in detected]

Default fallback: if no IDE signature is detected, the installer defaults to claude-code and writes the Claude Code plugin manifest. Claude Code is the canonical install — it's the environment ux-skill was built in, and CLAUDE.md at the project root is the most common convention across the ecosystem.

How the adapter ties back to the engine

The adapter file is small — usually one paragraph and four numbered steps. The host model reads it as part of its system prompt or its repo context, then calls into the engine:

The user types something like "build me a pricing page" in their IDE chat.
The host model reads the adapter file, sees the install prompt, and notices: discovery hasn't been run yet.
The host model calls ux discover (either via shell, via a registered MCP tool, or via the agent's native tool-use surface depending on the IDE).
The discovery flow asks the 10 questions, captures the answers, and writes .ux/last-discovery.json.
The host model calls ux recommend --brief-file .ux/last-discovery.json and reads the JSON it returns.
The host model generates the pricing page grounded in the recommendation — recommended style, palette, type pair, motion presets, components, brand exemplars, anti-pattern guardrails.
The host model calls ux lint ./src/components/Pricing.tsx --threshold high and acts on any findings.

The adapter doesn't carry the rules. It carries the pointer to the engine. The 100 anti-pattern rules, the 110 brand specs, the 84 style systems — they all live in the installed Python package. The adapter is the introduction.

This design is what makes the cross-IDE distribution actually scale. Bumping the engine from 100 to 120 rules doesn't require a single change to the 17 adapter files. The host model still calls ux lint, the linter still reads the current data/anti-patterns.json, and the new rules light up immediately. The adapters are stable; the engine evolves.

Per-IDE quirks worth knowing

Cursor and Windsurf — `.cursorrules` / `.windsurfrules`

Both IDEs read their dotfile on every session start. The file lives at the repo root. If your repo has 50,000 lines of code and the rules file is 2,000 lines, every chat turn pays the token cost of re-reading it. The ux-skill adapter keeps the file under 50 lines for this reason — the engine is invoked, not embedded.

GitHub Copilot — `.github/copilot-instructions.md`

This file is per-repo and read by Copilot Chat. It ships through .github/, so it survives git clone and shows up in PR-context for reviewers. There's no global install for Copilot — the file has to be in the repo.

Aider — two files

Aider is the one adapter that writes two files. .aider.conf.yml lists the data manifests as read: paths so Aider auto-loads them as read-only context on every session. AIDER.md carries the install prompt. The pair gives Aider both the rules (in the JSON) and the meta-instructions (in the Markdown).

Continue — JSON, not Markdown

Continue's project config is JSON. The adapter wraps the install prompt as systemMessage inside .continue/config.json. Continue then injects it as the chat system message on every session.

Claude Code — already canonical

Claude Code's signature is .claude/ and CLAUDE.md. ux-skill is typically installed as a Claude Code plugin (~/.claude/plugins/ux/ symlink) which means the adapter doesn't have much to write — the plugin manifest already exists. The Claude Code adapter is the cheapest of the 17.

JetBrains AI — works across the whole JetBrains family

The .jetbrains-ai/ directory is sibling to .idea/. The JetBrains AI Assistant picks it up regardless of which JetBrains IDE you open (IntelliJ IDEA, WebStorm, PyCharm, Rider, GoLand, RubyMine, PhpStorm, etc.). One adapter, six+ IDEs covered.

Verifying an install

After running ux install <target> (or ux init), confirm the adapter file is in place:

ls -la .cursorrules        # cursor
ls -la .windsurfrules      # windsurf
ls -la GEMINI.md           # gemini-cli
ls -la AGENTS.md           # codex
ls -la .github/copilot-instructions.md   # copilot
ls -la .continue/config.json             # continue
ls -la .aider.conf.yml AIDER.md          # aider

Then verify the engine itself is reachable from the IDE's shell — open the IDE, run a chat turn, and ask the model to call ux stats. The response should include per-manifest counts (84 styles, 176 palettes, 100 rules, etc.). If ux is not on PATH, install it with pip install uxskill or pipx install uxskill.

Adding an 18th IDE

The pattern is mechanical. Three edits in engine/installer/core.py:

Add to SUPPORTED: append the new IDE's target name.
Add to DETECT_SIGNATURES: map the target name to a list of files/directories that indicate this IDE is in use.
Add a writer function: implement _install_<target>(root, dry_run, report). For most cases, this is a one-liner wrapping _install_markdown_root (if the file is at the repo root) or _install_dotdir (if it lives under a dotted directory).
Wire into WRITERS: add the target → writer mapping.

Then add a test in tests/test_installer.py that covers detection and writing for the new target, and re-run pytest tests/test_installer.py -q. Submit a PR.

See also: Architecture · Installation · MCP Server · All 22 Commands Source: engine/installer/core.py

Cross IDE Distribution

Cross-IDE Distribution — the 17 IDE adapter list

Why 17 IDEs

The 17 adapters

The CLI install paths

Install for one IDE explicitly

Install via npx

Install for everything detected

Auto-detection

How the adapter ties back to the engine

Per-IDE quirks worth knowing

Cursor and Windsurf — .cursorrules / .windsurfrules

GitHub Copilot — .github/copilot-instructions.md

Aider — two files

Continue — JSON, not Markdown

Claude Code — already canonical

JetBrains AI — works across the whole JetBrains family

Verifying an install

Adding an 18th IDE

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally

Install via `npx`

Cursor and Windsurf — `.cursorrules` / `.windsurfrules`

GitHub Copilot — `.github/copilot-instructions.md`