Initial commit

.github/workflows/spellcheck.yml

@@ -0,0 +1,24 @@
+name: Spellcheck
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+    paths:
+      - "**/*.md"
+      - ".github/workflows/spellcheck.yml"
+
+jobs:
+  spellcheck:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Check Markdown spelling
+        uses: streetsidesoftware/cspell-action@v6
+        with:
+          config: cspell.json
+          files: "**/*.md"

AGENTS.md

@@ -0,0 +1,24 @@
+# AGENTS.md
+
+## Purpose
+
+This repository packages the `building-good-ux` skill for multiple agent ecosystems.
+Treat the root files as the canonical project guidance:
+
+- `Intent.md` is the behavior spec for the skill.
+- `README.md` explains the repo layout at a high level.
+- `cspell.json` defines the spellcheck vocabulary used by CI.
+
+## Working Rules
+
+- Read `Intent.md` and `README.md` before making repo-wide changes.
+- Keep the three package folders aligned when a shared description changes.
+- Keep prose concise and consistent across `codex/`, `claude/`, and `openclaw/`.
+- When adding new markdown wording or project terms, update `cspell.json` if CI should accept them.
+- Preserve intentional misspellings only when they are part of a test or a deliberate example.
+- Prefer `apply_patch` for edits and keep changes minimal.
+
+## Validation
+
+- Markdown files are checked in CI with `cspell`.
+- Make sure new or edited `.md` files pass spellcheck before you consider the work done.

Intent.md

@@ -0,0 +1,153 @@
+# Intent
+
+## Purpose
+
+This skill helps an agent design, review, and implement better UX for product flows, screens, and components.
+
+It is inspired by the "Building Good UX" series by [synsation](https://www.instagram.com/synsation_).
+
+The skill should behave like a practical UX copilot:
+
+- spot friction before users do,
+- design beyond the happy path,
+- turn vague UX advice into concrete interface changes,
+- and keep the product usable when data is slow, missing, or broken.
+
+## What It Should Do
+
+When the user asks for UX help, the skill should:
+
+- identify the user's main goal and the critical path through the interface,
+- audit loading, success, empty, error, and partial states,
+- recommend patterns that reduce uncertainty and cognitive load,
+- suggest clearer copy, feedback, and recovery paths,
+- and connect UX advice to concrete product and implementation choices.
+
+## Core Questions
+
+The skill exists to answer:
+
+- What is the user trying to do?
+- Where might they hesitate, get stuck, or lose trust?
+- What should the interface show while it is waiting, empty, or failing?
+- How can the flow recover gracefully instead of collapsing?
+- What changes would make the product feel faster, clearer, and more forgiving?
+
+## Operating Model
+
+The UX pass should happen in 5 steps.
+
+### Step 1: Define the task and the risk
+
+Identify:
+
+- the user's primary goal,
+- the important actions and dependencies,
+- the moments where feedback matters,
+- and the highest-friction points in the current flow.
+
+### Step 2: Map the state coverage
+
+For each important step, account for:
+
+- success,
+- loading,
+- empty,
+- error,
+- and partial states.
+
+Look specifically for:
+
+- silent failures,
+- blank screens with no explanation,
+- disabled actions with no clue why,
+- and full-page blockers caused by one slow or broken dependency.
+
+### Step 3: Improve the interaction patterns
+
+#### Loading and feedback
+
+- Use skeletons for whole pages or large sections where layout matters first.
+- Use progress bars for measurable waits like uploads, imports, and installs.
+- Use inline spinners for small localized actions.
+- Use optimistic UI for fast reversible actions that should feel instant.
+- Avoid flashing loaders for work that finishes in under a second.
+- Add meaningful progress text for longer waits.
+- Replace long looping spinners with progress bars or step indicators when waits stretch past roughly ten seconds.
+
+#### Errors and recovery
+
+- Explain what happened, why it happened when known, and what the user can do next.
+- Never expose raw backend or database errors directly to the user.
+- Prefer inline errors near the failed action when recovery is local.
+- Use toasts for low-severity or transient status.
+- Use modals only when the user is blocked and must make a decision before continuing.
+
+#### Forms and inputs
+
+- Validate inline so the user can fix issues immediately.
+- Explain disabled submit states instead of leaving users guessing.
+- Show limits, formatting expectations, and password requirements before submission fails.
+- Prefill known information when possible.
+- Preserve user input and accept forgiving formatting when the backend can normalize it safely.
+
+#### Empty, success, and partial states
+
+- Explain why an area is empty and what the user should do next.
+- Turn first-use empty states into guided starting points.
+- Treat reward-style empty states, like inbox zero, as a positive moment.
+- Let sections load and fail independently instead of blocking the whole page.
+- Give broken sections local retry paths while keeping the rest of the interface usable.
+- Use cached or stale content strategically when it helps the product stay useful.
+
+### Step 4: Ground the advice in real patterns
+
+Use concrete examples from real products when they help clarify the recommendation, such as:
+
+- feed skeletons on content-heavy apps,
+- progress bars for file uploads and installs,
+- optimistic likes or saves,
+- helpful first-use dashboard empty states,
+- and section-level loading and retry behavior on dashboards and feeds.
+
+Do not force brand-name examples when a generic explanation is clearer.
+
+### Step 5: Deliver a prioritized recommendation
+
+The final response should:
+
+- diagnose the biggest UX risks first,
+- recommend the highest-impact fixes in priority order,
+- cover the relevant interface states,
+- include concrete copy or behavior suggestions when useful,
+- and mention implementation notes when the user is actively building the interface.
+
+## Output Format
+
+The final response should be concise and actionable.
+
+It should usually include:
+
+- brief diagnosis,
+- prioritized fixes,
+- state coverage notes,
+- suggested UX copy or interaction changes,
+- and implementation guidance when relevant.
+
+## Behavioral Rules
+
+- Optimize for clarity, trust, recovery, and forward momentum.
+- Prefer concrete product guidance over abstract design jargon.
+- Design for the messy middle, not just the happy path.
+- Distinguish critical blockers from minor friction.
+- Keep recommendations realistic for the product context.
+- Say plainly when a design is attractive but confusing, fragile, or incomplete.
+
+## Success Criteria
+
+The skill is successful if it can:
+
+- catch missing states before users do,
+- reduce confusion and abandonment,
+- improve recovery when things go wrong,
+- and help another agent turn rough interfaces into dependable experiences.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 space
+
+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.

README.md

@@ -0,0 +1,45 @@
+# Building Good UX Skill
+
+This repository packages the same `building-good-ux` skill for three different agent ecosystems.
+
+It repurposes the existing multi-harness packaging into a reusable UX skill grounded in:
+
+- general UX best practices,
+- and real-world product patterns.
+
+It is inspired by the "Building Good UX" series by [synsation](https://www.instagram.com/synsation_).
+
+## Contents
+
+- `Intent.md`: the canonical behavior spec for the skill
+- `codex/building-good-ux`: Codex-formatted package
+- `claude/building-good-ux`: Claude Code-formatted package
+- `openclaw/building-good-ux`: OpenClaw-formatted package
+- `copy-script/`: Python installer and its README
+
+## What The Skill Does
+
+`building-good-ux` helps an agent improve product experience quality instead of focusing only on the happy path.
+
+It is designed to help with:
+
+- loading, empty, error, partial, and success states,
+- form friction and inline validation,
+- error copy and error placement,
+- graceful degradation and local recovery,
+- and practical UX recommendations tied to real interface behavior.
+
+## Repo Layout
+
+- `Intent.md` is the source of truth for shared skill behavior
+- each package folder contains an installable `SKILL.md` and a short ecosystem README
+- `copy-script/README.md` explains how to install the packaged skill folders
+- CI spellchecks Markdown with the project dictionary from `cspell.json`
+
+## Installation
+
+Run the Python installer in `copy-script/` to copy the package folders into the matching skills directories under your home folder.
+
+## License
+
+This repository is licensed under the MIT License. See [LICENSE](LICENSE).

claude/building-good-ux/README.md

@@ -0,0 +1,14 @@
+# Claude Package
+
+This folder contains the Claude Code version of `building-good-ux`.
+
+## Packaging notes
+
+- The package mirrors the shared skill behavior from the repo root.
+- `SKILL.md` is the installable artifact copied into the target skills directory.
+- Keeping the wording aligned with the other harness folders makes cross-ecosystem maintenance simpler.
+
+## Source
+
+- `Intent.md` in the repo root
+- shared repository packaging conventions

claude/building-good-ux/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: building-good-ux
+description: Improve product and interface UX by reviewing or designing flows, screens, components, forms, and async states. Use when Codex needs to critique, redesign, or implement better loading, empty, error, partial, or success states, reduce form friction, choose feedback patterns, or make AI-generated UI less happy-path-only and more trustworthy.
+---
+
+# Intent
+
+## Purpose
+
+This skill helps an agent design, review, and implement better UX for product flows, screens, and components.
+
+It is inspired by the "Building Good UX" series by [synsation](https://www.instagram.com/synsation_).
+
+The skill should behave like a practical UX copilot:
+
+- spot friction before users do,
+- design beyond the happy path,
+- turn vague UX advice into concrete interface changes,
+- and keep the product usable when data is slow, missing, or broken.
+
+## What It Should Do
+
+When the user asks for UX help, the skill should:
+
+- identify the user's main goal and the critical path through the interface,
+- audit loading, success, empty, error, and partial states,
+- recommend patterns that reduce uncertainty and cognitive load,
+- suggest clearer copy, feedback, and recovery paths,
+- and connect UX advice to concrete product and implementation choices.
+
+## Core Questions
+
+The skill exists to answer:
+
+- What is the user trying to do?
+- Where might they hesitate, get stuck, or lose trust?
+- What should the interface show while it is waiting, empty, or failing?
+- How can the flow recover gracefully instead of collapsing?
+- What changes would make the product feel faster, clearer, and more forgiving?
+
+## Operating Model
+
+The UX pass should happen in 5 steps.
+
+### Step 1: Define the task and the risk
+
+Identify:
+
+- the user's primary goal,
+- the important actions and dependencies,
+- the moments where feedback matters,
+- and the highest-friction points in the current flow.
+
+### Step 2: Map the state coverage
+
+For each important step, account for:
+
+- success,
+- loading,
+- empty,
+- error,
+- and partial states.
+
+Look specifically for:
+
+- silent failures,
+- blank screens with no explanation,
+- disabled actions with no clue why,
+- and full-page blockers caused by one slow or broken dependency.
+
+### Step 3: Improve the interaction patterns
+
+#### Loading and feedback
+
+- Use skeletons for whole pages or large sections where layout matters first.
+- Use progress bars for measurable waits like uploads, imports, and installs.
+- Use inline spinners for small localized actions.
+- Use optimistic UI for fast reversible actions that should feel instant.
+- Avoid flashing loaders for work that finishes in under a second.
+- Add meaningful progress text for longer waits.
+- Replace long looping spinners with progress bars or step indicators when waits stretch past roughly ten seconds.
+
+#### Errors and recovery
+
+- Explain what happened, why it happened when known, and what the user can do next.
+- Never expose raw backend or database errors directly to the user.
+- Prefer inline errors near the failed action when recovery is local.
+- Use toasts for low-severity or transient status.
+- Use modals only when the user is blocked and must make a decision before continuing.
+
+#### Forms and inputs
+
+- Validate inline so the user can fix issues immediately.
+- Explain disabled submit states instead of leaving users guessing.
+- Show limits, formatting expectations, and password requirements before submission fails.
+- Prefill known information when possible.
+- Preserve user input and accept forgiving formatting when the backend can normalize it safely.
+
+#### Empty, success, and partial states
+
+- Explain why an area is empty and what the user should do next.
+- Turn first-use empty states into guided starting points.
+- Treat reward-style empty states, like inbox zero, as a positive moment.
+- Let sections load and fail independently instead of blocking the whole page.
+- Give broken sections local retry paths while keeping the rest of the interface usable.
+- Use cached or stale content strategically when it helps the product stay useful.
+
+### Step 4: Ground the advice in real patterns
+
+Use concrete examples from real products when they help clarify the recommendation, such as:
+
+- feed skeletons on content-heavy apps,
+- progress bars for file uploads and installs,
+- optimistic likes or saves,
+- helpful first-use dashboard empty states,
+- and section-level loading and retry behavior on dashboards and feeds.
+
+Do not force brand-name examples when a generic explanation is clearer.
+
+### Step 5: Deliver a prioritized recommendation
+
+The final response should:
+
+- diagnose the biggest UX risks first,
+- recommend the highest-impact fixes in priority order,
+- cover the relevant interface states,
+- include concrete copy or behavior suggestions when useful,
+- and mention implementation notes when the user is actively building the interface.
+
+## Output Format
+
+The final response should be concise and actionable.
+
+It should usually include:
+
+- brief diagnosis,
+- prioritized fixes,
+- state coverage notes,
+- suggested UX copy or interaction changes,
+- and implementation guidance when relevant.
+
+## Behavioral Rules
+
+- Optimize for clarity, trust, recovery, and forward momentum.
+- Prefer concrete product guidance over abstract design jargon.
+- Design for the messy middle, not just the happy path.
+- Distinguish critical blockers from minor friction.
+- Keep recommendations realistic for the product context.
+- Say plainly when a design is attractive but confusing, fragile, or incomplete.
+
+## Success Criteria
+
+The skill is successful if it can:
+
+- catch missing states before users do,
+- reduce confusion and abandonment,
+- improve recovery when things go wrong,
+- and help another agent turn rough interfaces into dependable experiences.

codex/building-good-ux/README.md

@@ -0,0 +1,14 @@
+# Codex Package
+
+This folder contains the Codex version of `building-good-ux`.
+
+## Packaging notes
+
+- Codex skills are folder-based and use `SKILL.md` as the trigger and instruction file.
+- `name` and `description` in YAML frontmatter are the important discovery fields.
+- The body stays procedural so another Codex instance can reuse it quickly.
+
+## Source
+
+- `Intent.md` in the repo root
+- Codex skill format guidance

codex/building-good-ux/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: building-good-ux
+description: Improve product and interface UX by reviewing or designing flows, screens, components, forms, and async states. Use when Codex needs to critique, redesign, or implement better loading, empty, error, partial, or success states, reduce form friction, choose feedback patterns, or make AI-generated UI less happy-path-only and more trustworthy.
+---
+
+# Intent
+
+## Purpose
+
+This skill helps an agent design, review, and implement better UX for product flows, screens, and components.
+
+It is inspired by the "Building Good UX" series by [synsation](https://www.instagram.com/synsation_).
+
+The skill should behave like a practical UX copilot:
+
+- spot friction before users do,
+- design beyond the happy path,
+- turn vague UX advice into concrete interface changes,
+- and keep the product usable when data is slow, missing, or broken.
+
+## What It Should Do
+
+When the user asks for UX help, the skill should:
+
+- identify the user's main goal and the critical path through the interface,
+- audit loading, success, empty, error, and partial states,
+- recommend patterns that reduce uncertainty and cognitive load,
+- suggest clearer copy, feedback, and recovery paths,
+- and connect UX advice to concrete product and implementation choices.
+
+## Core Questions
+
+The skill exists to answer:
+
+- What is the user trying to do?
+- Where might they hesitate, get stuck, or lose trust?
+- What should the interface show while it is waiting, empty, or failing?
+- How can the flow recover gracefully instead of collapsing?
+- What changes would make the product feel faster, clearer, and more forgiving?
+
+## Operating Model
+
+The UX pass should happen in 5 steps.
+
+### Step 1: Define the task and the risk
+
+Identify:
+
+- the user's primary goal,
+- the important actions and dependencies,
+- the moments where feedback matters,
+- and the highest-friction points in the current flow.
+
+### Step 2: Map the state coverage
+
+For each important step, account for:
+
+- success,
+- loading,
+- empty,
+- error,
+- and partial states.
+
+Look specifically for:
+
+- silent failures,
+- blank screens with no explanation,
+- disabled actions with no clue why,
+- and full-page blockers caused by one slow or broken dependency.
+
+### Step 3: Improve the interaction patterns
+
+#### Loading and feedback
+
+- Use skeletons for whole pages or large sections where layout matters first.
+- Use progress bars for measurable waits like uploads, imports, and installs.
+- Use inline spinners for small localized actions.
+- Use optimistic UI for fast reversible actions that should feel instant.
+- Avoid flashing loaders for work that finishes in under a second.
+- Add meaningful progress text for longer waits.
+- Replace long looping spinners with progress bars or step indicators when waits stretch past roughly ten seconds.
+
+#### Errors and recovery
+
+- Explain what happened, why it happened when known, and what the user can do next.
+- Never expose raw backend or database errors directly to the user.
+- Prefer inline errors near the failed action when recovery is local.
+- Use toasts for low-severity or transient status.
+- Use modals only when the user is blocked and must make a decision before continuing.
+
+#### Forms and inputs
+
+- Validate inline so the user can fix issues immediately.
+- Explain disabled submit states instead of leaving users guessing.
+- Show limits, formatting expectations, and password requirements before submission fails.
+- Prefill known information when possible.
+- Preserve user input and accept forgiving formatting when the backend can normalize it safely.
+
+#### Empty, success, and partial states
+
+- Explain why an area is empty and what the user should do next.
+- Turn first-use empty states into guided starting points.
+- Treat reward-style empty states, like inbox zero, as a positive moment.
+- Let sections load and fail independently instead of blocking the whole page.
+- Give broken sections local retry paths while keeping the rest of the interface usable.
+- Use cached or stale content strategically when it helps the product stay useful.
+
+### Step 4: Ground the advice in real patterns
+
+Use concrete examples from real products when they help clarify the recommendation, such as:
+
+- feed skeletons on content-heavy apps,
+- progress bars for file uploads and installs,
+- optimistic likes or saves,
+- helpful first-use dashboard empty states,
+- and section-level loading and retry behavior on dashboards and feeds.
+
+Do not force brand-name examples when a generic explanation is clearer.
+
+### Step 5: Deliver a prioritized recommendation
+
+The final response should:
+
+- diagnose the biggest UX risks first,
+- recommend the highest-impact fixes in priority order,
+- cover the relevant interface states,
+- include concrete copy or behavior suggestions when useful,
+- and mention implementation notes when the user is actively building the interface.
+
+## Output Format
+
+The final response should be concise and actionable.
+
+It should usually include:
+
+- brief diagnosis,
+- prioritized fixes,
+- state coverage notes,
+- suggested UX copy or interaction changes,
+- and implementation guidance when relevant.
+
+## Behavioral Rules
+
+- Optimize for clarity, trust, recovery, and forward momentum.
+- Prefer concrete product guidance over abstract design jargon.
+- Design for the messy middle, not just the happy path.
+- Distinguish critical blockers from minor friction.
+- Keep recommendations realistic for the product context.
+- Say plainly when a design is attractive but confusing, fragile, or incomplete.
+
+## Success Criteria
+
+The skill is successful if it can:
+
+- catch missing states before users do,
+- reduce confusion and abandonment,
+- improve recovery when things go wrong,
+- and help another agent turn rough interfaces into dependable experiences.

copy-script/README.md

@@ -0,0 +1,43 @@
+# Copy Script
+
+This folder contains the Python installer for the `building-good-ux` skill packages.
+
+## What It Does
+
+The script copies each ecosystem package into the matching skills directory in your home folder:
+
+- `codex/building-good-ux` -> `~/.codex/skills/building-good-ux`
+- `claude/building-good-ux` -> `~/.claude/skills/building-good-ux`
+- `openclaw/building-good-ux` -> `~/.openclaw/skills/building-good-ux`
+
+## Interactive Mode
+
+Run the script with no flags in a terminal to pick ecosystems interactively.
+
+It will:
+
+- show the available ecosystems,
+- let you choose one or more,
+- and ask before overwriting existing installs.
+
+## CLI Mode
+
+Use flags when you want a non-interactive run.
+
+Examples:
+
+```bash
+python copy-script/install-skills.py --all
+python copy-script/install-skills.py --ecosystems codex openclaw
+python copy-script/install-skills.py --all --dry-run
+python copy-script/install-skills.py --all --force
+```
+
+## Options
+
+- `--all`: install into every supported ecosystem
+- `--ecosystems`: install into selected ecosystems only
+- `--repo-root`: point the script at a different repository root
+- `--home`: point the script at a different home directory
+- `--dry-run`: print actions without copying files
+- `--force`: skip overwrite confirmation

copy-script/install-skills.py

@@ -0,0 +1,157 @@
+from __future__ import annotations
+
+import argparse
+import shutil
+import sys
+from pathlib import Path
+
+
+ECOSYSTEMS = {
+    "codex": ("codex", ".codex"),
+    "claude": ("claude", ".claude"),
+    "openclaw": ("openclaw", ".openclaw"),
+}
+
+SKILL_NAME = "building-good-ux"
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description=f"Copy the {SKILL_NAME} skill packages into local skills directories."
+    )
+    parser.add_argument(
+        "--ecosystems",
+        nargs="+",
+        choices=sorted(ECOSYSTEMS),
+        help="One or more ecosystems to install into. Omit for interactive mode.",
+    )
+    parser.add_argument(
+        "--all",
+        action="store_true",
+        help="Install into all supported ecosystems.",
+    )
+    parser.add_argument(
+        "--repo-root",
+        type=Path,
+        default=Path(__file__).resolve().parent.parent,
+        help="Path to the repository root. Defaults to the parent of copy-script/.",
+    )
+    parser.add_argument(
+        "--home",
+        type=Path,
+        default=Path.home(),
+        help="Home directory that contains the target skills folders.",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show what would be copied without writing anything.",
+    )
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Overwrite existing installations without prompting.",
+    )
+    return parser
+
+
+def prompt_ecosystems() -> list[str]:
+    options = list(ECOSYSTEMS)
+    print("Select ecosystems to install:")
+    for index, name in enumerate(options, start=1):
+        print(f"  {index}. {name}")
+    print("  a. all")
+
+    choice = input("Enter numbers or names separated by commas [a]: ").strip().lower()
+    if not choice or choice == "a" or choice == "all":
+        return options
+
+    selected: list[str] = []
+    for raw_item in choice.split(","):
+        item = raw_item.strip()
+        if not item:
+            continue
+        if item.isdigit():
+            index = int(item) - 1
+            if index < 0 or index >= len(options):
+                raise SystemExit(f"Invalid ecosystem number: {item}")
+            selected.append(options[index])
+            continue
+        if item not in ECOSYSTEMS:
+            raise SystemExit(f"Unknown ecosystem: {item}")
+        selected.append(item)
+
+    if not selected:
+        raise SystemExit("No ecosystems selected.")
+
+    return list(dict.fromkeys(selected))
+
+
+def prompt_confirmation(message: str) -> bool:
+    choice = input(f"{message} [y/N]: ").strip().lower()
+    return choice in {"y", "yes"}
+
+
+def resolve_targets(args: argparse.Namespace) -> list[str]:
+    if args.all:
+        return list(ECOSYSTEMS)
+
+    if args.ecosystems:
+        return list(dict.fromkeys(args.ecosystems))
+
+    if sys.stdin.isatty():
+        return prompt_ecosystems()
+
+    raise SystemExit("Specify --all or --ecosystems when running non-interactively.")
+
+
+def install_skill(source: Path, destination_root: Path, dry_run: bool) -> Path:
+    destination = destination_root / source.name
+    if dry_run:
+        print(f"Would copy {source} -> {destination}")
+        return destination
+
+    destination_root.mkdir(parents=True, exist_ok=True)
+
+    if destination.exists():
+        if destination.is_dir():
+            shutil.rmtree(destination)
+        else:
+            destination.unlink()
+
+    shutil.copytree(source, destination)
+    print(f"Copied {source} -> {destination}")
+    return destination
+
+
+def main() -> None:
+    parser = build_parser()
+    args = parser.parse_args()
+
+    repo_root = args.repo_root.resolve()
+    home = args.home.expanduser().resolve()
+    selected = resolve_targets(args)
+
+    jobs = []
+    for ecosystem in selected:
+        source_dirname, destination_dirname = ECOSYSTEMS[ecosystem]
+        source = repo_root / source_dirname / SKILL_NAME
+        destination_root = home / destination_dirname / "skills"
+        jobs.append((ecosystem, source, destination_root))
+
+    if not args.force and not args.dry_run:
+        destinations = [destination_root / SKILL_NAME for _, _, destination_root in jobs]
+        existing = [path for path in destinations if path.exists()]
+        if existing:
+            print("Existing installations found:")
+            for path in existing:
+                print(f"  {path}")
+            if not sys.stdin.isatty() or not prompt_confirmation("Overwrite them"):
+                raise SystemExit("Cancelled.")
+
+    for _, source, destination_root in jobs:
+        install_skill(source, destination_root, args.dry_run)
+
+
+if __name__ == "__main__":
+    main()

cspell.json

@@ -0,0 +1,37 @@
+{
+  "version": "0.2",
+  "language": "en",
+  "words": [
+    "AGENTS",
+    "Codex",
+    "Claude",
+    "Gitea",
+    "MVP",
+    "OpenClaw",
+    "README",
+    "apply_patch",
+    "backlinks",
+    "copy-script",
+    "cspell",
+    "frontmatter",
+    "gamified",
+    "building-good-ux",
+    "hyphen-case",
+    "learntocode",
+    "nerding",
+    "prefill",
+    "subagents",
+    "synsation",
+    "uxdesign",
+    "uxdesigners",
+    "uxdesignmastery",
+    "uxdesigns",
+    "vibecoding"
+  ],
+  "ignoreRegExpList": [
+    "/\\(D[A-Za-z0-9_-]+\\)/g"
+  ],
+  "ignorePaths": [
+    "LICENSE"
+  ]
+}

openclaw/building-good-ux/README.md

@@ -0,0 +1,14 @@
+# OpenClaw Package
+
+This folder contains the OpenClaw version of `building-good-ux`.
+
+## Packaging notes
+
+- The package mirrors the shared skill behavior from the repo root.
+- `SKILL.md` is the installable artifact copied into the target skills directory.
+- Keeping the wording aligned with the other harness folders makes cross-ecosystem maintenance simpler.
+
+## Source
+
+- `Intent.md` in the repo root
+- shared repository packaging conventions

openclaw/building-good-ux/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: building-good-ux
+description: Improve product and interface UX by reviewing or designing flows, screens, components, forms, and async states. Use when Codex needs to critique, redesign, or implement better loading, empty, error, partial, or success states, reduce form friction, choose feedback patterns, or make AI-generated UI less happy-path-only and more trustworthy.
+---
+
+# Intent
+
+## Purpose
+
+This skill helps an agent design, review, and implement better UX for product flows, screens, and components.
+
+It is inspired by the "Building Good UX" series by [synsation](https://www.instagram.com/synsation_).
+
+The skill should behave like a practical UX copilot:
+
+- spot friction before users do,
+- design beyond the happy path,
+- turn vague UX advice into concrete interface changes,
+- and keep the product usable when data is slow, missing, or broken.
+
+## What It Should Do
+
+When the user asks for UX help, the skill should:
+
+- identify the user's main goal and the critical path through the interface,
+- audit loading, success, empty, error, and partial states,
+- recommend patterns that reduce uncertainty and cognitive load,
+- suggest clearer copy, feedback, and recovery paths,
+- and connect UX advice to concrete product and implementation choices.
+
+## Core Questions
+
+The skill exists to answer:
+
+- What is the user trying to do?
+- Where might they hesitate, get stuck, or lose trust?
+- What should the interface show while it is waiting, empty, or failing?
+- How can the flow recover gracefully instead of collapsing?
+- What changes would make the product feel faster, clearer, and more forgiving?
+
+## Operating Model
+
+The UX pass should happen in 5 steps.
+
+### Step 1: Define the task and the risk
+
+Identify:
+
+- the user's primary goal,
+- the important actions and dependencies,
+- the moments where feedback matters,
+- and the highest-friction points in the current flow.
+
+### Step 2: Map the state coverage
+
+For each important step, account for:
+
+- success,
+- loading,
+- empty,
+- error,
+- and partial states.
+
+Look specifically for:
+
+- silent failures,
+- blank screens with no explanation,
+- disabled actions with no clue why,
+- and full-page blockers caused by one slow or broken dependency.
+
+### Step 3: Improve the interaction patterns
+
+#### Loading and feedback
+
+- Use skeletons for whole pages or large sections where layout matters first.
+- Use progress bars for measurable waits like uploads, imports, and installs.
+- Use inline spinners for small localized actions.
+- Use optimistic UI for fast reversible actions that should feel instant.
+- Avoid flashing loaders for work that finishes in under a second.
+- Add meaningful progress text for longer waits.
+- Replace long looping spinners with progress bars or step indicators when waits stretch past roughly ten seconds.
+
+#### Errors and recovery
+
+- Explain what happened, why it happened when known, and what the user can do next.
+- Never expose raw backend or database errors directly to the user.
+- Prefer inline errors near the failed action when recovery is local.
+- Use toasts for low-severity or transient status.
+- Use modals only when the user is blocked and must make a decision before continuing.
+
+#### Forms and inputs
+
+- Validate inline so the user can fix issues immediately.
+- Explain disabled submit states instead of leaving users guessing.
+- Show limits, formatting expectations, and password requirements before submission fails.
+- Prefill known information when possible.
+- Preserve user input and accept forgiving formatting when the backend can normalize it safely.
+
+#### Empty, success, and partial states
+
+- Explain why an area is empty and what the user should do next.
+- Turn first-use empty states into guided starting points.
+- Treat reward-style empty states, like inbox zero, as a positive moment.
+- Let sections load and fail independently instead of blocking the whole page.
+- Give broken sections local retry paths while keeping the rest of the interface usable.
+- Use cached or stale content strategically when it helps the product stay useful.
+
+### Step 4: Ground the advice in real patterns
+
+Use concrete examples from real products when they help clarify the recommendation, such as:
+
+- feed skeletons on content-heavy apps,
+- progress bars for file uploads and installs,
+- optimistic likes or saves,
+- helpful first-use dashboard empty states,
+- and section-level loading and retry behavior on dashboards and feeds.
+
+Do not force brand-name examples when a generic explanation is clearer.
+
+### Step 5: Deliver a prioritized recommendation
+
+The final response should:
+
+- diagnose the biggest UX risks first,
+- recommend the highest-impact fixes in priority order,
+- cover the relevant interface states,
+- include concrete copy or behavior suggestions when useful,
+- and mention implementation notes when the user is actively building the interface.
+
+## Output Format
+
+The final response should be concise and actionable.
+
+It should usually include:
+
+- brief diagnosis,
+- prioritized fixes,
+- state coverage notes,
+- suggested UX copy or interaction changes,
+- and implementation guidance when relevant.
+
+## Behavioral Rules
+
+- Optimize for clarity, trust, recovery, and forward momentum.
+- Prefer concrete product guidance over abstract design jargon.
+- Design for the messy middle, not just the happy path.
+- Distinguish critical blockers from minor friction.
+- Keep recommendations realistic for the product context.
+- Say plainly when a design is attractive but confusing, fragile, or incomplete.
+
+## Success Criteria
+
+The skill is successful if it can:
+
+- catch missing states before users do,
+- reduce confusion and abandonment,
+- improve recovery when things go wrong,
+- and help another agent turn rough interfaces into dependable experiences.