# ui-ux-pro-max-skill Administrator & Developer Guide

The administrator and developer perspective on `nextlevelbuilder/ui-ux-pro-max-skill`. This document covers the architecture of the package, the platform-config JSON schema that drives every install, the install pipeline, security review of a skill pack that runs with the host AI's tool grants, and the developer-internals needed to extend the skill with new platforms or new reference data.

The repository is split into a small Node/TypeScript CLI (`cli/src/`) and a much larger asset payload (`cli/assets/` shipped to npm, mirrored in `src/ui-ux-pro-max/` as the source-of-truth tree). The CLI's only job is to copy the asset payload into the right folder for the user's AI assistant. The actual design intelligence — 33 CSV reference files, 3 Python search scripts, and a SKILL.md flavored per platform — lives entirely in the asset payload and runs only when an AI agent invokes it post-install.

> [!NOTE]
> "Multi-platform" in this codebase means **multiple AI coding assistants** (Claude Code, Cursor, Windsurf, Copilot, plus 14 others), not multiple operating systems. Eighteen platforms are supported as of v2.5.0; each platform contributes one JSON config under `cli/assets/templates/platforms/`.

---

## 1. Architecture Overview

The system has four layers, each with a single responsibility. The boundaries between them are sharp and the code surface is small (~50 KB of TypeScript), making this an unusually predictable codebase to audit.

```text
+----------------------------------------------------------+
|                  uipro-cli (Node 18+)                    |
|  cli/src/index.ts (commander root)                       |
|     init / update / uninstall / versions                 |
|                          |                               |
|        +----------------+----------------+               |
|        v                v                v               |
|   detectAIType    templateInstall    GitHub fetch        |
|  (utils/detect)   (utils/template)   (utils/github,      |
|                                       --legacy only)     |
|                          |                               |
|                          v                               |
|              File writer (cp / mkdir / cleanup)          |
|              writes to <root>/<platform>/skills/...      |
+----------------------------------------------------------+
                           |
                           v
+----------------------------------------------------------+
|              Asset payload (cli/assets/...)              |
|  templates/                                              |
|    base/skill-content.md     (shared SKILL.md template)  |
|    base/quick-reference.md   (shared QR cheat sheet)     |
|    platforms/<18 JSONs>      (per-platform config)       |
|  data/                                                   |
|    *.csv (15 root tables) + stacks/*.csv (16 stacks)     |
|  scripts/                                                |
|    core.py / design_system.py / search.py                |
+----------------------------------------------------------+
                           |
                           v (after install)
+----------------------------------------------------------+
|           Host AI assistant (Claude / Cursor / ...)      |
|  Loads .<root>/skills/ui-ux-pro-max/SKILL.md             |
|  Invokes data/*.csv via scripts/search.py at design time |
+----------------------------------------------------------+
```

### Component inventory

| Component | Path | Role |
|---|---|---|
| CLI entry | `cli/src/index.ts` | Commander setup; defines `init`, `versions`, `update`, `uninstall` |
| Init command | `cli/src/commands/init.ts` | Pick path (template/legacy), call writer, print summary |
| Update command | `cli/src/commands/update.ts` | Calls `getLatestRelease()` then re-runs `init` with `force=true` |
| Uninstall command | `cli/src/commands/uninstall.ts` | Resolve `AI_FOLDERS[ai]`, recursively remove `skills/ui-ux-pro-max/` |
| Versions command | `cli/src/commands/versions.ts` | List GitHub releases newest-first |
| Type definitions | `cli/src/types/index.ts` | `AIType` union, `AI_TYPES` allow-list, `AI_FOLDERS` map, `PlatformConfig` interface |
| Detect | `cli/src/utils/detect.ts` | Scan cwd for marker folders, return detected list and a single suggestion |
| Extract | `cli/src/utils/extract.ts` | ZIP extraction (PowerShell on Windows, `unzip` elsewhere); folder copy with filter; temp-dir lifecycle |
| GitHub | `cli/src/utils/github.ts` | `fetch`-based REST client with rate-limit guards |
| Logger | `cli/src/utils/logger.ts` | Chalk-themed `info` / `success` / `warn` / `error` / `title` / `dim` |
| Template | `cli/src/utils/template.ts` | Load platform JSON, render base templates, write SKILL.md, copy data + scripts |
| Skill manifest | `skill.json` | Top-level manifest (name, version, platforms, install command) |
| Source-of-truth tree | `src/ui-ux-pro-max/...` | Mirror of `cli/assets/...`, kept in sync via `_sync_all.py` |

### Technology stack

| Layer | Technology | Version (from `cli/package.json`) |
|---|---|---|
| Runtime | Node.js | `>=18` |
| Language | TypeScript | `^5.7.2` (devDep) |
| Build | bun | implicit (`bun build src/index.ts --outdir dist --target node`) |
| CLI parser | `commander` | `^12.1.0` |
| Color/styling | `chalk` | `^5.3.0` |
| Spinner | `ora` | `^8.1.1` |
| Prompts | `prompts` | `^2.4.2` |
| Skill scripts | Python 3 | runtime-required on the user's machine |

> [!NOTE]
> The package ships executable Python scripts inside the npm package. The CLI does not run Python — the **AI agent** invokes the scripts through its tool-call surface after install. This matters for security review (section 7).

### Data flow — default install path

1. User runs `npx uipro-cli init [--ai <type>] [--global]`.
2. `index.ts` parses flags via `commander` and dispatches to `initCommand` (`commands/init.ts`).
3. If `--ai` is omitted, `detectAIType()` walks the cwd for marker folders and shows an interactive picker.
4. `templateInstall()` calls `generatePlatformFiles()` (or `generateAllPlatformFiles()` for `--ai all`).
5. `loadPlatformConfig(aiType)` reads `cli/assets/templates/platforms/<platform>.json`.
6. `renderSkillFile()` reads `cli/assets/templates/base/skill-content.md` and (optionally) `quick-reference.md`, applies the per-platform JSON, and substitutes `{{TITLE}}`, `{{DESCRIPTION}}`, `{{SCRIPT_PATH}}`, `{{SKILL_OR_WORKFLOW}}`, `{{QUICK_REFERENCE}}` placeholders.
7. The renderer writes `SKILL.md` to `<effectiveDir>/<root>/<skillPath>/<filename>`.
8. `copyDataAndScripts()` recursively copies `cli/assets/data/` and `cli/assets/scripts/` into the same skill folder.
9. The CLI prints the list of folders it touched and a "Next steps" message ("Restart your AI coding assistant").

### Data flow — `--legacy` ZIP path

1. Same parse + detect.
2. `tryGitHubInstall()` calls `getLatestRelease()`, then `getAssetUrl()`. If no uploaded ZIP exists, falls back to `https://github.com/nextlevelbuilder/ui-ux-pro-max-skill/archive/refs/tags/<tag>.zip`.
3. `downloadRelease(url, zipPath)` writes the asset to a `mkdtemp` temp dir (`tmpdir() + 'uipro-'`).
4. `installFromZip()` calls `extractZip()` (PowerShell `Expand-Archive` on Windows, `unzip -o` elsewhere), then `findExtractedRoot()` (use the single subdir if there is one, else the temp dir).
5. `copyFolders()` walks `AI_FOLDERS[aiType]`, deduplicates, copies recursively while filtering `EXCLUDED_FILES = ['settings.local.json']`.
6. On copy failure, falls back to `xcopy` (Windows) or `cp -r` (Unix); silently skips unreadable folders.
7. `cleanup(tempDir)` removes the temp dir on success or error.

> [!WARNING]
> Any failure inside `tryGitHubInstall` (rate limit, download failure, network error) **degrades silently** to template install. The user sees a `spinner.warn(...)` with the failure category, then the install proceeds via the bundled assets. This is intentional — `--legacy` is a fallback, not a required path — but it does mean a `--legacy` invocation may produce the same files as the default. If you depend on `--legacy` for pinning, check the install summary line (`Installed from GitHub release!` vs `Installed from bundled assets!` vs `Generated from templates!`).

### Dual asset tree

The repo maintains two asset trees in lockstep:

| Tree | Purpose |
|---|---|
| `cli/assets/...` | The npm-published payload (declared in `cli/package.json`'s `files: ["dist", "assets"]`) |
| `src/ui-ux-pro-max/...` | The source-of-truth tree under the project root |

A `_sync_all.py` script (present in both `cli/assets/scripts/` and `src/ui-ux-pro-max/scripts/`) keeps them aligned. Drift between the two trees is the most likely maintenance bug — flag any PR that changes one without the other.

> [!NOTE]
> This dual-tree layout is a mid-life refactor artifact: an earlier version shipped from `src/ui-ux-pro-max/` directly; the current version ships from `cli/assets/` for npm. Both are kept alive so contributors don't break either workflow.

---

## 2. System Requirements

| Component | Minimum | Notes |
|---|---|---|
| Node.js | 18.x | Enforced indirectly by `commander@^12.1.0` (`engines.node: ">=18"`) and `ora@^8.1.1` (`engines.node: ">=18"`) |
| Operating system | Windows / macOS / Linux | Cross-platform tested; PowerShell required on Windows for ZIP extract; `unzip` required on Unix for ZIP extract |
| Python | 3.x at runtime | Only required at skill-execution time inside the AI assistant. Not required to install. |
| Disk | ~5 MB per AI platform installed | CSVs + scripts + markdown templates |
| Network | optional | Default install path is offline; `--legacy`, `update`, and `versions` use HTTPS to `api.github.com` |
| User permission | non-admin | Writes only inside `cwd` or `homedir()` |

### Dependencies

Runtime dependencies (`cli/package.json`):

```json
{
  "commander": "^12.1.0",
  "chalk": "^5.3.0",
  "ora": "^8.1.1",
  "prompts": "^2.4.2"
}
```

Dev dependencies (build only):

```json
{
  "@types/bun": "^1.1.14",
  "@types/node": "^22.10.1",
  "@types/prompts": "^2.4.9",
  "typescript": "^5.7.2"
}
```

### What's published to npm

`cli/package.json` declares:

```json
{
  "name": "uipro-cli",
  "version": "2.5.0",
  "type": "module",
  "bin": { "uipro": "./dist/index.js" },
  "files": ["dist", "assets"]
}
```

The `dist/` folder is a single bundled JS file produced by `bun build src/index.ts --outdir dist --target node`. The `assets/` folder ships verbatim — that is the entire skill payload.

> [!IMPORTANT]
> If the `assets/` folder is missing from a published version, every install will fail with `Unknown AI type` errors at template-load time. Always validate the npm tarball contains the asset tree before pushing a release.

---

## 3. Configuration Reference

There is no user-editable configuration. All "configuration" is one of two things: (a) CLI flags, (b) per-platform JSON configs that ship with the package.

### CLI flags (full reference)

Defined in `cli/src/index.ts`.

| Command | Flag | Type | Default | Description | Source |
|---|---|---|---|---|---|
| `init` | `-a, --ai <type>` | enum | undefined | AI assistant type (member of `AI_TYPES`) | `cli/src/index.ts:30` |
| `init` | `-f, --force` | bool | `false` | Overwrite existing files | `cli/src/index.ts:31` |
| `init` | `-o, --offline` | bool | `false` | Skip GitHub download, use bundled assets only (no effect on default template path) | `cli/src/index.ts:32` |
| `init` | `-g, --global` | bool | `false` | Install to home directory (`~/`) instead of cwd | `cli/src/index.ts:33` |
| `update` | `-a, --ai <type>` | enum | undefined | Same allow-list as `init` | `cli/src/index.ts:54` |
| `uninstall` | `-a, --ai <type>` | enum | undefined | Same allow-list as `init` | `cli/src/index.ts:69` |
| `uninstall` | `-g, --global` | bool | `false` | Uninstall from home directory | `cli/src/index.ts:70` |

The `versions` command takes no flags; it lists releases from `https://api.github.com/repos/nextlevelbuilder/ui-ux-pro-max-skill/releases`.

### Allow-list of `<type>` values

From `cli/src/types/index.ts`:

```ts
export const AI_TYPES: AIType[] = [
  'claude', 'cursor', 'windsurf', 'antigravity', 'copilot',
  'roocode', 'kiro', 'codex', 'qoder', 'gemini',
  'trae', 'opencode', 'continue', 'codebuddy', 'droid',
  'kilocode', 'warp', 'augment',
  'all',
];
```

If `--ai` is given but not in this list, `cli/src/index.ts` prints `Invalid AI type: <foo>` and `Valid types: ...`, then `process.exit(1)`.

### `AI_FOLDERS` map (which root folders each platform owns)

From `cli/src/types/index.ts`:

```ts
export const AI_FOLDERS: Record<Exclude<AIType, 'all'>, string[]> = {
  claude:      ['.claude'],
  cursor:      ['.cursor', '.shared'],
  windsurf:    ['.windsurf', '.shared'],
  antigravity: ['.agents', '.shared'],
  copilot:     ['.github', '.shared'],
  kiro:        ['.kiro', '.shared'],
  codex:       ['.codex'],
  roocode:     ['.roo', '.shared'],
  qoder:       ['.qoder', '.shared'],
  gemini:      ['.gemini', '.shared'],
  trae:        ['.trae', '.shared'],
  opencode:    ['.opencode', '.shared'],
  continue:    ['.continue'],
  codebuddy:   ['.codebuddy'],
  droid:       ['.factory'],
  kilocode:    ['.kilocode', '.shared'],
  warp:        ['.warp', '.shared'],
  augment:     ['.augment', '.shared'],
};
```

> [!NOTE]
> The `.shared` folder is included for backward compatibility with the older ZIP-based install layout. Newer platforms (`kilocode`, `warp`, `augment`) include it as a no-op so `uninstall` removes the same set across versions. Five platforms (`claude`, `codex`, `continue`, `codebuddy`, `droid`) own a single root folder with no `.shared` companion.

### Platform-config JSON schema (the flagship config reference)

Every platform contributes one file under `cli/assets/templates/platforms/<platform>.json`. The schema is encoded in `PlatformConfig` (`cli/src/types/index.ts`) and consumed by `cli/src/utils/template.ts`.

| Field | Type | Required | Purpose |
|---|---|---|---|
| `platform` | string | yes | Internal name (matches the JSON filename without extension) |
| `displayName` | string | yes | Human-readable label shown in install logs |
| `installType` | `'full'` \| `'reference'` | yes | `full` = ship complete SKILL.md + assets; `reference` = lighter pointer file |
| `folderStructure.root` | string | yes | The top-level dotted folder (e.g. `.claude`) |
| `folderStructure.skillPath` | string | yes | Relative path under `root` where the skill lives (e.g. `skills/ui-ux-pro-max`) |
| `folderStructure.filename` | string | yes | Name of the rendered skill file (typically `SKILL.md`) |
| `scriptPath` | string | yes | Path the SKILL.md uses when invoking Python scripts (e.g. `python3 skills/ui-ux-pro-max/scripts/...`) |
| `frontmatter` | `Record<string,string>` \| null | yes | YAML frontmatter block to prepend; `null` for platforms that don't accept frontmatter |
| `sections.quickReference` | bool | yes | Whether to inline `base/quick-reference.md` |
| `title` | string | yes | Title injected into `{{TITLE}}` placeholder |
| `description` | string | yes | Injected into `{{DESCRIPTION}}` placeholder |
| `skillOrWorkflow` | string | yes | The word the platform uses ("skill" / "workflow" / "agent") |

### Eighteen platform config files

| File | Platform | Notes |
|---|---|---|
| `agent.json` | Antigravity | Mapped from `aiType: 'antigravity'` via `AI_TO_PLATFORM` |
| `augment.json` | Augment | |
| `claude.json` | Claude Code | |
| `codebuddy.json` | CodeBuddy | |
| `codex.json` | Codex | |
| `continue.json` | Continue | |
| `copilot.json` | GitHub Copilot | Lives under `.github/prompts/` rather than `.github/skills/` |
| `cursor.json` | Cursor | |
| `droid.json` | Droid (Factory) | Lives under `.factory/` |
| `gemini.json` | Gemini CLI | |
| `kilocode.json` | KiloCode | |
| `kiro.json` | Kiro | Lives under `.kiro/steering/` (per `getAITypeDescription`) |
| `opencode.json` | OpenCode | |
| `qoder.json` | Qoder | |
| `roocode.json` | RooCode | |
| `trae.json` | Trae | |
| `warp.json` | Warp | |
| `windsurf.json` | Windsurf | Earlier versions shipped without YAML frontmatter (issue #204, fixed) |

### Frontmatter rendering rules

`renderFrontmatter` in `cli/src/utils/template.ts`:

1. If `frontmatter` is `null`, emit nothing.
2. Otherwise emit `---\n`, then each `key: value` line, then `---\n\n`.
3. If a value contains `:`, `"`, or a newline, wrap in double quotes and escape inner quotes with `\\"`.

### Placeholder substitution

`renderSkillFile` performs a fixed set of replacements against `base/skill-content.md`:

| Placeholder | Replaced with |
|---|---|
| `{{TITLE}}` | `config.title` |
| `{{DESCRIPTION}}` | `config.description` |
| `{{SCRIPT_PATH}}` | `config.scriptPath` |
| `{{SKILL_OR_WORKFLOW}}` | `config.skillOrWorkflow` |
| `{{QUICK_REFERENCE}}` | inline content of `base/quick-reference.md` if `sections.quickReference` is true, else empty |

When `--global` is used, an extra rewrite kicks in:

```ts
content = content.replace(
  /python3 skills\//g,
  `python3 ~/${config.folderStructure.root}/skills/`
);
```

This makes script paths absolute under `~/<root>/`, which is needed when the skill lives in the user's home directory rather than the project tree.

### Excluded files during ZIP install

`cli/src/utils/extract.ts`:

```ts
const EXCLUDED_FILES = ['settings.local.json'];
```

Anything matching this list is filtered out by `cp(...)` during `--legacy` install. Add new entries here if a future platform ships a private settings file that must never be copied.

---

## 4. Deployment & Scaling

The CLI is single-process, single-shot. There is no daemon, no service, no long-running state. Each `init` run is a stateless transformation: read assets + JSON + flags → write files.

### Build & release pipeline

Defined in `cli/package.json`:

```json
{
  "scripts": {
    "build": "bun build src/index.ts --outdir dist --target node",
    "dev": "bun run src/index.ts",
    "prepublishOnly": "bun run build"
  }
}
```

Steps to cut a release:

1. Update version in `cli/package.json` and `skill.json`.
2. Run `_sync_all.py` (in `cli/assets/scripts/` or `src/ui-ux-pro-max/scripts/`) to ensure both asset trees match.
3. `cd cli && bun run build` produces `cli/dist/index.js`.
4. `npm publish` from `cli/`. The `prepublishOnly` hook re-runs `bun run build` defensively.
5. Tag the corresponding GitHub release. The auto-archive URL is what `getAssetUrl()` falls back to when no uploaded ZIP asset exists.

> [!IMPORTANT]
> Issue #202 reported that `plugin.json` version was stuck at 2.0.1 while GitHub releases showed v2.5.0. The lesson: bump **every** versioned manifest in lockstep — `cli/package.json`, `skill.json`, and any platform JSON that includes a version string — and tag a Git release that matches all of them.

### Distribution channels

| Channel | Surface | Audience |
|---|---|---|
| npm | `uipro-cli` | Developers running `npx uipro-cli init` |
| GitHub releases | tarball/ZIP per tag | `--legacy` install path; `versions` / `update` callers |
| GitHub repo | source clone | Forks and contributors |

### Scaling considerations

There is nothing to scale on the runtime side — every install is a local file copy. What does scale is **support load**:

- Issues with ratio "command not found / unknown option" tend to be caused by stale `npx` caches (#215). Document the `npx clear-npx-cache` remedy upfront.
- Platform-detection misses ("nothing happened") are usually marker-folder mismatches (e.g. user has `.claude-code/` instead of `.claude/`) — extend `detectAIType()` and the `AI_FOLDERS` map.
- Per-platform SKILL.md issues (e.g. windsurf without frontmatter, #204) require a release that updates only the affected platform JSON and republishes.

### Uninstall behavior

`cli/src/commands/uninstall.ts`:

1. Determine `baseDir`: `homedir()` if `--global`, else `process.cwd()`.
2. Detect existing installs via `detectAIType(baseDir)`.
3. Prompt the user with the detected list (or `'all detected'`).
4. For each chosen platform, walk `AI_FOLDERS[ai]` and `rm(skills/ui-ux-pro-max, { recursive: true, force: true })`.
5. Skip `ENOENT` (folder not present); re-throw any other error.
6. Print the list of removed paths.

---

## 5. Operations

Day-to-day operational concerns for someone who has the package installed and is keeping it healthy.

### Routine maintenance checklist

- [ ] After each release, run `npx uipro-cli@latest update` on the workstations that use the skill
- [ ] Verify the install: `ls -la .<tool>/skills/ui-ux-pro-max/` should show `SKILL.md`, `data/`, `scripts/`
- [ ] If using `--global`, confirm `~/.<tool>/skills/ui-ux-pro-max/` is intact
- [ ] If you maintain a fork, run `_sync_all.py` after any data edit so `cli/assets/` and `src/ui-ux-pro-max/` stay aligned
- [ ] Watch GitHub issues for new platform-detection requests (`detectAIType` updates)

### Operational error reference

Eight error classes are thrown explicitly in the codebase. Documented as **Type / Message / Source / Operational response**.

| Type | Message | Source | Response |
|---|---|---|---|
| `GitHubDownloadError` | `No ZIP asset found in latest release` | `cli/src/commands/init.ts:49` | Drop `--legacy`; default path is unaffected |
| `Error` | `Failed to extract zip: ${error}` | `cli/src/utils/extract.ts:22` | Install `unzip` or use Windows host with PowerShell |
| `GitHubRateLimitError` | `GitHub API rate limit exceeded. Resets at ${resetDate}` | `cli/src/utils/github.ts:27` | Wait or set `GITHUB_TOKEN`; or drop `--legacy` |
| `GitHubRateLimitError` | `GitHub API rate limit exceeded (429 Too Many Requests)` | `cli/src/utils/github.ts:30` | Same |
| `GitHubDownloadError` | `Failed to fetch releases: ${response.status} ${response.statusText}` | `cli/src/utils/github.ts:47` | Retry; transient |
| `GitHubDownloadError` | `Failed to fetch latest release: ${response.status} ${response.statusText}` | `cli/src/utils/github.ts:66` | Retry; consider drop-`--legacy` |
| `GitHubDownloadError` | `Failed to download: ${response.status} ${response.statusText}` | `cli/src/utils/github.ts:83` | Drop `--legacy` |
| `Error` | `Unknown AI type: ${aiType}` | `cli/src/utils/template.ts:66` | Check `--ai <type>` against allow-list |

### Logging

`cli/src/utils/logger.ts`:

```ts
export const logger = {
  info:    (msg) => console.log(chalk.blue('info'), msg),
  success: (msg) => console.log(chalk.green('success'), msg),
  warn:    (msg) => console.log(chalk.yellow('warn'), msg),
  error:   (msg) => console.log(chalk.red('error'), msg),
  title:   (msg) => console.log(chalk.bold.cyan(`\n${msg}\n`)),
  dim:     (msg) => console.log(chalk.dim(msg)),
};
```

There is no log file. All output goes to stdout/stderr. The `ora` spinner adds ephemeral progress lines. CI consumers should set `FORCE_COLOR=0` if they need uncolored output.

> [!TIP]
> If you wrap the CLI in another tool, parse the install summary line — `Generated from templates!` vs `Installed from GitHub release!` vs `Installed from bundled assets!` — to know which install path actually ran. This is the single source of truth in the absence of a structured log.

### Common operational questions

> [!NOTE]
> Issue #181 ("How should Claude Code use this skill?") and #266 (sub-skill name frontmatter mismatch) are repeat-pattern questions. Answer them by pointing to (a) restart-after-install, (b) `npx uipro-cli@latest init --force` to overwrite stale frontmatter, (c) the per-platform JSON config under `cli/assets/templates/platforms/`.

### Backup & restore

Nothing to back up at the package level — the package is reproducible from npm. If users have customized their installed skill files (against advice in the User Guide), back up the `.<tool>/skills/ui-ux-pro-max/` folder before re-running `init`.

---

## 6. Performance

Performance is an install-time concern only. Once installed, the AI agent owns runtime behavior.

### Install timing

| Path | Typical wall-clock |
|---|---|
| Default template install (`init`) | < 2 seconds (no network, local file copy of ~5 MB) |
| `init --ai all` | ~ 10 seconds (18 platforms × ~0.5 s each, dominated by recursive `cp` calls) |
| `--legacy` install with cached temp ZIP | ~ 5 seconds |
| `--legacy` install over cold network | 5–30 seconds depending on link quality |
| `versions` command | 1–3 seconds (single GitHub list call) |
| `update` command | 1 second metadata + same as `init --force` |

> [!TIP]
> Issue #260 ("UI/UX Pro Max Installer 很慢" — slow installer) typically traces to either (a) the user is on `--legacy` and their network is slow, or (b) their npm cache is cold. The default template path on a warm cache is sub-second.

### Bottlenecks and mitigations

- **`fetch` to GitHub**: only relevant for `--legacy`, `update`, `versions`. Avoid by sticking with the default install.
- **Recursive copy**: dominates install time when `--ai all` is used. Mitigation: ask users whether they really need `all` or just their primary AI tool.
- **PowerShell `Expand-Archive`**: slow on large ZIPs in older PowerShell versions. Mitigation: use the default template path on Windows.

### Memory / disk footprint

- Installed skill folder per platform: ~5 MB.
- `--ai all`: ~90 MB total written across 18 platform folders (most identical assets duplicated under each `<root>/skills/ui-ux-pro-max/`).
- npm package: ~500 KB compressed.

### Network considerations

The default install does **zero network calls**. The user's npm/`npx` infrastructure handles fetching the package itself; the CLI then runs entirely against bundled assets. Air-gapped environments work without configuration once the npm package has been mirrored.

---

## 7. Security

Skill packs run inside the AI assistant's process and inherit its tool grants — file read/write, shell execution, network, and any MCP server the assistant has attached. That makes a skill a meaningful supply-chain dependency. The points below are the threat model for `ui-ux-pro-max-skill` specifically.

### Trust boundary

The skill ships three trust-relevant artifacts:

1. **`SKILL.md`** — instructions read by the AI at inference time. A malicious instruction file can manipulate the model into running arbitrary commands, exfiltrating files, or producing biased output. Review before installing into a privileged environment.
2. **`scripts/*.py`** — Python scripts the AI invokes via tool-call. They run in the AI's tool sandbox (or unsandboxed, depending on the host). Read all three before installing into a privileged environment.
3. **`data/*.csv`** — reference data. Lower risk because they're read by the Python scripts, not executed; still worth diffing against past versions to spot unexpected changes.

> [!CAUTION]
> A skill pack runs with **the AI's full tool grants**. If your AI has shell access, the skill can ask the AI to run shell commands on your machine. Always review `SKILL.md` and the Python scripts before installing in a sensitive environment, and never install from an untrusted fork.

### Supply-chain considerations

- **npm package integrity**: the package is published as `uipro-cli` to the public npm registry. Verify the publisher and version pin where it matters: `npx uipro-cli@2.5.0` rather than `npx uipro-cli`.
- **Bundled Python**: the package ships `.py` files inside an npm package. Auditors who only scan JS dependencies will miss these — call them out explicitly in security review.
- **No checksum verification**: the CLI does not verify a hash of the bundled assets it installs. A tampered npm tarball would install without alerting the user.
- **Dual asset tree drift**: `cli/assets/` and `src/ui-ux-pro-max/` can drift. The npm-published copy is `cli/assets/`; the `src/` tree is for development. A user who clones the repo and installs from a checkout sees a different artifact than a user who runs `npx`.
- **Issue #161** ("UI UX Pro Max is a scam, don't buy it") was a closed report; the repo is MIT-licensed and free to use, no purchase required. Treat unverified accusations cautiously but verify the package origin and license yourself.

### Data residency

The CLI does not transmit user prompts or designs anywhere. Data residency concerns are entirely about what your **AI assistant** does with the prompts you send — that's a property of the AI host, not of this skill pack. The skill itself is a passive read.

### Path-traversal & file-write surface

`cli/src/utils/extract.ts` and `template.ts` write to `process.cwd()` or `homedir()`. Inputs that influence paths:

- `--ai <type>` is checked against `AI_TYPES` — bounded set, no traversal possible.
- `--global` toggles a fixed `homedir()` call.
- `config.folderStructure.root`, `skillPath`, `filename` come from package-internal JSONs, not user input — no traversal possible from outside.
- `config.scriptPath` is interpolated into SKILL.md text, not a filesystem path.

Conclusion: there is **no user-controlled path** that the CLI uses for filesystem writes. The blast radius is bounded to either `cwd` or `homedir`.

### Shell-injection surface

`cli/src/utils/extract.ts` uses `child_process.exec` for ZIP extraction:

```ts
if (isWindows) {
  await execAsync(`powershell -Command "Expand-Archive -Path '${zipPath}' -DestinationPath '${destDir}' -Force"`);
} else {
  await execAsync(`unzip -o "${zipPath}" -d "${destDir}"`);
}
```

`zipPath` is `tempDir + 'release.zip'` (CLI-controlled, `mkdtemp` output). `destDir` is `tempDir` from `createTempDir()`. Both come from `mkdtemp(join(tmpdir(), 'uipro-'))` — not user-controlled. There is no user-controlled string passed to `exec`.

The `xcopy` and `cp -r` fallbacks in `copyFolders` interpolate `sourcePath` and `targetPath`, which are `join(sourceDir, folder)` and `join(targetDir, folder)`. `folder` comes from `AI_FOLDERS[aiType]` — bounded set, internally controlled.

> [!WARNING]
> Although the current code has no user-controlled exec inputs, any future change that lets the user pick a custom destination path or platform name **must** be plumbed through `child_process.execFile` (with argv array) instead of `exec` (with a shell string). The current `exec` calls are safe only because their inputs are package-internal.

### License

Both `cli/package.json` and `skill.json` declare `"license": "MIT"`. The repository ships a `LICENSE` file at the root.

### Audit log

Maintain an audit trail when installing in regulated environments:

- Pin the version: `npx uipro-cli@<exact-version> init`
- Capture the install summary line (`Generated from templates!`)
- Hash the resulting `.<tool>/skills/ui-ux-pro-max/SKILL.md` and Python scripts
- Compare against a known-good baseline at re-install time

---

## 8. Developer Internals

How to read the codebase, how the SKILL.md trigger pattern is implemented, and how to extend the skill with new platforms or new reference data.

### Repository layout

```text
ui-ux-pro-max-skill/
├── CLAUDE.md                      # repo's own AI context
├── LICENSE                        # MIT
├── README.md                      # public-facing pitch
├── skill.json                     # top-level manifest (name, version, platforms)
├── .gitignore
├── cli/                           # The CLI package (published to npm)
│   ├── README.md
│   ├── package.json               # bin: uipro -> dist/index.js
│   ├── package-lock.json
│   ├── bun.lock
│   ├── tsconfig.json
│   ├── .gitignore / .npmignore
│   ├── src/                       # TypeScript sources (HIGH priority modules)
│   │   ├── index.ts               # commander root
│   │   ├── commands/              # init.ts, uninstall.ts, update.ts, versions.ts
│   │   ├── types/                 # index.ts (AIType, AI_TYPES, AI_FOLDERS, PlatformConfig)
│   │   └── utils/                 # detect.ts, extract.ts, github.ts, logger.ts, template.ts
│   └── assets/                    # The npm-shipped asset payload
│       ├── data/                  # 15 root CSVs + stacks/ (16 stack CSVs) + _sync_all.py
│       ├── scripts/               # core.py, design_system.py, search.py
│       └── templates/
│           ├── base/              # quick-reference.md, skill-content.md
│           └── platforms/         # 18 platform JSONs
├── docs/                          # 三个 data-scripts-templates 的区别.md
├── preview/                       # xiaomaomi-app.html (skill output sample)
├── screenshots/                   # website.png
└── src/ui-ux-pro-max/             # Source-of-truth tree (mirror of cli/assets/)
    ├── data/                      # mirrors cli/assets/data/
    ├── scripts/                   # mirrors cli/assets/scripts/
    └── templates/                 # mirrors cli/assets/templates/
```

### SKILL.md trigger pattern

The skill activates inside the AI assistant via the platform's standard skill-loading mechanism — there is no custom magic phrase. Specifically:

1. The AI assistant lists the skill in its skill catalog by reading the YAML frontmatter at the top of `SKILL.md`.
2. The frontmatter is rendered by `renderFrontmatter()` from each platform's JSON `frontmatter` field — so trigger metadata (description, intent words) is platform-controlled and varies per `cli/assets/templates/platforms/<platform>.json`.
3. At inference time, the assistant's own logic decides whether the user's prompt matches the skill's description; if so, it loads `SKILL.md` and follows its body.
4. The body of `SKILL.md` (rendered from `base/skill-content.md` with `{{TITLE}}` / `{{DESCRIPTION}}` / `{{SCRIPT_PATH}}` / `{{SKILL_OR_WORKFLOW}}` / `{{QUICK_REFERENCE}}` substituted) instructs the assistant to use the bundled CSVs and Python scripts.

This means there is no codified "activation phrase" inside the package. The phrasing your assistant treats as a trigger is a function of the assistant + the description rendered from the platform JSON. Empirically, design-intent words ("design", "UI", "UX", "layout", "color", "typography", "audit", "wireframe", or naming a stack) reliably activate the skill across all 18 supported platforms.

### Asset organization principles

The asset payload is grouped by *what kind of intelligence* it provides, not by *which feature uses it*. This is intentional — any feature (design, audit, palette pick) can read any CSV.

- `data/*.csv` — flat tag-indexed reference tables, one concept per file
- `data/stacks/*.csv` — same shape but indexed by tech stack, used to translate a chosen design into idiomatic code
- `scripts/*.py` — composition layer (`core.py` shared, `design_system.py` for full-system synthesis, `search.py` for ad-hoc fuzzy lookup)
- `templates/base/*.md` — the SKILL.md body shared across platforms
- `templates/platforms/*.json` — per-platform deltas (frontmatter, scriptPath, title, description)

### Adding a new AI platform

A working recipe — every step is required, none can be skipped:

1. **Choose a folder convention** for the new platform (e.g. `.newtool/`).
2. **Edit `cli/src/types/index.ts`**:
   - Add the new value to the `AIType` union.
   - Add it to the `AI_TYPES` array (before `'all'`).
   - Add an entry to `AI_FOLDERS` with at least one folder; include `.shared` if the platform's earlier installs depended on it (most don't anymore).
3. **Edit `cli/src/utils/detect.ts`**:
   - Add a marker-folder check that pushes the new value into `detected` when the marker is present.
4. **Edit `cli/src/utils/detect.ts` `getAITypeDescription`**:
   - Add a `case` returning the human-readable label (used in install logs and prompts).
5. **Edit `cli/src/utils/template.ts` `AI_TO_PLATFORM`**:
   - Add a mapping from the new `AIType` value to the platform JSON filename.
6. **Create `cli/assets/templates/platforms/<platform>.json`**:
   - Fill in every field of the `PlatformConfig` schema (see section 3).
   - For `frontmatter`, copy the closest existing platform's frontmatter and adjust per the platform's docs.
7. **Mirror the JSON to `src/ui-ux-pro-max/templates/platforms/<platform>.json`** (the dual-tree convention).
8. **Test locally**: `cd cli && bun run dev init --ai newtool`, then verify the rendered `.newtool/skills/ui-ux-pro-max/SKILL.md` matches the platform's expectations.
9. **Add a row to `skill.json`**'s `platforms` array.
10. **Build, version-bump, and release** per section 4.

> [!IMPORTANT]
> All five edits to TypeScript files are required. Forgetting `getAITypeDescription` produces a fallthrough to the default `case 'all'` label and confuses install logs. Forgetting `AI_TO_PLATFORM` produces `Unknown AI type: <foo>` from `template.ts:66`.

### Adding a new reference category

To add a new CSV (e.g. `data/animations.csv`):

1. Create the CSV under `cli/assets/data/animations.csv` with columns the search scripts can index (consult `scripts/core.py` for the load convention).
2. Mirror to `src/ui-ux-pro-max/data/animations.csv`.
3. If the new file has stack-specific entries, also create per-stack files under `data/stacks/<stack>-animations.csv` and mirror.
4. Run `_sync_all.py` to confirm both trees agree.
5. If `SKILL.md` should mention the new category by name (it usually doesn't — `search.py` fuzzy-matches by file), edit `cli/assets/templates/base/skill-content.md`.
6. No code change is needed to `cli/src/`; the CLI just copies the asset tree.

### Adding a new search script

1. Create `cli/assets/scripts/<name>.py` and mirror to `src/ui-ux-pro-max/scripts/<name>.py`.
2. Reuse `core.py`'s loader if reading CSVs.
3. Document the script's input/output contract in a comment block.
4. Update SKILL.md if the AI needs explicit guidance on when to invoke the new script.

> [!NOTE]
> The bundled Python scripts shouldn't depend on third-party packages — users won't have run `pip install` for the skill. Stick to the standard library.

### Build & test

```bash
cd cli
bun install
bun run dev init --ai claude   # local dry-run
bun run build                  # produces dist/index.js
```

The repo has no test suite shipped at v2.5.0. Verification is manual: run `bun run dev init --ai <each platform>` against a clean test directory and confirm the resulting tree matches expectations.

### Coding conventions

- **TypeScript strict-mode** (per `tsconfig.json`).
- **ESM only** (`"type": "module"` in `package.json`); imports use `.js` extensions even in `.ts` source per Node ESM rules.
- **`#!/usr/bin/env node`** shebang on the entry point.
- **`process.exit(1)`** for fatal errors after logging via `logger.error`.
- **No global state**; every command takes its options object and returns.
- **Custom error classes** for GitHub-related failures (`GitHubRateLimitError`, `GitHubDownloadError`) extend `Error` directly.

### Improvements & technical debt

- **Dual-asset-tree drift** is the highest-risk maintenance issue. Consider eliminating one tree entirely and adapting the npm publish to read from `src/ui-ux-pro-max/` directly, or vice versa.
- **No checksum verification** of the bundled assets at install time. A SHA-256 manifest baked into the package would catch tampered installs.
- **No automated tests** for the platform-config rendering logic. A snapshot test per platform JSON would catch frontmatter-rendering regressions like issue #204 before release.
- **Issue #267** ("Hard-coded `.claude/` paths and unknown `opencode.json` config keys, 89 warnings") points to portability gaps in how some platform JSONs reference `.claude/` paths even when installed for a different platform — worth a top-down audit of every `templates/platforms/*.json` for hard-coded folder references.
- **Issue #270** ("Is it support Figma mcp?") is a feature request for Figma MCP integration — would let the skill pull live design tokens from Figma rather than relying solely on bundled CSVs.

### Contributing guide

Pull requests should follow the dual-tree contract: any change to `cli/assets/...` requires the matching change to `src/ui-ux-pro-max/...` and vice versa. Run `_sync_all.py` before commit. Add a paragraph to the PR description specifying:

- Which platforms are affected
- Whether the change touches `SKILL.md` rendering (in which case existing users need to `--force` reinstall)
- Whether the change is purely additive (safe) or removes/renames something (breaking)

---

## 9. Integration Points

How the skill connects to other systems — both inbound (what calls it) and outbound (what it calls).

### Inbound integrations (who installs the skill)

| Caller | Mechanism | Notes |
|---|---|---|
| Human at a terminal | `npx uipro-cli init` | The dominant install path |
| CI / scripted setup | `npm install -g uipro-cli && uipro init --ai <type> --force` | Use `--force` to make idempotent |
| Dotfiles / dev-container provisioner | Same as scripted | Pin the version: `uipro-cli@2.5.0` |
| AI assistant itself | indirectly, via the user prompting "install ui-ux-pro-max" | The assistant runs the same `npx` invocation |

### Outbound integrations (what the CLI itself calls)

| System | Purpose | When |
|---|---|---|
| `api.github.com/repos/nextlevelbuilder/ui-ux-pro-max-skill/releases` | List/get releases | `versions`, `update`, and `--legacy init` |
| `api.github.com/.../releases/latest` | Get latest release | `update`, `--legacy init` |
| `github.com/.../archive/refs/tags/<tag>.zip` (auto-archive fallback) | Download release source | `--legacy init` when no uploaded ZIP asset exists |
| Local filesystem (`cwd` or `homedir`) | Write skill files | every `init` |
| `tmpdir()` (`os.tmpdir`) | Stage extraction | `--legacy init` |
| PowerShell (Windows) / `unzip` (Unix) | ZIP extraction | `--legacy init` |
| `xcopy` (Windows) / `cp -r` (Unix) | Folder copy fallback | when `fs.cp` fails |

### Outbound integrations (what the installed skill itself calls — by way of the AI agent)

| System | Purpose | Invoked by |
|---|---|---|
| Local Python 3 interpreter | Run `core.py`, `design_system.py`, `search.py` | The AI agent's tool-call surface |
| Local CSVs in `data/*.csv` | Read reference data | The Python scripts |

The skill itself does not make outbound network calls. All design intelligence is computed locally from bundled CSVs by Python scripts the AI invokes via its tool-call surface.

### MCP (Model Context Protocol) integrations

None at present. Issue #270 is open requesting Figma MCP support. If this lands, the integration point will be a new MCP server config in the per-platform JSON config (or an external config consumed by the agent).

### Compatible AI host configurations

| Host | Skill location after install | Skill discovery mechanism |
|---|---|---|
| Claude Code | `<root>/.claude/skills/ui-ux-pro-max/SKILL.md` | Claude Code skill loader |
| Cursor | `<root>/.cursor/skills/ui-ux-pro-max/...` (+ `.shared/`) | Cursor's prompt/rule loader |
| Windsurf | `<root>/.windsurf/skills/ui-ux-pro-max/...` (+ `.shared/`) | Windsurf's skill loader |
| GitHub Copilot | `<root>/.github/prompts/...` (per `getAITypeDescription`) | Copilot's `.github/prompts` convention |
| Kiro | `<root>/.kiro/steering/...` (per `getAITypeDescription`) | Kiro's steering-file convention |
| Codex | `<root>/.codex/skills/...` | Codex skill loader |
| RooCode | `<root>/.roo/skills/...` (+ `.shared/`) | RooCode skill loader |
| Qoder | `<root>/.qoder/skills/...` (+ `.shared/`) | Qoder skill loader |
| Gemini CLI | `<root>/.gemini/skills/...` (+ `.shared/`) | Gemini CLI skill loader |
| Trae | `<root>/.trae/skills/...` (+ `.shared/`) | Trae skill loader |
| OpenCode | `<root>/.opencode/skills/...` (+ `.shared/`) | OpenCode skill loader |
| Continue | `<root>/.continue/skills/...` | Continue's skill convention |
| CodeBuddy | `<root>/.codebuddy/skills/...` | CodeBuddy skill loader |
| Droid (Factory) | `<root>/.factory/skills/...` | Factory skill loader |
| KiloCode | `<root>/.kilocode/skills/...` (+ `.shared/`) | KiloCode skill loader |
| Warp | `<root>/.warp/skills/...` (+ `.shared/`) | Warp skill loader |
| Augment | `<root>/.augment/skills/...` (+ `.shared/`) | Augment skill loader |
| Antigravity | `<root>/.agents/skills/...` (+ `.shared/`) | Antigravity skill loader |

### Composition with other skill packs

The skill is purely additive — installing it alongside other skill packs (e.g. another design pack, a testing skill, or a security skill) is safe because it occupies its own `skills/ui-ux-pro-max/` subfolder under each platform root. The host AI's skill resolver will surface multiple skills based on prompt intent; UI/UX Pro Max activates only on design-related prompts.

> [!TIP]
> If you're shipping your own skill pack and want to follow this repo's conventions, the pattern worth copying is the platform-config JSON schema: declare per-platform deltas as JSON, render a shared template, ship one folder per platform. It scales linearly with new platforms and contains the per-platform complexity inside data, not code.

### External brand surfaces

| Surface | URL |
|---|---|
| Project homepage | `https://uupm.cc` |
| Repository | `https://github.com/nextlevelbuilder/ui-ux-pro-max-skill` |
| npm package | `https://www.npmjs.com/package/uipro-cli` |
| Releases | `https://github.com/nextlevelbuilder/ui-ux-pro-max-skill/releases` |

---

_Generated April 2026 from nextlevelbuilder/ui-ux-pro-max-skill at b7e3af8. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._