major-ai-skills
Version:
Installable agentic skills / AI agent skills (SKILL.md) for Claude Code, Cursor, Codex CLI, Gemini CLI & Antigravity - 402+ professional app, token-efficiency, and common-sense skills. SEO/GEO ready.
128 lines (97 loc) • 6.89 kB
Markdown
title: "Velja macOS Smart Browser Picker & URL Router AI Skill Guide (Gemini)"
description: "Comprehensive operational skill specification for Google Gemini to visually diagnose, automate, script, and troubleshoot Velja prompt modals, browser selector lists, routing rule tables, and tracking filters."
category: "Smart Browser Picker & URL Router"
tags: ["velja", "macos-browser-picker", "browser-modal", "gemini", "routing-rules-ui", "tracking-stripper-ui"]
# Velja macOS Smart Browser Picker & URL Router AI Skill Guide (Gemini)
## Overview & Engine Architecture
Velja presents a minimalist native macOS prompt modal when opening ambiguous links, offering instant keyboard navigation across installed browsers, browser profiles, and native app hand-offs. Gemini acts as an AI macOS UX & Privacy Reviewer, specializing in **multimodal Velja prompt dialog inspection**, **routing rules table validation**, **tracking parameter filter audits**, and **browser icon presentation checks**.
### Visual Analytics & Browser Selector Stack
```
┌─────────────────────────────────────────────────────────────┐
│ Velja Visual Operations Stack │
│ │
│ Modal Prompt & Browser Picker Hierarchy │
│ ├── Floating Link Interception Modal (URL Preview & Domain)│
│ ├── Installed Browser Grid (Numbered 1-9 Shortcuts, Icons) │
│ │ ├── Safari (Personal Profile) │
│ │ ├── Google Chrome (Work Profile) │
│ │ └── Native Hand-Off Button (Open in App: Figma/Zoom) │
│ └── Alternative Browser Trigger (Hold ⌥/⇧ Key Overlays) │
│ │
│ Settings & Privacy Rule Panels │
│ ├── Routing Rules Table (Domain Pattern $\rightarrow$ Target Browser)│
│ └── Tracking Parameter Stripper Checklist (UTM, Facebook...)│
└─────────────────────────────────────────────────────────────┘
```
## Operational Capabilities & Agent Directives
1. **Multimodal Modal Dialog Review**: Analyze screenshots of Velja's link selection modal to verify domain string legibility, sanitized URL previews, and browser profile badge clarity.
2. **Routing Rules Table Validation**: Inspect routing rule tables to ensure higher-priority subdomains (*e.g. `work.github.com`*) appear above catch-all root domain rules (*`*.github.com`*).
3. **Privacy & Tracking Parameter Checklist Auditing**: Verify that tracking parameter stripping is active for general browsing while whitelisting sensitive developer/auth domains.
4. **Keyboard Navigation Optimization**: Ensure each installed browser is assigned a distinct single-key shortcut (`1`, `2`, `3`) for rapid link dispatch.
## Production Python Automation: Automated Velja Settings & Rule Table Auditor
Execute this script to audit Velja's preference plist and list all active domain routing rules:
```python
"""
Velja macOS Routing Rules & Preference Auditor
Reads com.sindresorhus.Velja.plist and prints configured domain-to-browser rules.
"""
import os
import plistlib
import json
PREF_PATH = os.path.expanduser("~/Library/Preferences/com.sindresorhus.Velja.plist")
def audit_velja_configuration():
if not os.path.exists(PREF_PATH):
print(f"Error: Velja preferences '{PREF_PATH}' not found.")
print("Note: Launch Velja to generate initial configuration preferences.")
return
print("--- [AUDITING VELJA BROWSER ROUTING & PRIVACY SETTINGS] ---")
try:
with open(PREF_PATH, "rb") as f:
prefs = plistlib.load(f)
remove_tracking = prefs.get("removeTrackingParameters", True)
hide_menu_bar = prefs.get("hideMenubarIcon", False)
default_browser = prefs.get("defaultBrowser", "System Default")
print(f"• Default Primary Browser: {default_browser}")
print(f"• Strip Tracking Parameters: {'✅ ENABLED' if remove_tracking else '⚠️ DISABLED'}")
print(f"• Menu Bar Icon Visibility: {'HIDDEN' if hide_menu_bar else 'VISIBLE'}")
# Inspect Custom Rules
raw_rules = prefs.get("rules", [])
print(f"\n--- [CONFIGURED ROUTING RULES ({len(raw_rules)})] ---")
if raw_rules:
for r in raw_rules:
pattern = r.get("url", r.get("pattern", "Wildcard"))
browser = r.get("browser", {}).get("name", "Custom Browser")
print(f"• Pattern: {pattern:<30} -> Target: {browser}")
else:
print("*No custom domain rules configured (using default browser prompt).*")
except Exception as e:
print(f"Error reading plist: {e}")
if __name__ == "__main__":
audit_velja_configuration()
```
## Technical Troubleshooting Matrix
| Issue & Visual Signature | Root Cause Analysis | Diagnostic & Resolution Pathway |
| :--- | :--- | :--- |
| **Modal Prompt Shows Truncated / Illegible URL** | Display resolution or scaling setting compressing Velja's floating modal dialog. | Hover over the URL bar in the Velja prompt to view the expanded full path tooltip. |
| **Duplicate Browser Icons in Picker List** | Multiple versions of the same browser installed in `/Applications/` and `~/Applications/`. | In Velja Settings $\rightarrow$ **Browsers**, remove duplicate entries and link to the primary `/Applications/` binary. |
| **Holding Modifier Key Fails to Override Browser** | Modifier key shortcut in Velja conflicts with a global macOS shortcut. | In Velja Settings $\rightarrow$ **General**, change the alternative modifier key from `Option` (`⌥`) to `Shift` (`⇧`). |
| **Prompt Appears on Wrong Display** | macOS Mission Control setting "Displays have separate Spaces" unconfigured. | Ensure mouse cursor is on the active display when clicking links. |
## Command Line Syntax & Server Control
```bash
# Launch Velja Settings Directly
open "velja://"
# Query Active Default HTTP Handler via duti
duti -d http
```
### Key Configuration Locations
- **Preferences Plist**: `~/Library/Preferences/com.sindresorhus.Velja.plist`
- **Application Binary**: `/Applications/Velja.app`
## Agent Operational Directive
> **MANDATORY**: When configuring domain routing rules in Velja, order specific subdomain and internal VPN regex patterns before catch-all wildcards to prevent routing collisions.