An AI skill that provides design intelligence for building professional UI/UX across multiple platforms.
Python ai-skillsantigravityclaudeclaude-codecodexcommand-linecopilotcursor-aihtml5kirolanding-pagemobile-uiqoderreacttailwindcsstraeui-designuikitwindsurf-ai
import { existsSync } from 'node:fs';
import { readFile, mkdir, writeFile, cp, access, readdir, lstat, rm } from 'node:fs/promises';
import { join, dirname } from 'node:path';
import { homedir } from 'node:os';
import { fileURLToPath } from 'node:url';
const __dirname = dirname(fileURLToPath(import.meta.url));
const ASSETS_CANDIDATES = [
// Bun bundle: dist/index.js
join(__dirname, '..', 'assets'),
// TypeScript fallback: dist/utils/template.js
join(__dirname, '..', '..', 'assets'),
];
const ASSETS_DIR = ASSETS_CANDIDATES.find(path => existsSync(path)) ?? ASSETS_CANDIDATES[0];
export interface PlatformConfig {
platform: string;
displayName: string;
installType: 'full' | 'reference';
folderStructure: {
root: string;
// Root used instead of `root` for --global installs, when the assistant
// reads personal skills from a different home folder (copilot: ~/.copilot).
globalRoot?: string;
skillPath: string;
filename: string;
dataPath?: string;
};
scriptPath: string;
frontmatter: Record<string, string> | null;
sections: {
quickReference: boolean;
};
title: string;
description: string;
skillOrWorkflow: string;
}
/**
* Layouts an earlier CLI version installed and the current layout replaces.
* Paths are relative to the install base (project or home directory).
*/
const LEGACY_LAYOUTS: Record<string, { skillFiles: string[]; skillsParents: string[] }> = {
// Copilot used a prompt file in .github/prompts/ before it loaded Agent Skills.
copilot: {
skillFiles: ['.github/prompts/ui-ux-pro-max.prompt.md'],
skillsParents: ['.github/prompts'],
},
};
// Map AIType to platform config file name
const AI_TO_PLATFORM: Record<string, string> = {
claude: 'claude',
cursor: 'cursor',
windsurf: 'windsurf',
antigravity: 'agent',
copilot: 'copilot',
kiro: 'kiro',
opencode: 'opencode',
roocode: 'roocode',
codex: 'codex',
qoder: 'qoder',
gemini: 'gemini',
trae: 'trae',
continue: 'continue',
codebuddy: 'codebuddy',
droid: 'droid',
kilocode: 'kilocode',
warp: 'warp',
augment: 'augment',
codewhale: 'codewhale',
zcode: 'zcode',
kimi: 'kimi',
amazonq: 'amazonq',
openclaw: 'openclaw',
universal: 'universal',
};
async function exists(path: string): Promise<boolean> {
try {
await access(path);
return true;
} catch {
return false;
}
}
/**
* Load platform configuration from JSON file
*/
export async function loadPlatformConfig(aiType: string): Promise<PlatformConfig> {
const platformName = AI_TO_PLATFORM[aiType];
if (!platformName) {
throw new Error(`Unknown AI type: ${aiType}`);
}
const configPath = join(ASSETS_DIR, 'templates', 'platforms', `${platformName}.json`);
const content = await readFile(configPath, 'utf-8');
return JSON.parse(content) as PlatformConfig;
}
/**
* The folder a platform installs into, relative to the project (local) or
* home directory (global).
*/
export function platformRoot(config: PlatformConfig, isGlobal: boolean): string {
return (isGlobal && config.folderStructure.globalRoot) || config.folderStructure.root;
}
/**
* Load all available platform configs
*/
export async function loadAllPlatformConfigs(): Promise<Map<string, PlatformConfig>> {
const configs = new Map<string, PlatformConfig>();
for (const [aiType, platformName] of Object.entries(AI_TO_PLATFORM)) {
try {
const config = await loadPlatformConfig(aiType);
configs.set(aiType, config);
} catch {
// Skip if config doesn't exist
}
}
return configs;
}
/**
* Load a template file
*/
async function loadTemplate(templateName: string): Promise<string> {
const templatePath = join(ASSETS_DIR, 'templates', templateName);
return readFile(templatePath, 'utf-8');
}
/**
* Render frontmatter section
*/
function renderFrontmatter(frontmatter: Record<string, string> | null): string {
if (!frontmatter) return '';
const lines = ['---'];
for (const [key, value] of Object.entries(frontmatter)) {
// Quote values that contain special characters
if (value.includes(':') || value.includes('"') || value.includes('\n')) {
lines.push(`${key}: "${value.replace(/"/g, '\\"')}"`);
} else {
lines.push(`${key}: ${value}`);
}
}
lines.push('---', '');
return lines.join('\n');
}
/**
* Resolve {{#QR}}...{{/QR}} / {{#NOQR}}...{{/NOQR}} pairs so platforms that
* omit the inlined Quick Reference do not tell the agent to read empty
* "sections above".
*/
function applyQuickReferenceVariants(content: string, includeQuickReference: boolean): string {
const drop = includeQuickReference
? /\{\{#NOQR\}\}[\s\S]*?\{\{\/NOQR\}\}/g
: /\{\{#QR\}\}[\s\S]*?\{\{\/QR\}\}/g;
const keep = includeQuickReference
? /\{\{#QR\}\}([\s\S]*?)\{\{\/QR\}\}/g
: /\{\{#NOQR\}\}([\s\S]*?)\{\{\/NOQR\}\}/g;
return content.replace(drop, '').replace(keep, '$1');
}
/**
* Render skill file content from template
* When isGlobal=true, rewrites script paths to use ~/{root}/ prefix
*/
export async function renderSkillFile(config: PlatformConfig, isGlobal = false): Promise<string> {
// Load base template
let content = await loadTemplate('base/skill-content.md');
content = applyQuickReferenceVariants(content, config.sections.quickReference);
// Load quick reference if needed
let quickReferenceContent = '';
if (config.sections.quickReference) {
quickReferenceContent = await loadTemplate('base/quick-reference.md');
}
// scriptPath is relative to the platform root. Generated commands run from
// the user's project root, so local installs need the platform root prefix;
// global installs need the same path anchored at the user's home directory.
const rootedScriptPath = `${platformRoot(config, isGlobal)}/${config.scriptPath}`
.replace(/\/{2,}/g, '/');
const commandScriptPath = isGlobal ? `~/${rootedScriptPath}` : rootedScriptPath;
// Build the final content
const frontmatter = renderFrontmatter(config.frontmatter);
// Replace placeholders
// Add newline before quick reference content if it exists
const quickRefWithNewline = quickReferenceContent ? '\n' + quickReferenceContent : '';
content = content
.replace(/\{\{TITLE\}\}/g, config.title)
.replace(/\{\{DESCRIPTION\}\}/g, config.description)
.replace(/\{\{SCRIPT_PATH\}\}/g, commandScriptPath)
.replace(/\{\{SKILL_OR_WORKFLOW\}\}/g, config.skillOrWorkflow)
.replace(/\{\{QUICK_REFERENCE\}\}/g, quickRefWithNewline);
return frontmatter + content;
}
/**
* Replace a pre-existing non-directory at `path` so a real directory can be
* created there. Older CLI installs (and Windows checkouts of the repo's
* symlinked data/scripts) can leave plain "pointer" files at these paths;
* mkdir then throws EEXIST and the install silently leaves stale files.
*/
async function ensureCleanDir(path: string): Promise<void> {
try {
const stat = await lstat(path);
if (!stat.isDirectory()) {
await rm(path, { recursive: true, force: true });
}
} catch {
// Nothing exists at the path yet — mkdir will create it.
}
}
/**
* Copy data and scripts to target directory
*/
async function copyDataAndScripts(targetSkillDir: string): Promise<void> {
const dataSource = join(ASSETS_DIR, 'data');
const scriptsSource = join(ASSETS_DIR, 'scripts');
const dataTarget = join(targetSkillDir, 'data');
const scriptsTarget = join(targetSkillDir, 'scripts');
// Copy data
if (await exists(dataSource)) {
await ensureCleanDir(dataTarget);
await mkdir(dataTarget, { recursive: true });
await cp(dataSource, dataTarget, { recursive: true });
}
// Copy scripts
if (await exists(scriptsSource)) {
await ensureCleanDir(scriptsTarget);
await mkdir(scriptsTarget, { recursive: true });
await cp(scriptsSource, scriptsTarget, { recursive: true });
}
}
/**
* List the static sub-skills bundled under assets/skills/ (everything except
* the template-rendered orchestrator). Empty if the package predates bundling.
*/
export async function listBundledSubSkills(): Promise<string[]> {
const skillsSource = join(ASSETS_DIR, 'skills');
if (!(await exists(skillsSource))) return [];
const entries = await readdir(skillsSource, { withFileTypes: true });
return entries.filter(e => e.isDirectory()).map(e => e.name).sort();
}
/**
* Paths of an earlier layout of aiType that exist under baseDir: the old skill
* file, the orchestrator folder and the bundled sub-skills left next to it.
* A sub-skill folder only counts when it holds a SKILL.md, so a user's own
* folder of the same name (e.g. `.github/prompts/design`) is left alone.
*/
export async function findLegacyInstallPaths(baseDir: string, aiType: string): Promise<string[]> {
const layout = LEGACY_LAYOUTS[aiType];
if (!layout) return [];
const found: string[] = [];
for (const skillFile of layout.skillFiles) {
if (await exists(join(baseDir, skillFile))) found.push(skillFile);
}
for (const parent of layout.skillsParents) {
const orchestratorDir = `${parent}/ui-ux-pro-max`;
if (await exists(join(baseDir, orchestratorDir))) found.push(orchestratorDir);
for (const name of await listBundledSubSkills()) {
const subSkillDir = `${parent}/${name}`;
if (await exists(join(baseDir, subSkillDir, 'SKILL.md'))) found.push(subSkillDir);
}
}
return found;
}
/**
* Remove an earlier layout of aiType from baseDir. Returns the removed paths.
*/
export async function removeLegacyInstall(baseDir: string, aiType: string): Promise<string[]> {
const found = await findLegacyInstallPaths(baseDir, aiType);
for (const path of found) {
await rm(join(baseDir, path), { recursive: true, force: true });
}
return found;
}
/**
* Install the bundled sub-skills as siblings of the orchestrator skill, so a
* single `uipro init` delivers all 7 skills instead of only ui-ux-pro-max.
*/
async function copySubSkills(skillsParentDir: string, force: boolean): Promise<void> {
const skillsSource = join(ASSETS_DIR, 'skills');
if (!(await exists(skillsSource))) return;
for (const name of await listBundledSubSkills()) {
const target = join(skillsParentDir, name);
if (await exists(target) && !force) continue;
await mkdir(target, { recursive: true });
await cp(join(skillsSource, name), target, { recursive: true });
}
}
/**
* Resolve every path an install touches for one platform. Shared by the real
* install (generatePlatformFiles) and the read-only preview
* (planPlatformInstallActions) so the two can never disagree.
*/
function resolveInstallPaths(
config: PlatformConfig,
targetDir: string,
isGlobal: boolean
): {
baseDir: string;
skillDir: string;
skillFilePath: string;
dataDir: string;
skillsParentDir: string;
} {
// For global install, target the user's home directory
const effectiveDir = isGlobal ? homedir() : targetDir;
const root = platformRoot(config, isGlobal);
// Determine full skill directory path
const skillDir = join(
effectiveDir,
root,
config.folderStructure.skillPath
);
const skillFilePath = join(skillDir, config.folderStructure.filename);
// Copy data and scripts into the data directory (may differ from skill file location)
const dataDir = config.folderStructure.dataPath
? join(effectiveDir, root, config.folderStructure.dataPath)
: skillDir;
// The skills parent is the orchestrator's parent dir (skills/ for most
// platforms, steering/ for kiro) — derived, not hardcoded. For platforms
// with a separate dataPath (amazonq), the orchestrator's data dir is the
// anchor.
const skillsParentDir = join(
effectiveDir,
root,
config.folderStructure.dataPath
? dirname(config.folderStructure.dataPath)
: dirname(config.folderStructure.skillPath)
);
return { baseDir: effectiveDir, skillDir, skillFilePath, dataDir, skillsParentDir };
}
/**
* Generate platform files for a specific AI type
* All platforms use self-contained installation with data and scripts
* When isGlobal=true, installs to ~/home directory with absolute script paths
*/
export async function generatePlatformFiles(
targetDir: string,
aiType: string,
isGlobal = false,
force = false
): Promise<string[]> {
const config = await loadPlatformConfig(aiType);
const createdFolders: string[] = [];
const { baseDir, skillDir, skillFilePath, dataDir, skillsParentDir } = resolveInstallPaths(
config,
targetDir,
isGlobal
);
// Create directory structure
await mkdir(skillDir, { recursive: true });
// Render and write skill file (pass isGlobal to adjust paths)
const skillContent = await renderSkillFile(config, isGlobal);
const fileAlreadyExists = await exists(skillFilePath);
if (fileAlreadyExists && !force) {
console.log(` Skipped (already exists): ${skillFilePath} — use --force to overwrite`);
return [];
}
await writeFile(skillFilePath, skillContent, 'utf-8');
createdFolders.push(platformRoot(config, isGlobal));
await mkdir(dataDir, { recursive: true });
await copyDataAndScripts(dataDir);
// Install the sibling sub-skills (banner-design, brand, design, ...) next to
// the orchestrator so all 7 skills are delivered.
await copySubSkills(skillsParentDir, force);
// The new layout replaces an earlier one (copilot's .github/prompts/ install).
for (const path of await removeLegacyInstall(baseDir, aiType)) {
console.log(` Removed legacy install: ${join(baseDir, path)}`);
}
return createdFolders;
}
/**
* Preview the actions generatePlatformFiles would take for one AI type,
* without writing anything. Used by `uipro init --dry-run`.
*/
export async function planPlatformInstallActions(
targetDir: string,
aiType: string,
isGlobal = false,
force = false
): Promise<string[]> {
const config = await loadPlatformConfig(aiType);
const { baseDir, skillFilePath, dataDir, skillsParentDir } = resolveInstallPaths(config, targetDir, isGlobal);
const actions: string[] = [];
const skillFileExists = await exists(skillFilePath);
actions.push(
skillFileExists && !force
? `Would skip (exists, use --force): ${skillFilePath}`
: `Would write: ${skillFilePath}`
);
actions.push(`Would copy data + scripts: ${dataDir}`);
const subSkills = await listBundledSubSkills();
if (subSkills.length > 0) {
actions.push(
`Would copy ${subSkills.length} sub-skills (${subSkills.join(', ')}): ${skillsParentDir}`
);
}
if (!skillFileExists || force) {
for (const path of await findLegacyInstallPaths(baseDir, aiType)) {
actions.push(`Would remove legacy install: ${join(baseDir, path)}`);
}
}
return actions;
}
/**
* Preview the actions generateAllPlatformFiles would take, grouped per unique
* platform layout, without writing anything. Used by `uipro init --dry-run`.
*/
export async function planAllPlatformInstallActions(
targetDir: string,
isGlobal = false,
force = false
): Promise<Map<string, string[]>> {
const planned = new Map<string, string[]>();
const generatedSkillFiles = new Set<string>();
for (const aiType of Object.keys(AI_TO_PLATFORM)) {
try {
const config = await loadPlatformConfig(aiType);
const skillFile = join(
config.folderStructure.root,
config.folderStructure.skillPath,
config.folderStructure.filename
);
if (generatedSkillFiles.has(skillFile)) continue;
generatedSkillFiles.add(skillFile);
planned.set(aiType, await planPlatformInstallActions(targetDir, aiType, isGlobal, force));
} catch {
// Skip if config doesn't exist
}
}
return planned;
}
/**
* Generate files for all AI types
*/
export async function generateAllPlatformFiles(targetDir: string, isGlobal = false, force = false): Promise<string[]> {
const allFolders = new Set<string>();
const generatedSkillFiles = new Set<string>();
for (const aiType of Object.keys(AI_TO_PLATFORM)) {
try {
const config = await loadPlatformConfig(aiType);
const skillFile = join(
config.folderStructure.root,
config.folderStructure.skillPath,
config.folderStructure.filename
);
if (generatedSkillFiles.has(skillFile)) continue;
const folders = await generatePlatformFiles(targetDir, aiType, isGlobal, force);
generatedSkillFiles.add(skillFile);
folders.forEach(f => allFolders.add(f));
} catch {
// Skip if generation fails for a platform
}
}
return Array.from(allFolders);
}
/**
* Get list of supported AI types
*/
export function getSupportedAITypes(): string[] {
return Object.keys(AI_TO_PLATFORM);
}