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.

+----------------------------------------------------------+
|                  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

Technology stack

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:

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

Dependencies

Runtime dependencies (cli/package.json):

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

Dev dependencies (build only):

{
  "@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:

{
  "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.

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:

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:

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.

Eighteen platform config files

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:

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

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:

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:

{
  "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

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.

Logging

cli/src/utils/logger.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

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:

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

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

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)

Outbound integrations (what the CLI itself calls)

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

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

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