@clix-so/clix-agent-skills 0.2.1 → 0.2.3

package/README.md

@@ -3,8 +3,24 @@
 [![npm version](https://img.shields.io/npm/v/%40clix-so%2Fclix-agent-skills.svg?logo=npm&label=npm)](https://www.npmjs.com/package/@clix-so/clix-agent-skills)
 [![npm downloads](https://img.shields.io/npm/d18m/%40clix-so%2Fclix-agent-skills.svg)](https://www.npmjs.com/package/@clix-so/clix-agent-skills)
 
-This repository contains a collection of **Agent Skills for Clix**. Each skill
-is a self-contained package that can be loaded and executed by AI clients.
+This repository contains a collection of Agent Skills for Clix. Each skill is a
+separate module within this package that can be installed and used independently
+by AI clients.
+
+## Available Skills
+
+- **clix-integration**: Seamlessly integrate Clix Mobile SDK to your mobile
+  application with Clix MCP Server
+- **clix-event-tracking**: Implement `Clix.trackEvent` with naming/schema best
+  practices and campaign-ready validation
+- **clix-user-management**: Implement `Clix.setUserId` + user properties with
+  logout best practices, personalization (`user.*`), and audience targeting
+- **clix-personalization**: Author and debug personalization templates for
+  message content, deep links/URLs, and audience targeting rules (`user.*`,
+  `event.*`, `trigger.*`, `device.*`)
+- **clix-api-triggered-campaigns**: Configure API-triggered campaigns in the
+  console and trigger them from your backend with safe auth, dynamic filters
+  (`trigger.*`), and personalization patterns
 
 ## Installing Skills
 
@@ -35,9 +51,9 @@ The CLI supports two installation modes for skills:
 - Skills are available across all projects
 - Best for personal development setup
 
-**Note:** MCP (Model Context Protocol) server configuration is always set up
-globally (system root), regardless of the skill installation mode. This ensures
-the MCP server is available across all your projects.
+**Note:** MCP (Model Context Protocol) server configuration location depends on
+the AI client. Some clients support both project-level and user-level (global)
+configurations. See the "Configuration Locations" section below for details.
 
 ```bash
 # Install a specific skill (repo root - default)
@@ -58,21 +74,6 @@ npx @clix-so/clix-agent-skills@latest install --all --client cursor
 npx @clix-so/clix-agent-skills@latest install --all --client cursor --global
 ```
 
-### Available Skills
-
-- **clix-integration**: Seamlessly integrate Clix Mobile SDK to your mobile
-  application with Clix MCP Server
-- **clix-event-tracking**: Implement `Clix.trackEvent` with naming/schema best
-  practices and campaign-ready validation
-- **clix-user-management**: Implement `Clix.setUserId` + user properties with
-  logout best practices, personalization (`user.*`), and audience targeting
-- **clix-personalization**: Author and debug personalization templates for
-  message content, deep links/URLs, and audience targeting rules (`user.*`,
-  `event.*`, `trigger.*`, `device.*`)
-- **clix-api-triggered-campaigns**: Configure API-triggered campaigns in the
-  console and trigger them from your backend with safe auth, dynamic filters
-  (`trigger.*`), and personalization patterns
-
 **Supported Clients:**
 
 | Client         | Flag                                 | Default Path       |
@@ -88,14 +89,13 @@ npx @clix-so/clix-agent-skills@latest install --all --client cursor --global
 | OpenCode       | `--client opencode`                  | `.opencode/skill/` |
 | VS Code        | `--client vscode`                    | `.vscode/skills/`  |
 
-### Claude Code
+### Claude Code (Alternative setup via plugin marketplace)
 
 To register this repository as a plugin marketplace in Claude Code, run the
 following command:
 
 ```bash
 /plugin marketplace add clix-so/skills
-/plugin install all@clix-agent-skills
 ```
 
 To install specific skills:
@@ -111,10 +111,6 @@ Alternatively, you can install a single skill directly by running:
 /plugin install <plugin-name>@<marketplace-name>
 # For example
 /plugin install clix-integration@clix-agent-skills
-/plugin install clix-event-tracking@clix-agent-skills
-/plugin install clix-user-management@clix-agent-skills
-/plugin install clix-personalization@clix-agent-skills
-/plugin install clix-api-triggered-campaigns@clix-agent-skills
 ```
 
 **Note for Claude Code users**: Skills now support automatic hot-reload! Skills
@@ -122,7 +118,7 @@ created or modified in `~/.claude/skills` or `.claude/skills` are immediately
 available without restarting the session. Skills also show real-time progress
 while executing, displaying tool uses as they happen.
 
-### Codex
+### Codex (Alternative setup via skill-installer)
 
 To manually install skills, save them from this repository into your Codex
 configuration directory:

package/dist/bin/commands/install.js

@@ -110,6 +110,15 @@ async function installSkill(skillName, options) {
     // Determine installation root: repo root (cwd) or system root (home directory)
     const installRoot = options.global ? os_1.default.homedir() : process.cwd();
     const destPath = path_1.default.resolve(installRoot, relativeDest, skillName);
+    // Gemini note: by default we install to project scope (.gemini/skills).
+    // If the user expects Gemini to see these skills in *any* project, they should use --global.
+    if (options.client?.toLowerCase() === "gemini" &&
+        !options.global &&
+        !options.path &&
+        skillName === "integration") {
+        console.log(chalk_1.default.yellow("Gemini note: skills were installed to this project's .gemini/skills. " +
+            "To make skills available across all projects, re-run with --global (installs to ~/.gemini/skills)."));
+    }
     // 3. Copy Files
     try {
         await fs_extra_1.default.ensureDir(destPath);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clix-so/clix-agent-skills",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "An open collection of agent skills for Clix.",
   "main": "dist/index.js",
   "bin": {

package/skills/api-triggered-campaigns/SKILL.md

@@ -1,5 +1,7 @@
 ---
 name: clix-api-triggered-campaigns
+display-name: API-Triggered Campaigns
+short-description: API-triggered campaign setup
 description:
   Helps developers configure API-triggered campaigns in the Clix console and
   trigger them from backend services with safe auth, payload schemas, dynamic

package/skills/event-tracking/SKILL.md

@@ -1,5 +1,7 @@
 ---
 name: clix-event-tracking
+display-name: Event Tracking
+short-description: Event tracking setup
 description:
   Implements Clix event tracking (Clix.trackEvent) with consistent naming, safe
   property schemas, and campaign-ready validation. Use when adding, reviewing,

package/skills/integration/SKILL.md

@@ -1,5 +1,7 @@
 ---
 name: clix-integration
+display-name: SDK Integration
+short-description: SDK integration guide
 description:
   Integrates Clix Mobile SDK into iOS, Android, Flutter, and React Native
   projects. Provides step-by-step guidance for installation, initialization, and

package/skills/integration/scripts/install-mcp.sh

@@ -31,7 +31,7 @@ Usage:
 
 Options:
   --client <client>      Explicitly select the MCP client to configure.
-                         Supported: claude, claude-code, opencode, amp, codex, cursor, vscode
+                         Supported: claude, claude-code, gemini, opencode, amp, codex, cursor, vscode
   --help                 Show this help.
 
 Environment:
@@ -70,7 +70,7 @@ done
 
 validate_client() {
   case "${1:-}" in
-    claude|claude-code|opencode|amp|codex|cursor|vscode) return 0 ;;
+    claude|claude-code|gemini|opencode|amp|codex|cursor|vscode) return 0 ;;
     "") return 1 ;;
     *) return 1 ;;
   esac
@@ -93,6 +93,15 @@ get_config_path() {
   local platform=$(detect_platform)
 
   case "$client" in
+    gemini)
+      # Gemini supports project scope (.gemini/settings.json) and user scope (~/.gemini/settings.json).
+      # Prefer project config when it exists (Gemini prioritizes project over user).
+      if [ -f ".gemini/settings.json" ]; then
+        echo ".gemini/settings.json"
+      else
+        echo "${home}/.gemini/settings.json"
+      fi
+      ;;
     claude-code)
       # Claude Code CLI manages MCP via `claude mcp ...` commands (no direct config file here)
       echo ""
@@ -145,6 +154,72 @@ get_config_path() {
   esac
 }
 
+# Returns candidate config paths (one per line) for a client, including both
+# project-level and user-level locations where applicable.
+get_candidate_config_paths() {
+  local client=$1
+  local home="${HOME:-$HOME}"
+  local platform
+  platform=$(detect_platform)
+
+  case "$client" in
+    gemini)
+      # Gemini supports project scope (.gemini/settings.json) and user scope (~/.gemini/settings.json)
+      echo ".gemini/settings.json"
+      echo "${home}/.gemini/settings.json"
+      ;;
+    cursor)
+      # Cursor supports workspace (.cursor/mcp.json) and user (~/.cursor/mcp.json)
+      echo ".cursor/mcp.json"
+      echo "${home}/.cursor/mcp.json"
+      ;;
+    amp)
+      # Amp can be configured via VS Code workspace/user settings (per this script),
+      # and is also commonly stored under ~/.config/amp/settings.json.
+      echo ".vscode/settings.json"
+      echo "${home}/.vscode/settings.json"
+      if [ "$platform" = "win32" ]; then
+        echo "${USERPROFILE:-$home}/.config/amp/settings.json"
+      else
+        echo "${home}/.config/amp/settings.json"
+      fi
+      ;;
+    vscode)
+      echo "${home}/.vscode/mcp.json"
+      ;;
+    codex)
+      echo "${home}/.codex/config.toml"
+      ;;
+    opencode)
+      echo "opencode.jsonc"
+      echo "opencode.json"
+      ;;
+    *)
+      local p
+      p="$(get_config_path "$client")"
+      [ -n "$p" ] && echo "$p"
+      ;;
+  esac
+}
+
+find_existing_clix_mcp_configs() {
+  local client=$1
+  local any_found=0
+
+  # Print matching paths to stdout (one per line).
+  while IFS= read -r p; do
+    [ -z "${p:-}" ] && continue
+    [ ! -f "$p" ] && continue
+    if grep -q "clix-mcp-server" "$p" 2>/dev/null; then
+      echo "$p"
+      any_found=1
+    fi
+  done < <(get_candidate_config_paths "$client" | awk 'NF' | sort -u)
+
+  # Return 0 if found any, 1 otherwise.
+  [ "$any_found" -eq 1 ]
+}
+
 # Configure MCP for Claude Code CLI
 configure_claude_code() {
   if ! command -v claude &> /dev/null; then
@@ -228,11 +303,30 @@ configure_amp() {
     log "${GREEN}✔ Created Amp settings file${RESET}"
   fi
 
-  # Check if already configured
+  # Check both project + user locations before deciding.
+  # If config_path already has it, we can skip. If it's only present elsewhere,
+  # we still proceed to configure config_path so the selected scope works.
   if grep -q "clix-mcp-server" "$config_path" 2>/dev/null; then
     log "${GREEN}✔ Clix MCP Server already configured in Amp${RESET}"
     return 0
   fi
+  local existing_paths=""
+  # NOTE: Use the function's exit status (0 = found elsewhere, 1 = not found) in a way
+  # that's safe under `set -e` (conditions don't trigger errexit).
+  if existing_paths="$(find_existing_clix_mcp_configs "amp")"; then
+    log ""
+    log "${YELLOW}⚠️  DUPLICATE CONFIGURATION DETECTED${RESET}"
+    log "${YELLOW}   Found clix-mcp-server in other config location(s).${RESET}"
+    log "${YELLOW}   clix-mcp-server is already configured in:${RESET}"
+    printf "%s\n" "$existing_paths" | sed 's/^/     /'
+    log ""
+    log "${YELLOW}   Now also adding to: ${config_path}${RESET}"
+    log ""
+    log "${BLUE}   ℹ️  Having multiple configurations may cause confusion.${RESET}"
+    log "${BLUE}      To avoid duplicates, you can remove the server from other locations.${RESET}"
+    log "${BLUE}      Amp typically prioritizes workspace (.vscode) over user (~/.vscode) settings.${RESET}"
+    log ""
+  fi
 
   # Use node to safely update JSON/JSONC (VS Code settings often allow comments)
   if command -v node &> /dev/null; then
@@ -433,7 +527,8 @@ EOF
 
 # Configure MCP for JSON-based clients
 configure_json_client() {
-  local config_path="$1"
+  local client="$1"
+  local config_path="$2"
   local config_dir=$(dirname "$config_path")
 
   mkdir -p "$config_dir"
@@ -443,11 +538,42 @@ configure_json_client() {
     log "${GREEN}✔ Created config file${RESET}"
   fi
 
-  # Check if already configured
+  # Check both project + user locations before deciding.
+  # If config_path already has it, we can skip. If it's only present elsewhere,
+  # we still proceed to configure config_path so the selected scope works.
   if grep -q "clix-mcp-server" "$config_path" 2>/dev/null; then
     log "${GREEN}✔ Clix MCP Server already configured${RESET}"
     return 0
   fi
+  local existing_paths=""
+  # NOTE: Use the function's exit status (0 = found elsewhere, 1 = not found) in a way
+  # that's safe under `set -e` (conditions don't trigger errexit).
+  if existing_paths="$(find_existing_clix_mcp_configs "$client")"; then
+    log ""
+    log "${YELLOW}⚠️  DUPLICATE CONFIGURATION DETECTED${RESET}"
+    log "${YELLOW}   Found clix-mcp-server in other config location(s).${RESET}"
+    log "${YELLOW}   clix-mcp-server is already configured in:${RESET}"
+    printf "%s\n" "$existing_paths" | sed 's/^/     /'
+    log ""
+    log "${YELLOW}   Now also adding to: ${config_path}${RESET}"
+    log ""
+    log "${BLUE}   ℹ️  Having multiple configurations may cause confusion.${RESET}"
+    log "${BLUE}      To avoid duplicates, you can remove the server from other locations.${RESET}"
+
+    # Client-specific priority information
+    case "$client" in
+      cursor)
+        log "${BLUE}      Cursor prioritizes workspace (.cursor) over user (~/.cursor) configs.${RESET}"
+        ;;
+      gemini)
+        log "${BLUE}      Gemini prioritizes project (.gemini) over user (~/.gemini) configs.${RESET}"
+        ;;
+      vscode)
+        log "${BLUE}      VS Code prioritizes workspace over user-level configs.${RESET}"
+        ;;
+    esac
+    log ""
+  fi
 
   # Use node to safely update JSON
   if command -v node &> /dev/null; then
@@ -483,6 +609,11 @@ detect_clients() {
     echo "claude"
   fi
 
+  # Gemini CLI (user config: ~/.gemini/settings.json)
+  if command -v gemini &> /dev/null || [ -f "${HOME}/.gemini/settings.json" ]; then
+    echo "gemini"
+  fi
+
   # OpenCode (project config files or opencode command)
   if [ -f "opencode.json" ] || [ -f "opencode.jsonc" ] || command -v opencode &> /dev/null; then
     echo "opencode"
@@ -606,7 +737,7 @@ if [ "$detected_client" != "unknown" ]; then
     elif [ "$detected_client" = "opencode" ]; then
       configure_opencode "$config_path"
     else
-      configure_json_client "$config_path"
+      configure_json_client "$detected_client" "$config_path"
     fi
 
     log "${GREEN}✅ Successfully configured Clix MCP Server!${RESET}"
@@ -618,6 +749,7 @@ if [ "$detected_client" != "unknown" ]; then
 else
   log "${YELLOW}⚠️  Could not auto-detect MCP client.${RESET}"
   log "${BLUE}The package is ready to use. Configure manually:${RESET}"
+  log "${BLUE}  - Gemini CLI: Add to ~/.gemini/settings.json${RESET}"
   log "${BLUE}  - OpenCode: Add to opencode.json or opencode.jsonc${RESET}"
   log "${BLUE}  - Amp: Add to .vscode/settings.json or ~/.vscode/settings.json${RESET}"
   log "${BLUE}  - Codex: Add to ~/.codex/config.toml${RESET}"

package/skills/personalization/SKILL.md

@@ -1,5 +1,7 @@
 ---
 name: clix-personalization
+display-name: Personalization
+short-description: Personalization templates
 description:
   Helps developers author and debug Clix personalization templates
   (Liquid-style) for message content, deep links/URLs, and audience targeting.

package/skills/user-management/SKILL.md

@@ -1,5 +1,7 @@
 ---
 name: clix-user-management
+display-name: User Management
+short-description: User management setup
 description:
   Implements Clix user identification and user properties (setUserId,
   removeUserId, setUserProperty/setUserProperties,