solanabr · sandman-sh · Jun 30, 2026
diff --git a/agent-ux-skill/LICENSE b/agent-ux-skill/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agent-ux-skill contributors
+
+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.
diff --git a/agent-ux-skill/README.md b/agent-ux-skill/README.md
@@ -0,0 +1,173 @@
+# 🧩 agent-ux-skill
+
+> **AI skill for the Solana AI Kit** — Analyze dApp transaction flows, generate UX optimization reports, and scaffold production-ready frontend components.
+
+[![Solana](https://img.shields.io/badge/Solana-2026_Stack-9945FF?style=flat-square&logo=solana)](https://solana.com)
+[![License](https://img.shields.io/badge/License-MIT-blue?style=flat-square)](./LICENSE)
+[![Skill Bounty](https://img.shields.io/badge/Superteam-Skill_Bounty-14F195?style=flat-square)](https://github.com/solanabr/skill-bounty)
+
+---
+
+## The Problem
+
+Web3 dApps lose **40–60% of users** at the transaction signing step due to:
+
+- 🔴 Wallet connection failures with no fallback UI
+- 🔴 Cryptic error messages (`"custom program error: 0x1194"`)
+- 🔴 No loading states during 10-second confirmation waits
+- 🔴 Requiring SOL for gas before users can do anything
+- 🔴 Missing retry logic on `BlockhashNotFound` errors
+
+Founders know their UX is bad, but lack the tooling to systematically identify
+and fix these issues.
+
+## The Solution
+
+**agent-ux-skill** is an AI skill that plugs into the
+[Solana AI Kit](https://github.com/solana-labs/solana-ai-kit) and gives your
+AI coding agent three superpowers:
+
+| Capability              | What it does                                                                 |
+|-------------------------|------------------------------------------------------------------------------|
+| **🔍 UX Audit**         | Analyzes your transaction flow against a 20+ point checklist and outputs a severity-ranked report. |
+| **🧱 Scaffold UI**      | Generates production-ready React/Vue components: wallet guards, transaction toasts, error boundaries, priority fee selectors. |
+| **⛽ Gasless Flow**      | Guides implementation of fee-payer architecture, Octane relays, or session keys so users never need SOL to transact. |
+
+---
+
+## Architecture
+
+This skill follows the **progressive loading** pattern — the AI agent only
+loads the specific instructions it needs, keeping token usage minimal:
+
+```
+skill/
+├── SKILL.md            ← Router (entry point — routes to sub-files)
+├── ux-audit.md         ← UX audit checklist & report template
+├── scaffold-ui.md      ← React/Vue component templates
+└── gasless-flow.md     ← Fee payer / relay / session key guides
+```
+
+The router (`SKILL.md`) evaluates the user's intent and loads **only the
+relevant file** — never all three at once.
+
+---
+
+## Installation
+
+### Option 1: Installer Script
+
+```bash
+# Clone this repo
+git clone https://github.com/your-username/agent-ux-skill.git
+cd agent-ux-skill
+
+# Set the path to your Solana AI Kit installation
+export SOLANA_AI_KIT_DIR="/path/to/solana-ai-kit"
+
+# Run the installer
+chmod +x install.sh
+./install.sh
+```
+
+### Option 2: Manual Copy
+
+```bash
+cp -r skill/ /path/to/solana-ai-kit/skills/agent-ux-skill/
+```
+
+### Option 3: Git Submodule
+
+```bash
+cd /path/to/solana-ai-kit
+git submodule add https://github.com/your-username/agent-ux-skill.git skills/agent-ux-skill
+```
+
+---
+
+## Usage
+
+Once installed, your AI agent will automatically detect the skill. Use natural
+language prompts:
+
+### UX Audit
+
+```
+"Audit the UX of my Solana dApp. My program ID is Fg6P...abc.
+Here's a recent transaction: 5Kx9...xyz"
+```
+
+The agent will analyze your transaction flow and produce a structured report
+with **Critical / Warning / Info** findings, each with a concrete fix.
+
+### Scaffold Components
+
+```
+"Scaffold wallet connection and transaction UI components for my
+Next.js app using React and CSS Modules."
+```
+
+The agent generates 5 production-ready components:
+- `WalletConnectionGuard` — conditional rendering based on wallet state
+- `TransactionToast` — real-time tx status feedback
+- `SendTransactionButton` — one-click send with simulation, retry, priority fees
+- `SolanaErrorBoundary` — catches and decodes Anchor/program errors
+- `PriorityFeeSelector` — user-facing tx speed picker (Slow / Standard / Fast)
+
+### Gasless Transactions
+
+```
+"Add gasless transactions to my dApp so users don't need SOL.
+I want a server-side fee payer approach."
+```
+
+The agent provides a complete server endpoint + client hook with rate limiting,
+security validation, and transaction co-signing.
+
+---
+
+## Tech Stack
+
+| Layer           | Technology                                                |
+|-----------------|-----------------------------------------------------------|
+| Solana SDK      | `@solana/web3.js` v2                                      |
+| Wallet Adapter  | `@solana/wallet-adapter-react` v0.15+                     |
+| React           | React 19 with `"use client"` directives                   |
+| Vue             | Vue 3.5+ Composition API (`<script setup lang="ts">`)     |
+| Transactions    | Versioned Transactions, Compute Budget, Address Lookup Tables |
+
+---
+
+## Submitting to the Skill Bounty
+
+This skill is designed for submission to the
+[Superteam Earn Skill Bounty](https://github.com/solanabr/skill-bounty).
+
+### Steps to Submit
+
+1. **Fork** the [skill-bounty repository](https://github.com/solanabr/skill-bounty).
+2. **Copy** the `skill/` directory into the fork under `skills/agent-ux-skill/`.
+3. **Add** this `README.md` to the root of your submission.
+4. **Open a Pull Request** with:
+   - Title: `[Skill Submission] agent-ux-skill`
+   - Description: Link to this README and a brief summary of the three capabilities.
+5. **Include a demo** — record a short video or GIF showing the agent
+   performing a UX audit or scaffolding components.
+
+---
+
+## Contributing
+
+Contributions are welcome. Key areas:
+
+- **New audit checks** — add to the checklist in `ux-audit.md`
+- **Framework support** — add Svelte/SolidJS component variants to `scaffold-ui.md`
+- **Relay integrations** — add new gasless relay providers to `gasless-flow.md`
+
+Please open an issue before submitting large changes.
+
+---
+
+## License
+
+MIT — see [LICENSE](./LICENSE) for details.
diff --git a/agent-ux-skill/install.sh b/agent-ux-skill/install.sh
@@ -0,0 +1,110 @@
+#!/usr/bin/env bash
+# ──────────────────────────────────────────────────────────────────
+#  agent-ux-skill installer
+#  Installs the skill into the Solana AI Kit's skills directory.
+# ──────────────────────────────────────────────────────────────────
+set -euo pipefail
+
+# ── Config ───────────────────────────────────────────────────────
+SKILL_NAME="agent-ux-skill"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SKILL_SOURCE="${SCRIPT_DIR}/skill"
+
+# Default install target — can be overridden via env var
+SOLANA_AI_KIT_DIR="${SOLANA_AI_KIT_DIR:-$(pwd)/solana-ai-kit}"
+SKILLS_DIR="${SOLANA_AI_KIT_DIR}/skills"
+TARGET_DIR="${SKILLS_DIR}/${SKILL_NAME}"
+
+# ── Colors ───────────────────────────────────────────────────────
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+RED='\033[0;31m'
+NC='\033[0m' # No Color
+
+info()  { echo -e "${GREEN}[✓]${NC} $*"; }
+warn()  { echo -e "${YELLOW}[!]${NC} $*"; }
+error() { echo -e "${RED}[✗]${NC} $*"; exit 1; }
+
+# ── Pre-flight checks ───────────────────────────────────────────
+echo ""
+echo "╔═══════════════════════════════════════════╗"
+echo "║   agent-ux-skill — Installer              ║"
+echo "╚═══════════════════════════════════════════╝"
+echo ""
+
+# Verify source skill directory exists
+if [ ! -d "${SKILL_SOURCE}" ]; then
+  error "Skill source directory not found at: ${SKILL_SOURCE}"
+fi
+
+# Verify SKILL.md exists
+if [ ! -f "${SKILL_SOURCE}/SKILL.md" ]; then
+  error "SKILL.md not found in ${SKILL_SOURCE}. Aborting."
+fi
+
+# Check if Solana AI Kit directory exists
+if [ ! -d "${SOLANA_AI_KIT_DIR}" ]; then
+  warn "Solana AI Kit directory not found at: ${SOLANA_AI_KIT_DIR}"
+  echo ""
+  echo "Options:"
+  echo "  1. Set SOLANA_AI_KIT_DIR env var to the correct path and re-run."
+  echo "  2. Clone the Solana AI Kit first:"
+  echo "     git clone https://github.com/solana-labs/solana-ai-kit.git"
+  echo ""
+  read -rp "Create ${SKILLS_DIR} now? [y/N] " confirm
+  if [[ "${confirm}" =~ ^[Yy]$ ]]; then
+    mkdir -p "${SKILLS_DIR}"
+    info "Created ${SKILLS_DIR}"
+  else
+    error "Cannot proceed without a target directory. Aborting."
+  fi
+fi
+
+# Create skills directory if it doesn't exist
+mkdir -p "${SKILLS_DIR}"
+
+# ── Install ──────────────────────────────────────────────────────
+
+# Check for existing installation
+if [ -d "${TARGET_DIR}" ]; then
+  warn "Existing installation found at ${TARGET_DIR}"
+  read -rp "Overwrite? [y/N] " overwrite
+  if [[ "${overwrite}" =~ ^[Yy]$ ]]; then
+    rm -rf "${TARGET_DIR}"
+    info "Removed existing installation"
+  else
+    error "Aborting to preserve existing installation."
+  fi
+fi
+
+# Copy skill files
+cp -r "${SKILL_SOURCE}" "${TARGET_DIR}"
+info "Copied skill files to ${TARGET_DIR}"
+
+# Verify installation
+EXPECTED_FILES=("SKILL.md" "ux-audit.md" "scaffold-ui.md" "gasless-flow.md")
+for file in "${EXPECTED_FILES[@]}"; do
+  if [ ! -f "${TARGET_DIR}/${file}" ]; then
+    error "Verification failed: ${file} missing from ${TARGET_DIR}"
+  fi
+done
+
+info "All skill files verified"
+
+# ── Summary ──────────────────────────────────────────────────────
+echo ""
+echo "╔═══════════════════════════════════════════╗"
+echo "║   Installation Complete                    ║"
+echo "╚═══════════════════════════════════════════╝"
+echo ""
+info "Skill installed at: ${TARGET_DIR}"
+echo ""
+echo "Files installed:"
+for file in "${EXPECTED_FILES[@]}"; do
+  echo "  • ${file}"
+done
+echo ""
+echo "Usage: Point your AI agent at the skills directory or reference"
+echo "the SKILL.md file directly. The skill will auto-route based on"
+echo "your prompt."
+echo ""
diff --git a/agent-ux-skill/skill/SKILL.md b/agent-ux-skill/skill/SKILL.md
@@ -0,0 +1,68 @@
+---
+name: agent-ux-skill
+description: >
+  Analyzes Solana dApp transaction flows and generates UX optimization reports.
+  Scaffolds production-ready React/Vue UI components for wallet connection,
+  gasless transactions, error boundaries, and optimal signing states.
+  Use when the user says "audit my dApp UX", "scaffold wallet UI",
+  "gasless transactions", "optimize Solana UX", "generate wallet adapter components",
+  "fee payer setup", or "transaction error handling".
+---
+
+# Agent UX Skill — Router
+
+You are the **Agent UX Skill** for the Solana AI Kit. Your job is to improve
+the end-user experience of Solana dApps by auditing transaction flows,
+scaffolding production-grade frontend components, and guiding gasless
+transaction architecture.
+
+**Do NOT read all sub-files at once.** Only load the file that matches the
+user's current intent. This keeps token usage minimal.
+
+---
+
+## Routing Table
+
+Evaluate the user's request and load **exactly one** of the following files:
+
+### 1 · UX Audit
+
+**Trigger phrases:** "audit my dApp", "analyze transactions", "UX report",
+"find UX issues", "transaction flow analysis", "review my Solana UX",
+"user friction", "drop-off analysis"
+
+→ Read [skill/ux-audit.md](./ux-audit.md) and follow its instructions.
+
+---
+
+### 2 · Scaffold UI Components
+
+**Trigger phrases:** "scaffold wallet UI", "generate React components",
+"Vue wallet adapter", "wallet connection component", "build sign-in flow",
+"create transaction modal", "UI components for Solana"
+
+→ Read [skill/scaffold-ui.md](./scaffold-ui.md) and follow its instructions.
+
+---
+
+### 3 · Gasless Transaction Flow
+
+**Trigger phrases:** "gasless transactions", "fee payer", "sponsor fees",
+"relay transactions", "abstract gas", "onboard web2 users",
+"no SOL for fees", "meta-transactions"
+
+→ Read [skill/gasless-flow.md](./gasless-flow.md) and follow its instructions.
+
+---
+
+## Combination Requests
+
+If the user's request spans multiple areas (e.g., "audit my dApp and then
+scaffold improved components"), load the files **sequentially** — complete the
+first workflow before loading the next.
+
+## Fallback
+
+If the request does not match any trigger above but is broadly related to
+Solana frontend or UX, load [skill/ux-audit.md](./ux-audit.md) as the
+default starting point and adapt from there.