mobile-app-ux-auditor-skill 0.1.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,22 @@
+{
+  "name": "mobile-app-ux-auditor",
+  "description": "Mobile app UI/UX audit skill for Flutter, React Native, iOS, Android, accessibility, onboarding, navigation, forms, retention, and platform-native flow improvements.",
+  "version": "0.1.0",
+  "author": {
+    "name": "Ajnas"
+  },
+  "license": "MIT",
+  "keywords": [
+    "mobile",
+    "ui",
+    "ux",
+    "accessibility",
+    "flutter",
+    "react-native",
+    "ios",
+    "android"
+  ],
+  "skills": [
+    "./skills/mobile-app-ux-auditor"
+  ]
+}

package/.codex-plugin/plugin.json

@@ -0,0 +1,43 @@
+{
+  "name": "mobile-app-ux-auditor",
+  "version": "0.1.0",
+  "description": "Agent Skill for auditing and improving mobile app UI/UX flows across Flutter, React Native, iOS, and Android.",
+  "author": {
+    "name": "Ajnas",
+    "email": "ajnasnb@gmail.com",
+    "url": "https://github.com/AjnasNB"
+  },
+  "homepage": "https://github.com/AjnasNB/mobile-app-ux-auditor-skill",
+  "repository": "https://github.com/AjnasNB/mobile-app-ux-auditor-skill",
+  "license": "MIT",
+  "keywords": [
+    "ux",
+    "ui",
+    "mobile",
+    "accessibility",
+    "flutter",
+    "react-native",
+    "ios",
+    "android"
+  ],
+  "skills": "./skills",
+  "interface": {
+    "displayName": "Mobile App UX Auditor",
+    "shortDescription": "Audit mobile app UI/UX flows",
+    "longDescription": "Review and improve mobile app navigation, onboarding, accessibility, platform-native fit, forms, retention, and state handling across Flutter, React Native, iOS, and Android.",
+    "developerName": "Ajnas",
+    "category": "Development",
+    "capabilities": [
+      "Read",
+      "Write",
+      "Review"
+    ],
+    "websiteURL": "https://github.com/AjnasNB/mobile-app-ux-auditor-skill",
+    "defaultPrompt": [
+      "Audit this mobile app UX flow.",
+      "Improve this mobile onboarding.",
+      "Review mobile accessibility."
+    ],
+    "brandColor": "#2563EB"
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ajnas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,186 @@
+# Mobile App UX Auditor Skill
+
+A portable Agent Skill by Ajnas for auditing and improving mobile app UI/UX flows across Flutter, React Native, Swift/iOS, Kotlin, Java, Android Views, and Jetpack Compose.
+
+Use it when you want an AI coding agent to inspect a mobile app, map real user flows, find UX friction, and propose or implement improvements with evidence instead of generic "make it cleaner" advice.
+
+## What it helps with
+
+- Navigation, back/close behavior, tabs, drawers, deep links, and re-entry flows.
+- First launch, onboarding, sign-in, permissions, paywalls, subscriptions, and settings.
+- Forms, validation, keyboard behavior, autofill, empty/loading/error/offline states.
+- Accessibility: labels, roles, states, screen readers, focus order, touch targets, dynamic type, contrast, reduced motion.
+- Platform fit for iOS and Android, including adaptive layout for tablets, foldables, landscape, and safe areas.
+- Ethical retention through saved progress, useful reminders, trust, and repeated value.
+- Static code triage with a bundled Python scanner.
+
+## Install globally
+
+```bash
+npx mobile-app-ux-auditor-skill
+```
+
+The installer asks where to install:
+
+1. Global current user: Claude Code, Codex, and shared Agent Skills.
+2. Current project: local skills plus adapter files for popular coding agents.
+3. Both global and current project.
+4. Custom project path.
+
+Global install copies the skill for the current user into:
+
+- `~/.claude/skills/mobile-app-ux-auditor`
+- `~/.agents/skills/mobile-app-ux-auditor`
+- `~/.codex/skills/mobile-app-ux-auditor`
+
+Restart your agent app after installing.
+
+## Use it
+
+Claude Code:
+
+```text
+/mobile-app-ux-auditor
+```
+
+Codex:
+
+```text
+$mobile-app-ux-auditor
+```
+
+Example prompts:
+
+```text
+/mobile-app-ux-auditor audit the onboarding and permission flow in this React Native app
+```
+
+```text
+$mobile-app-ux-auditor review this Flutter checkout flow and fix the highest-impact UX issues
+```
+
+## Install into one project
+
+```bash
+npx mobile-app-ux-auditor-skill --project .
+```
+
+Project install copies the canonical skill into `.claude/skills/` and `.agents/skills/`, then writes adapter rule files for common coding agents:
+
+- Cursor
+- Windsurf
+- GitHub Copilot
+- Gemini
+- Continue
+- Cline
+- Roo Code
+- Kiro
+- Trae
+- OpenCode
+
+Copy only the skill folders and skip adapter files:
+
+```bash
+npx mobile-app-ux-auditor-skill --project . --no-adapters
+```
+
+Skip prompts and force global install:
+
+```bash
+npx mobile-app-ux-auditor-skill --yes
+```
+
+## Static scanner
+
+The skill includes a Python scanner for static mobile UX signals:
+
+```bash
+python scripts/mobile_ux_static_scan.py /path/to/mobile-app
+```
+
+The scanner detects review signals such as unlabeled custom controls, missing image labels, permission prompts, form-label risks, safe-area risks, and platform-specific accessibility gaps.
+
+It is a triage tool, not a replacement for expert review. Confirm every finding in code, simulator/device, screenshots, accessibility tooling, or tests before changing behavior.
+
+## Package layout
+
+```text
+mobile-app-ux-auditor/
+  SKILL.md
+  agents/openai.yaml
+  references/mobile-ux-audit-reference.md
+  scripts/mobile_ux_static_scan.py
+  skills/mobile-app-ux-auditor/
+  .codex-plugin/plugin.json
+  .claude-plugin/plugin.json
+  bin/install.js
+  package.json
+```
+
+The root `SKILL.md` supports direct skill installation. The `skills/mobile-app-ux-auditor/` copy supports plugin-style discovery.
+
+## Publish to GitHub
+
+```bash
+gh auth login
+gh repo create AjnasNB/mobile-app-ux-auditor-skill --public --source . --remote origin --push
+```
+
+If the repo already exists:
+
+```bash
+git remote add origin https://github.com/AjnasNB/mobile-app-ux-auditor-skill.git
+git push -u origin main
+```
+
+## Download from npm
+
+Install and run without keeping the package:
+
+```bash
+npx mobile-app-ux-auditor-skill
+```
+
+Install the CLI globally:
+
+```bash
+npm install -g mobile-app-ux-auditor-skill
+mobile-app-ux-auditor
+```
+
+## Publish to npm
+
+Log in once:
+
+```bash
+npm adduser
+```
+
+Check the package:
+
+```bash
+npm publish --dry-run --access public
+```
+
+Publish:
+
+```bash
+npm publish --access public
+```
+
+After publishing, users download and install it with:
+
+```bash
+npx mobile-app-ux-auditor-skill
+```
+
+Or install the CLI globally:
+
+```bash
+npm install -g mobile-app-ux-auditor-skill
+mobile-app-ux-auditor --global
+```
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: mobile-app-ux-auditor
+description: Use when reviewing, redesigning, or implementing mobile app UI/UX flows in Flutter, React Native, Swift, SwiftUI, UIKit, Kotlin, Jetpack Compose, Java, or Android Views; especially for navigation, onboarding, retention, accessibility, forms, engagement, screen hierarchy, or platform-native fit.
+---
+
+# Mobile App UX Auditor
+
+## Overview
+
+Audit mobile apps by mapping real user flows, finding friction with evidence, and proposing or implementing improvements that match iOS and Android platform expectations. Optimize for users reaching value quickly and returning willingly, not for manipulative time-on-device.
+
+## Workflow
+
+1. State the design read: app category, audience, job-to-be-done, target platforms, product maturity, visual register, and risk level. For redesigns, preserve working navigation, copy, analytics names, and accessibility wins unless there is evidence they cause harm.
+2. If code is available, run the static signal scan before judging:
+   ```bash
+   python scripts/mobile_ux_static_scan.py <project-root>
+   ```
+   In Claude Code, use `python ${CLAUDE_SKILL_DIR}/scripts/mobile_ux_static_scan.py <project-root>` when the skill is installed. Treat the script as evidence-gathering, not a replacement for expert review.
+3. Inspect routing, screens, design system files, navigation components, analytics events, accessibility props, platform-specific UI primitives, tests, and screenshots before recommending changes.
+4. Build a compact screen and flow map: first launch, onboarding, sign-in, home, primary task, search/discovery, settings, error states, empty states, permission requests, purchase/subscription, and re-entry flows.
+5. Audit flows against platform conventions, accessibility, clarity, effort, trust, feedback, performance, adaptive layout, and ethical retention. Load `references/mobile-ux-audit-reference.md` for the detailed checklist and framework-specific code signals.
+6. Rank issues by user impact:
+   - P0: Blocks core task, causes data loss, or creates severe accessibility failure.
+   - P1: Breaks navigation, trust, comprehension, or completion for many users.
+   - P2: Adds avoidable friction, inconsistency, or weak platform fit.
+   - P3: Polish, delight, or instrumentation improvement.
+7. When editing code, preserve the app's existing architecture and design system. Prefer native platform components and established navigation/accessibility APIs over custom controls unless the product has a clear reason.
+8. Verify with the best available evidence: emulator/simulator walkthrough, screenshots, accessibility scanner, VoiceOver/TalkBack, widget/UI tests, route tests, or static inspection. State any verification that could not be run.
+
+## Quality Bar
+
+Hold the output to a senior mobile product design engineer standard:
+
+- The primary user can understand where they are, what changed, what to do next, and how to recover from mistakes.
+- Core flows handle loading, empty, error, partial, disabled, offline, slow-network, auth-expired, permission-denied, interrupted, and resumed states.
+- The UI has one coherent design system: typography scale, spacing rhythm, radius rules, color roles, interaction states, motion, density, and platform adaptation.
+- Accessibility is built into labels, roles, states, focus order, target size, screen reader output, dynamic type/font scaling, contrast, and reduced-motion behavior.
+- Mobile performance is UX: launch time, route transitions, jank, unnecessary re-renders, heavy images, blocked gestures, keyboard latency, and battery cost all matter.
+- Retention comes from saved progress, useful reminders, reduced effort, trust, and repeated value. Do not optimize for addiction.
+
+## Output Format
+
+Start with findings, not praise. Include:
+
+- A prioritized findings table: severity, screen/flow, evidence, user impact, recommended fix.
+- A before/after flow summary when navigation or onboarding changes.
+- Framework-specific implementation notes for Flutter, React Native, Swift/iOS, or Android as applicable.
+- Static scan findings from `scripts/mobile_ux_static_scan.py` when code is available.
+- Accessibility and adaptive-layout checks.
+- Verification performed and remaining risks.
+
+When asked to improve the app directly, implement the smallest high-impact changes first, then report changed files and validation.
+
+## Non-Negotiables
+
+- Do not recommend "make users stay longer" tactics that rely on confusion, forced continuity, hidden exits, guilt, dark patterns, or notification spam.
+- Do not replace platform conventions with custom UI only for novelty.
+- Do not audit from static screenshots alone when code or an app build is available.
+- Do not give generic advice like "improve onboarding" without naming the exact screen, problem, and change.

package/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Mobile App UX Auditor"
+  short_description: "Audit and improve mobile app UI/UX flows"
+  default_prompt: "Use $mobile-app-ux-auditor to review this mobile app flow and propose practical UI/UX improvements."

package/bin/install.js

@@ -0,0 +1,255 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const readline = require("readline");
+
+const SKILL_NAME = "mobile-app-ux-auditor";
+const DISPLAY_NAME = "Mobile App UX Auditor";
+const DESCRIPTION =
+  "Audit and improve mobile app UI/UX flows across Flutter, React Native, iOS, and Android.";
+
+const PACKAGE_ROOT = path.resolve(__dirname, "..");
+const COPY_ENTRIES = ["SKILL.md", "agents", "references", "scripts"];
+
+function usage() {
+  console.log(`
+${DISPLAY_NAME}
+
+Usage:
+  npx mobile-app-ux-auditor-skill
+  mobile-app-ux-auditor --global
+  mobile-app-ux-auditor --project <path>
+  mobile-app-ux-auditor --targets claude,codex,agents
+
+Default:
+  In an interactive terminal, asks where to install. In non-interactive shells, installs globally.
+
+Options:
+  --global             Install to current-user global skill folders. Default when no mode is passed.
+  --project <path>     Install project-local skills and adapter rule files for popular coding agents.
+  --targets <list>     Comma-separated global targets: claude,codex,agents,codex-legacy.
+  --yes                Skip prompts and install globally.
+  --no-adapters        With --project, skip non-skill adapter files.
+  --print-paths        Print install locations and exit.
+  --help               Show this help.
+`);
+}
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function rmIfExists(target) {
+  if (fs.existsSync(target)) {
+    fs.rmSync(target, { recursive: true, force: true });
+  }
+}
+
+function copyEntry(entry, targetDir) {
+  const source = path.join(PACKAGE_ROOT, entry);
+  if (!fs.existsSync(source)) return;
+  const target = path.join(targetDir, entry);
+  rmIfExists(target);
+  fs.cpSync(source, target, { recursive: true });
+}
+
+function copySkillTo(root) {
+  const targetDir = path.join(root, SKILL_NAME);
+  ensureDir(targetDir);
+  for (const entry of COPY_ENTRIES) copyEntry(entry, targetDir);
+  return targetDir;
+}
+
+function globalTargets(selected) {
+  const home = os.homedir();
+  const all = {
+    claude: path.join(home, ".claude", "skills"),
+    agents: path.join(home, ".agents", "skills"),
+    codex: path.join(home, ".agents", "skills"),
+    "codex-legacy": path.join(home, ".codex", "skills")
+  };
+  const names = selected || ["claude", "agents", "codex-legacy"];
+  return [...new Set(names.map((name) => all[name]).filter(Boolean))];
+}
+
+function appendBlock(file, marker, body) {
+  ensureDir(path.dirname(file));
+  const existing = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+  if (existing.includes(marker)) return false;
+  const prefix = existing.trim().length ? `${existing.trimEnd()}\n\n` : "";
+  fs.writeFileSync(file, `${prefix}${body.trimEnd()}\n`, "utf8");
+  return true;
+}
+
+function writeFile(file, content) {
+  ensureDir(path.dirname(file));
+  fs.writeFileSync(file, content, "utf8");
+}
+
+function adapterText(skillPath) {
+  return `# ${DISPLAY_NAME}
+
+Use the ${SKILL_NAME} Agent Skill for mobile app UI/UX reviews, redesigns, navigation audits, onboarding, forms, accessibility, platform-native fit, retention, and flow improvements.
+
+Canonical skill path in this project: ${skillPath}
+
+Follow the skill workflow before recommending changes:
+- inspect code, screens, routes, navigation, forms, states, accessibility props, and runtime behavior;
+- run the bundled static scanner when code is available;
+- rank findings by user impact;
+- verify with simulator/device, screen reader, screenshots, tests, or static evidence.
+`;
+}
+
+function installProject(projectRoot, withAdapters) {
+  const root = path.resolve(projectRoot);
+  const claudeSkill = copySkillTo(path.join(root, ".claude", "skills"));
+  const agentsSkill = copySkillTo(path.join(root, ".agents", "skills"));
+
+  if (!withAdapters) return [claudeSkill, agentsSkill];
+
+  const marker = `<!-- ${SKILL_NAME}:start -->`;
+  const block = `${marker}
+${adapterText(`.agents/skills/${SKILL_NAME}/SKILL.md`)}
+<!-- ${SKILL_NAME}:end -->`;
+
+  writeFile(
+    path.join(root, ".cursor", "rules", `${SKILL_NAME}.mdc`),
+    `---
+description: ${DESCRIPTION}
+globs: **/*
+alwaysApply: false
+---
+
+${adapterText(`.agents/skills/${SKILL_NAME}/SKILL.md`)}`
+  );
+  writeFile(path.join(root, ".windsurf", "rules", `${SKILL_NAME}.md`), adapterText(`.agents/skills/${SKILL_NAME}/SKILL.md`));
+  writeFile(path.join(root, ".continue", "rules", `${SKILL_NAME}.md`), adapterText(`.agents/skills/${SKILL_NAME}/SKILL.md`));
+  writeFile(path.join(root, ".clinerules", `${SKILL_NAME}.md`), adapterText(`.agents/skills/${SKILL_NAME}/SKILL.md`));
+  writeFile(path.join(root, ".roo", "rules", `${SKILL_NAME}.md`), adapterText(`.agents/skills/${SKILL_NAME}/SKILL.md`));
+  writeFile(path.join(root, ".kiro", "steering", `${SKILL_NAME}.md`), adapterText(`.agents/skills/${SKILL_NAME}/SKILL.md`));
+  writeFile(path.join(root, ".trae", "rules", `${SKILL_NAME}.md`), adapterText(`.agents/skills/${SKILL_NAME}/SKILL.md`));
+  writeFile(path.join(root, ".opencode", "AGENTS.md"), adapterText(`.agents/skills/${SKILL_NAME}/SKILL.md`));
+
+  appendBlock(path.join(root, "AGENTS.md"), marker, block);
+  appendBlock(path.join(root, ".gemini", "GEMINI.md"), marker, block);
+  appendBlock(path.join(root, ".github", "copilot-instructions.md"), marker, block);
+
+  return [claudeSkill, agentsSkill];
+}
+
+function parseArgs(argv) {
+  const result = {
+    global: false,
+    project: null,
+    targets: null,
+    adapters: true,
+    printPaths: false,
+    help: false,
+    yes: false,
+    explicitMode: false
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--help" || arg === "-h") result.help = true;
+    else if (arg === "--global") {
+      result.global = true;
+      result.explicitMode = true;
+    }
+    else if (arg === "--project") {
+      result.project = argv[++i] || ".";
+      result.explicitMode = true;
+    }
+    else if (arg.startsWith("--project=")) {
+      result.project = arg.split("=")[1] || ".";
+      result.explicitMode = true;
+    }
+    else if (arg === "--targets") result.targets = (argv[++i] || "").split(",").map((s) => s.trim()).filter(Boolean);
+    else if (arg.startsWith("--targets=")) result.targets = arg.split("=")[1].split(",").map((s) => s.trim()).filter(Boolean);
+    else if (arg === "--no-adapters") result.adapters = false;
+    else if (arg === "--print-paths") result.printPaths = true;
+    else if (arg === "--yes" || arg === "-y") result.yes = true;
+  }
+  if (result.yes && !result.explicitMode) result.global = true;
+  if (!result.global && !result.project && !process.stdin.isTTY) result.global = true;
+  return result;
+}
+
+function ask(question) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+async function chooseInstallMode(args) {
+  if (args.global || args.project || args.printPaths || args.help) return args;
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    args.global = true;
+    return args;
+  }
+
+  console.log(`${DISPLAY_NAME}`);
+  console.log("");
+  console.log("Where should this skill be installed?");
+  console.log("1. Global current user: Claude Code, Codex, and shared Agent Skills");
+  console.log("2. Current project: .claude/.agents skills plus adapters for Cursor, Windsurf, Copilot, Gemini, Continue, Cline, Roo, Kiro, Trae, OpenCode");
+  console.log("3. Both global current user and current project");
+  console.log("4. Custom project path");
+  console.log("");
+
+  const choice = await ask("Choose 1, 2, 3, or 4 [1]: ");
+  const selected = choice || "1";
+  if (selected === "2") args.project = process.cwd();
+  else if (selected === "3") {
+    args.global = true;
+    args.project = process.cwd();
+  } else if (selected === "4") {
+    const customPath = await ask("Project path: ");
+    args.project = customPath || process.cwd();
+  } else {
+    args.global = true;
+  }
+  return args;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  await chooseInstallMode(args);
+  if (args.help) {
+    usage();
+    return;
+  }
+
+  if (args.printPaths) {
+    console.log(globalTargets(args.targets).join("\n"));
+    return;
+  }
+
+  const installed = [];
+  if (args.global) {
+    for (const target of globalTargets(args.targets)) {
+      installed.push(copySkillTo(target));
+    }
+  }
+  if (args.project) {
+    installed.push(...installProject(args.project, args.adapters));
+  }
+
+  console.log(`${DISPLAY_NAME} installed:`);
+  for (const target of installed) console.log(`- ${target}`);
+  console.log("");
+  console.log("Claude Code: invoke with /mobile-app-ux-auditor");
+  console.log("Codex: invoke with $mobile-app-ux-auditor or let Codex choose it automatically.");
+}
+
+main().catch((error) => {
+  console.error(error && error.stack ? error.stack : String(error));
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "mobile-app-ux-auditor-skill",
+  "version": "0.1.0",
+  "description": "Agent Skill for auditing and improving mobile app UI/UX flows across Flutter, React Native, iOS, and Android.",
+  "license": "MIT",
+  "author": {
+    "name": "Ajnas",
+    "email": "ajnasnb@gmail.com"
+  },
+  "type": "commonjs",
+  "bin": {
+    "mobile-app-ux-auditor": "bin/install.js",
+    "mobile-app-ux-auditor-skill": "bin/install.js"
+  },
+  "files": [
+    "SKILL.md",
+    "agents/",
+    "references/",
+    "scripts/",
+    "skills/",
+    "bin/",
+    ".codex-plugin/",
+    ".claude-plugin/",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "agent-skill",
+    "claude-code",
+    "codex",
+    "ux",
+    "ui",
+    "mobile",
+    "flutter",
+    "react-native",
+    "ios",
+    "android",
+    "accessibility"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AjnasNB/mobile-app-ux-auditor-skill.git"
+  },
+  "bugs": {
+    "url": "https://github.com/AjnasNB/mobile-app-ux-auditor-skill/issues"
+  },
+  "homepage": "https://github.com/AjnasNB/mobile-app-ux-auditor-skill#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=16"
+  }
+}