feat: migrate UX tools to a formal Extension (ux-toolkit)

GEMINI.md

@@ -1,56 +1,38 @@
-# Workspace: Base Folder Strategy & Custom Skills
+# Gemini CLI Project Context
 
-This branch introduces the **\_ux_git-worktree**, **\_ux_finish-pr**, and
-**\_ux_designer** skills and enforces the **Base Folder Strategy** for
-repository management. It is maintained by the AI DevTools UX team.
+Gemini CLI is an open-source AI agent that brings the power of Gemini directly
+into the terminal. It is designed to be a terminal-first, extensible, and
+powerful tool for developers.
 
-## 🚨 Directive for AI Agents (Read First)
+## 📦 UX Toolkit Extension
 
-**If you are an AI agent operating in this branch, your first task is to ensure
-the custom skills are active.**
+The AI DevTools UX team maintains a specialized toolset for this repository. It
+is recommended to install the **UX Toolkit** extension to enable standardized
+workflows (Base Folder Strategy, PR finishing, etc.).
 
-1. Check if `~/.gemini/skills/_ux_git-worktree/`,
-   `~/.gemini/skills/_ux_finish-pr/`, and `~/.gemini/skills/_ux_designer/`
-   exist.
-2. If any are missing, immediately execute `./scripts/sync-skills.sh`.
-3. Prompt the user to run `/skills reload` if you are in an interactive session.
+### Installation
+
+```bash
+gemini extensions install ./packages/extensions/ux-toolkit
+```
+
+After installation, run `/_ux_help` to see available commands.
+
+## 🛠️ Workspace Strategy: Base Folder
+
+This repository uses a **Git Worktree "Base Folder" strategy**.
+
+- Functional work (commits, code, tests) happens in sibling directories (e.g.,
+  `main/`, `feature-name/`).
+- The root directory is a container, not a repository itself.
+- **ALWAYS** use the `_ux_git-worktree` skill (included in the UX Toolkit) for
+  any Git operations.
 
 ## 🤝 Team Contributions
 
-This is a **Draft PR branch**. Your team is encouraged to:
-
 - Refine the `_ux_git-worktree` skill instructions in
-  `packages/core/src/skills/builtin/_ux_git-worktree/SKILL.md`.
+  `packages/extensions/ux-toolkit/skills/_ux_git-worktree/SKILL.md`.
 - Refine the `_ux_finish-pr` skill instructions in
-  `packages/core/src/skills/builtin/_ux_finish-pr/SKILL.md`.
-- Improve the automation in `scripts/worktree-manager.sh`.
+  `packages/extensions/ux-toolkit/skills/_ux_finish-pr/SKILL.md`.
 - All changes should be committed directly to this branch
   (`feature/gemini-cli-ux-team-skills`).
-
-## 1. Architectural Strategy
-
-Functional work happens in sibling directories (e.g., `main/`, `feature-name/`).
-The root directory acts as a container.
-
-## 2. Setting Up Custom Skills
-
-To ensure this agent has the necessary procedural knowledge to manage worktrees
-and PR reviews on your behalf, you must sync the custom skills to your local
-user directory.
-
-### Sync Script
-
-Run the following from the root of this worktree:
-
-```bash
-./scripts/sync-skills.sh
-```
-
-## 3. Mandatory Workflow
-
-- **ALWAYS** use the `_ux_git-worktree` skill for branch management.
-- **ALWAYS** use the `_ux_finish-pr` skill for pull request maintenance.
-- Never use standard `git checkout -b`.
-- Use `worktree-manager.sh pr <number>` for semantic PR checkouts.
-- When operating in a worktree, ensure the primary `main/.git` path is included
-  in your trusted directories to bypass macOS sandbox restrictions.

README.md

@@ -115,14 +115,16 @@ npm install -g @google/gemini-cli@nightly
 
 ### Automation & Integration
 
-- **Custom Development Skills**: This branch introduces specialized skills for
-  the AI DevTools UX team:
+- **UX Toolkit Extension**: This branch introduces a formal extension for the AI
+  DevTools UX team. Install it to enable specialized workflows: \`gemini
+  extensions install ./packages/extensions/ux-toolkit\`
   - **\_ux_git-worktree**: Manage Git Worktrees using the "Base Folder
     Strategy".
   - **\_ux_finish-pr**: Co-author assistant for authors to cross the finish line
     with UX polish and CI fixes.
   - **\_ux_designer**: Lead UX Designer expert to review React/Ink components
     against the v1.0 Design Principles (Density, Progressive Disclosure, State).
+  - **\_ux_help**: Show the welcome guide and documentation.
 - Automate operational tasks like querying pull requests or handling complex
   rebases
 - Use MCP servers to connect new capabilities, including

packages/extensions/ux-toolkit/GEMINI.md

@@ -0,0 +1,25 @@
+# UX Toolkit: Extension Context
+
+This extension provides the specialized toolset for the AI DevTools UX team.
+When this extension is active, the agent must adhere to the following standards
+and workflows.
+
+## 🚨 Agent Directives
+
+1.  **Worktree Strategy**: Always prefer the **Base Folder Strategy**. Use
+    `_ux_git-worktree` to manage sibling directories for all tasks.
+2.  **PR Maintenance**: Use `_ux_finish-pr` to handle the final polish of pull
+    requests, ensuring all tests pass and snapshots are updated.
+3.  **UI Review**: Use `_ux_designer` to audit any new Ink/React components
+    against the v1.0 Design Principles (Density, Progressive Disclosure, State).
+4.  **UX Writing**: Use `_ux_string-reviewer` to ensure all user-facing strings
+    comply with project terminology and clarity rules.
+
+## Mandatory Workflow
+
+- **ALWAYS** use the `_ux_git-worktree` skill for branch management.
+- **ALWAYS** use the `_ux_finish-pr` skill for pull request maintenance.
+- Never use standard `git checkout -b`.
+- Use `worktree-manager.sh pr <number>` for semantic PR checkouts.
+- When operating in a worktree, ensure the primary `main/.git` path is included
+  in your trusted directories to bypass macOS sandbox restrictions.

packages/extensions/ux-toolkit/commands/ux-help.toml

@@ -0,0 +1,4 @@
+description = "Show the UX Toolkit welcome guide and documentation."
+prompt = """
+Read the welcome guide at \`packages/extensions/ux-toolkit/WELCOME.md\` and output its contents to the user.
+"""

packages/extensions/ux-toolkit/gemini-extension.json

@@ -0,0 +1,13 @@
+{
+  "name": "ux-toolkit",
+  "version": "1.0.0",
+  "description": "Specialized suite of UX development tools for the Gemini CLI team, including worktree management, PR finishing, and design auditing.",
+  "author": "AI DevTools UX Team",
+  "skills": [
+    "skills/_ux_git-worktree",
+    "skills/_ux_finish-pr",
+    "skills/_ux_designer",
+    "skills/_ux_string-reviewer"
+  ],
+  "commands": ["commands/ux-help.toml"]
+}

packages/extensions/ux-toolkit/skills/_ux_git-worktree/SKILL.md

@@ -29,7 +29,7 @@ When the user asks to "start a new task" or "create a branch":
 
 When the user asks to "check out PR #123":
 1.  **NEVER** use standard `gh pr checkout` without a directory.
-2.  **ALWAYS** use the automation script: `./packages/core/src/skills/builtin/_ux_git-worktree/scripts/worktree-manager.sh pr 123`.
+2.  **ALWAYS** use the automation script: `./packages/extensions/ux-toolkit/skills/_ux_git-worktree/scripts/worktree-manager.sh pr 123`.
 3.  **Mandatory Prep**: Run `npm install` inside the new worktree directory to ensure all dependencies are resolved.
 4.  This script will automatically fetch the PR title and create a semantic directory name (e.g., `pr-123-fix-core-bug`).
 

packages/extensions/ux-toolkit/skills/_ux_string-reviewer/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: _ux_string-reviewer
+description: >
+  Use this skill when asked to review text and user-facing strings within the codebase. It ensures that these strings follow rules on clarity,
+  usefulness, brevity and style.
+---
+
+# String Reviewer
+
+## Instructions
+
+Act as a Senior UX Writer. Look for user-facing strings that are too long,
+unclear, or inconsistent. This includes inline text, error messages, and other
+user-facing text.
+
+Do NOT automatically change strings without user approval. You must only suggest
+changes and do not attempt to rewrite them directly unless the user explicitly
+asks you to do so.
+
+## Core voice principles
+
+The system prioritizes deterministic clarity over conversational fluff. We
+provide telemetry, not etiquette, ensuring the user retains absolute agency..
+
+1. **Deterministic clarity:** Distinguish between certain system/service states
+   (Cloud Billing, IAM, the System) and probabilistic AI analysis (Gemini).
+2. **System transparency:** Replace "Loading..." with active technical telemetry
+   (e.g., Tracing stack traces...). Keep status updates under 5 words.
+3. **Front-loaded actionability:** Always use the [Goal] + [Action] pattern.
+   Lead with intent so users can scan left-to-right.
+4. **Agentic error recovery:** Every error must be a pivot point. Pair failures
+   with one-click recovery commands or suggested prompts.
+5. **Contextual humility:** Reserve disclaimers and "be careful" warnings for P0
+   (destructive/irreversible) tasks only. Stop warning-fatigue.
+
+## The writing checklist
+
+Use this checklist to audit UI strings and AI responses.
+
+### Identity and voice
+- **Eliminate the "I":** Remove all first-person pronouns (I, me, my, mine).
+- **Subject attribution:** Refer to the AI as Gemini and the infrastructure as
+  the - system or the CLI.
+- **Active voice:** Ensure the subject (Gemini or the system) is clearly
+  performing the action.
+- **Ownership rule:** Use the system for execution (doing) and Gemini for
+  analysis (thinking)
+
+### Structural scannability
+- **The skip test:** Do the first 3 words describe the user’s intent? If not,
+  rewrite.
+- **Goal-first sequence:** Use the template: [To Accomplish X] + [Do Y].
+- **The 5-word rule:** Keep status updates and loading states under 5 words.
+- **Telemetry over etiquette:** Remove polite filler (Please wait, Thank you,
+  Certainly). Replace with raw data or progress indicators.
+- **Micro-state cycles:** For tasks $> 3$ seconds, cycle through specific
+  sub-states (e.g., Parsing logs... ➔ Identifying patterns...) to show momentum.
+
+
+### Technical accuracy and humility
+- **Verb signal check:** Use deterministic verbs (is, will, must) for system
+  state/infrastructure.
+  - Use probabilistic verbs (suggests, appears, may, identifies) for AI output.
+- **No 100% certainty:** Never attribute absolute certainty to model-generated
+  content.
+- **Precision over fuzziness:** Use technical metrics (latency, tokens, compute) instead of "speed" or "cost."
+- **Instructional warnings:** Every warning must include a specific corrective action (e.g., "Perform a dry-run first" or "Review line 42").
+
+### Agentic error recovery
+- **The one-step rule:** Pair every error message with exactly one immediate
+  path to a fix (command, link, or prompt).
+- **Human-first:** Provide a human-readable explanation before machine error
+  codes (e.g., 404, 500).
+-  **Suggested prompts:** Offer specific text for the user to copy/click like
+   “Ask Gemini: 'Explain this port error.'”
+
+### Use consistent terminology
+
+Ensure all terminology aligns with the project [word
+list](./references/word-list.md). 
+
+If a string uses a term marked "do not use" or "use with caution," provide a
+correction based on the preferred terms.
+
+## Ensure consistent style for settings
+
+If `packages/cli/src/config/settingsSchema.ts` is modified, confirm labels and
+descriptions specifically follow the unique [Settings
+guidelines](./references/settings.md).
+
+## Output format
+When suggesting changes, always present your review using the following list
+format. Do not provide suggestions outside of this list..
+
+```
+1. **{Rationale/Principle Violated}**
+  - ❌ "{incorrect phrase}"
+  - ✅ `"{corrected phrase}"`
+```

packages/extensions/ux-toolkit/skills/_ux_string-reviewer/references/settings.md

@@ -0,0 +1,28 @@
+# Settings
+
+## Noun-First Labeling (Scannability)
+
+Labels must start with the subject of the setting, not the action. This allows
+users to scan for the feature they want to change.
+
+- **Rule:** `[Noun]` `[Attribute/Action]`
+- **Example:** `Show line numbers` becomes simply `Line numbers`
+
+## Positive Boolean Logic (Cognitive Ease)
+
+Eliminate "double negatives." Booleans should represent the presence of a
+feature, not its absence.
+
+- **Rule:** Replace `Disable {feature}` or `Hide {Feature}` with
+  `{Feature} enabled` or simply `{Feature}`.
+- **Example:** Change "Disable auto update" to "Auto update".
+- **Implementation:** Invert the boolean value in your config loader so true
+  always equals `On`
+
+## Verb Stripping (Brevity)
+
+Remove redundant leading verbs like "Enable," "Use," "Display," or "Show" unless
+they are part of a specific technical term.
+
+- **Rule**: If the label works without the verb, remove it
+- **Example**: Change `Enable prompt completion` to `Prompt completion`

packages/extensions/ux-toolkit/skills/_ux_string-reviewer/references/word-list.md

@@ -0,0 +1,61 @@
+## Terms
+
+### Preferred
+
+- Use **create** when a user is creating or setting up something.
+- Use **allow** instead of **may** to indicate that permission has been granted
+  to perform some action.
+- Use **canceled**, not **cancelled**.
+- Use **configure** to refer to the process of changing the attributes of a
+  feature, even if that includes turning on or off the feature.
+- Use **delete** when the action being performed is destructive.
+- Use **enable** for binary operations that turn a feature or API on. Use "turn
+  on" and "turn off" instead of "enable" and "disable" for other situations.
+- Use **key combination** to refer to pressing multiple keys simultaneously.
+- Use **key sequence** to refer to pressing multiple keys separately in order.
+- Use **modify** to refer to something that has changed vs obtaining the latest
+  version of something.
+- Use **remove** when the action being performed takes an item out of a larger
+  whole, but doesn't destroy the item itself.
+- Use **set up** as a verb. Use **setup** as a noun or adjective.
+- Use **show**. In general, use paired with **hide**.
+- Use **sign in**, **sign out** as a verb. Use **sign-in** or **sign-out** as a
+  noun or adjective.
+- Use **update** when you mean to obtain the latest version of something.
+- Use **want** instead of **like** or **would like**.
+
+#### Don't use
+
+- Don't use **etc.** It's redundant. To convey that a series is incomplete,
+  introduce it with "such as" instead.
+- Don't use **hostname**, use "host name" instead.
+- Don't use **in order to**. It's too formal. "Before you can" is usually better
+  in UI text.
+- Don't use **one or more**. Specify the quantity where possible. Use "at least
+  one" when the quantity is 1+ but you can't be sure of the number. Likewise,
+  use "at least one" when the user must choose a quantity of 1+.
+- Don't use the terms **log in**, **log on**, **login**, **logout** or **log
+  out**.
+- Don't use **like** or **would you like**. Use **want** instead. Better yet,
+  rephrase so that it's not referring to the user's emotional state, but rather
+  what is required.
+
+#### Use with caution
+
+- Avoid using **leverage**, especially as a verb. "Leverage" is considered a
+  buzzword largely devoid of meaning apart from the simpler "use".
+- Avoid using **once** as a synonym for "after". Typically, when "once" is used
+  in this way, it is followed by a verb in the perfect tense.
+- Don't use **e.g.** Use "example", "such as", "like", or "for example". The
+  phrase is always followed by a comma.
+- Don't use **i.e.** unless absolutely essential to make text fit. Use "that is"
+  instead.
+- Use **disable** for binary operations that turn a feature or API off. Use
+  "turn on" and "turn off" instead of "enable" and "disable" for other
+  situations. For UI elements that are not available, use "dimmed" instead of
+  "disabled".
+- Use **please** only when you're asking the user to do something inconvenient,
+  not just following the instructions in a typical flow.
+- Use **really** sparingly in such constructions as "Do you really want to..."
+  Because of the weight it puts on the decision, it should be used to confirm
+  actions that the user is extremely unlikely to make.

scripts/sync-skills.sh

@@ -1,36 +0,0 @@
-#!/bin/bash
-# sync-skills.sh - Syncs custom skills from the repo to the user's global ~/.gemini/skills folder.
-
-SKILLS_DIR="${HOME}/.gemini/skills"
-COMMANDS_DIR="${HOME}/.gemini/commands"
-REPO_SKILLS_PATH="packages/core/src/skills/builtin"
-
-mkdir -p "${SKILLS_DIR}"
-
-echo "Syncing skills..."
-
-# List of skills to sync
-CUSTOM_SKILLS=("_ux_git-worktree" "_ux_finish-pr" "_ux_designer")
-
-for SKILL in "${CUSTOM_SKILLS[@]}"; do
-    if [[ -d "${REPO_SKILLS_PATH}/${SKILL}" ]]; then
-        # Sync Skill
-        cp -r "${REPO_SKILLS_PATH}/${SKILL}" "${SKILLS_DIR}/"
-        echo "✅ Synced: ${SKILL}"
-
-        # Clean up legacy explicit command files if they exist to prevent conflicts.
-        # Gemini CLI automatically registers a slash command for each skill based on its name.
-        COMMAND_FILE="${COMMANDS_DIR}/${SKILL}.toml"
-        if [[ -f "${COMMAND_FILE}" ]]; then
-            rm -f "${COMMAND_FILE}"
-            echo "🧹 Cleaned up redundant command file: ${COMMAND_FILE}"
-        fi
-    else
-        echo "❌ Error: Skill ${SKILL} not found in ${REPO_SKILLS_PATH}"
-    fi
-done
-
-echo "Done. Run '/skills reload' in your Gemini session to apply changes."
-echo "--------------------------------------------------"
-echo ""
-cat WELCOME.md