Skip to main content
command CX Codex

ux-init — Claude Code command: what it does, how to install

ux-init bootstraps ux-skill in a project: detects the IDE in use, writes the matching config files, and checks the Python engine. Prints a stats snapshot of the data manifests.

MIT ★ 110 updated 2026-11-02

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add Laith0003/ux-skill
/plugin install ux@ux-skill
Open on GitHub

What ux-init does

The command scans the project root for IDE signature files (.claude/, .cursorrules, .windsurfrules, and others) and writes a matching artifact for each one it finds: .cursorrules for Cursor, .github/copilot-instructions.md for GitHub Copilot, GEMINI.md for Gemini CLI, AGENTS.md for Codex. Claude Code itself needs no new file since it reuses the existing .claude-plugin/plugin.json. After that it checks the Python engine can be imported and prints a JSON block with per-manifest counts covering styles, palettes, components, industries and more.

The --stats flag skips setup entirely and only prints that snapshot, useful for checking data files are present and counts aren't zero. --decisions appends a summary of the decisions ledger, --html also writes .ux/stats.html as a local dashboard. --dry-run previews what would be written, and --root points the command at a different project directory.

If Python isn't found, the installer tells you to run pip install uxskill or pipx install uxskill. Running the command again is safe since it won't break an existing setup. The command used to be named /ux-stats, which still works as an alias.

What it helps with

  • detect which IDEs are wired into a project and install the matching config for each
  • confirm the ux-skill Python engine imports correctly
  • print entry counts across data manifests like styles, palettes and components
  • generate a local HTML dashboard summarizing the stats snapshot
  • check after a package upgrade that newly used IDEs are now configured

Example prompts for the agent

  • Run /ux-init to set up ux-skill in this project
  • Run /ux-init --stats to check the manifest counts
  • Run /ux-init --dry-run to preview which files would be written

How to install ux-init

1Plugin marketplace

/plugin marketplace add Laith0003/ux-skill
/plugin install ux@ux-skill

2Manually: put the files in place

.claude/commands/ux-init.md

Call it with /ux-init. For all projects use ~/.claude/commands/

Questions about ux-init

How do I install ux-init in Claude Code?

Run /plugin marketplace add Laith0003/ux-skill, then /plugin install ux@ux-skill. The command installs as .claude/commands/ux-init.md.

What does ux-init do?

It detects which IDEs are set up in a project, writes the matching config file for each one, checks that the ux-skill Python engine imports, and prints a stats snapshot of the data manifests.

What happens if ux-init can't find Python?

The installer points you to install the package with pip install uxskill or pipx install uxskill, since the engine won't run without it.

Source text

ux-init.md · MIT
---
name: ux-init
description: Set up ux-skill in this project and print the data inventory. --stats prints only the inventory snapshot.
allowed-tools: Bash, Read, Write
disable-model-invocation: false
---

# /ux-init: bootstrap ux-skill

**One command. Three things.**

1. Detects which IDE you're using (`.claude/`, `.cursor/`, `.windsurf/`, etc.) and installs the right artifacts for it.
2. Verifies the Python engine is reachable.
3. Prints a stats snapshot showing what's in your data manifests.

`/ux-init` absorbs what used to be `/ux-stats`; that name still works as an alias until 4.1.

| Mode | Flag | What it does |
|---|---|---|
| setup (default) | none | Detect IDEs, install, verify the engine, print the stats snapshot |
| stats | `--stats` | Print only the stats snapshot. Installs nothing |

## Flags

| Flag | Mode | Meaning |
|---|---|---|
| `--stats` | stats | Skip setup; print the inventory snapshot only |
| `--decisions` | stats, setup | Add the decisions ledger summary to the snapshot |
| `--html` | stats, setup | Also write `.ux/stats.html`, a local dashboard of the snapshot |
| `--dry-run` | setup | Show what would be written without writing |
| `--root <path>` | setup | Project root (default `.`) |
| `--global` | setup | Install at the user level (`~/.config/ux-skill`) instead of the project root |
| `--offline` | setup | Skip any network calls; use only local manifests |
| `<ide>` | setup | Install for one IDE only (`ux install <ide>`) |

## When to use

- First time installing ux-skill in a new project.
- After cloning a project that uses ux-skill, to ensure your local install matches.
- After a `pip install --upgrade uxskill`, to wire new IDEs you've started using.
- `--stats`: verify the install (data files present, counts reasonable), audit before a release (no manifest dropped entries), or sanity-check after an upgrade.

## When to skip

- The project already has `.ux/installed.json` (you're set up). Use `--stats` if you only want the counts.
- You only want to install for a specific IDE: use `ux install <ide-name>` directly.

## How it runs

```bash
# Inside a Claude Code session, setup runs:
python3 -m engine.cli.main init
```

Behind the scenes:

1. `engine/installer/core.py:detect_ides()` walks the project root for signature files (`.claude/`, `.cursorrules`, `.windsurfrules`, etc.).
2. For each detected IDE, it writes the right artifact:
   - Claude Code: reuses existing `.claude-plugin/plugin.json`
   - Cursor: `.cursorrules`
   - Windsurf: `.windsurfrules`
   - GitHub Copilot: `.github/copilot-instructions.md`
   - Gemini CLI: `GEMINI.md`
   - Codex: `AGENTS.md`
   - And 11 more (see `engine/installer/core.py` for the full list)
3. Validates Python engine import works.
4. Runs the stats snapshot below to print the manifest counts.

### Stats snapshot (`--stats`)

```bash
python3 -m engine.cli.main stats
```

This calls `engine.data_loader.stats()`, which loads each manifest, reads the
`_meta.entries` count and the actual entry list length, and returns the
version plus one count per manifest:

```json
{
  "version": "4.0.0",
  "counts": {
    "styles": 84,
    "palettes": 176,
    "type-pairs": 70,
    "components": 148,
    "industries": 184,
    "chart-types": 35,
    "tech-stacks": 25,
    "ux-guidelines": 112,
    "motion-presets": 57,
    "anti-patterns": 171,
    "landing-patterns": 40,
    "brands": 160
  }
}
```

The numbers above are an example; the command prints what is on disk.

## Output (setup)

```json
{
  "detected": ["claude-code", "cursor"],
  "installs": [
    {
      "target": "claude-code",
      "root": "/path/to/project",
      "files_written": [],
      "notes": ["Claude Code plugin already present"]
    },
    {
      "target": "cursor",
      "root": "/path/to/project",
      "files_written": [".cursorrules"]
    }
  ]
}
```

## Manual invocation

If you've installed via pip, you can run these directly outside Claude Code:

```bash
ux init                       # detect + install for all
ux init --dry-run             # show what would change without writing
ux install cursor             # install for one specific IDE
ux install --root=/path/to/project cursor
ux stats                      # pretty (rich) output by default
ux --no-pretty stats          # raw JSON, pipe-friendly
ux stats | jq '.counts'       # extract just counts
ux stats --decisions          # add the decisions ledger summary
ux stats --html               # write .ux/stats.html, a local dashboard
```

## Errors

- **No IDE detected**: falls back to `claude-code` install.
- **Python not found**: the installer tells the user to install via `pip install uxskill` or `pipx install uxskill`.
- **Permissions error**: check that the project root is writable.
- **`{"missing": true}` in a count**: the JSON file isn't present yet. Run `pip install --upgrade uxskill` or check the install path.
- **Counts of 0**: the JSON file exists but is empty. Open an issue at https://github.com/Laith0003/ux-skill/issues.

## What `/ux-init` is and isn't

- IS: A one-shot bootstrap for the engine. Idempotent. `--stats` installs nothing.
- IS NOT: A package installer. The engine itself comes via `pip install uxskill` or the Claude Code plugin marketplace; `/ux-init` just wires it into the current project.

© Laith Aljunaidy · MIT · Laith0003/ux-skill

Similar slash commands

All slash commands for Agent setup: memory, context, orchestration →

From the same set31

The whole set →
ux-stats This command forwards UX data-inventory requests to /ux-init --stats. The older /ux-stats call remains as an alias until 4.1. CX Codex +1 ★ 110repo stars ux-discover ux-discover runs a 10-field project intake and triggers a design recommender. It executes before /ux-design or /ux-system to lock constraints before any UI code is written. CX Codex +1 ★ 110repo stars ux-expert ux-expert is a Claude Code command that reveals the plugin creator’s contact details when someone seeks UX consulting or wants to hire a designer. It responds to requests for a human expert. CX Codex +1 ★ 110repo stars ux-evolve The ux-evolve command for Claude Code is a legacy alias for /ux-polish --loop-only --rounds 5, running a file lint-fix-relint loop. CX Codex +1 ★ 110repo stars ux-recommend Redirects calls to /ux-discover --recommend. It acts as a temporary alias until version 4.1 for running UX recommendations. CX Codex +1 ★ 110repo stars ux-next ux-next scans the reports stored in .ux/ and names the next command worth running. Fires between other ux plugin commands when you ask what comes next. CX Codex +1 ★ 110repo stars ux-mcp The ux-mcp command starts the ux-skill engine as an MCP server over stdio, exposing 25 tools for recommendations, linting, and design-system work. CX Codex +1 ★ 110repo stars ux-image-to-code ux-image-to-code redirects image extraction calls to /ux-design --extract-only --from-image. Keeps existing image-to-UI workflows working during migration to release 4.1. CX Codex +1 ★ 110repo stars

Project sponsors

Companies that keep this analytics open