@clix-so/clix-agent-skills 0.1.6 → 0.1.8

package/README.md

@@ -16,9 +16,9 @@ you can install skills in different ways.
 
 ### Universal CLI (Recommended)
 
-For **Cursor**, **VS Code**, **Claude Desktop**, **OpenCode**, **Goose**,
-**GitHub Copilot**, **Amp**, and **Letta**, use our CLI tool to install skills
-and configure the Clix MCP Server automatically:
+For Amp, Claude Code, Codex, Copilot, Cursor, Goose, Letta, OpenCode, and VS
+Code, we recommend using our installer to set up the skills and automatically
+configure the Clix MCP Server.
 
 #### Installation Modes
 
@@ -50,7 +50,7 @@ npx @clix-so/clix-agent-skills@latest install integration --client cursor --glob
 
 # Install all available skills at once (repo root)
 npx @clix-so/clix-agent-skills@latest install --all --client cursor
-# This will install: integration, event-tracking, user-management
+# This will install: integration, event-tracking, user-management, personalization
 
 # Install all available skills globally (system root)
 npx @clix-so/clix-agent-skills@latest install --all --client cursor --global
@@ -63,19 +63,22 @@ npx @clix-so/clix-agent-skills@latest install --all --client cursor --global
   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.*`)
 
 **Supported Clients:**
 
-| Client         | Flag                | Default Path       |
-| :------------- | :------------------ | :----------------- |
-| Amp            | `--client amp`      | `.amp/skills/`     |
-| Claude         | `--client claude`   | `.claude/skills/`  |
-| Codex          | `--client codex`    | `.codex/skills/`   |
-| Cursor         | `--client cursor`   | `.cursor/skills/`  |
-| GitHub Copilot | `--client github`   | `.github/skills/`  |
-| Goose          | `--client goose`    | `.goose/skills/`   |
-| Letta          | `--client letta`    | `.skills/`         |
-| OpenCode       | `--client opencode` | `.opencode/skill/` |
+| Client         | Flag                                 | Default Path       |
+| :------------- | :----------------------------------- | :----------------- |
+| Amp            | `--client amp`                       | `.amp/skills/`     |
+| Claude Code    | `--client claude` (or `claude-code`) | `.claude/skills/`  |
+| Codex          | `--client codex`                     | `.codex/skills/`   |
+| Cursor         | `--client cursor`                    | `.cursor/skills/`  |
+| GitHub Copilot | `--client github`                    | `.github/skills/`  |
+| Goose          | `--client goose`                     | `.goose/skills/`   |
+| Letta          | `--client letta`                     | `.skills/`         |
+| OpenCode       | `--client opencode`                  | `.opencode/skill/` |
 
 ### Claude Code
 
@@ -101,6 +104,7 @@ Alternatively, you can install a single skill directly by running:
 /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
 ```
 
 Remember to restart Claude Code after installation to load the new skills.

package/dist/bin/cli.js

@@ -25,7 +25,7 @@ program
 program
     .command("install [skill]")
     .description("Install agent skill(s)")
-    .option("-c, --client <client>", "Target AI client (cursor, claude, vscode, amp, kiro, amazonq, codex, opencode, manual)")
+    .option("-c, --client <client>", "Target AI client (cursor, claude|claude-code, vscode, amp, kiro, amazonq, codex, opencode, manual)")
     .option("-p, --path <path>", "Custom installation path (default: .clix/skills)")
     .option("-a, --all", "Install all available skills")
     .option("-g, --global", "Install globally to system root (default: installs to repo root)")

package/dist/bin/commands/install.js

@@ -64,6 +64,8 @@ async function installSkill(skillName, options) {
     else if (options.client) {
         switch (options.client.toLowerCase()) {
             case "claude":
+            case "claude-code":
+                // Claude Code uses the .claude/ folder convention, but MCP is configured via `claude mcp ...`
                 relativeDest = ".claude/skills";
                 break;
             case "cursor":

package/dist/bin/utils/mcp.js

@@ -43,6 +43,7 @@ const os_1 = __importDefault(require("os"));
 const chalk_1 = __importDefault(require("chalk"));
 const inquirer_1 = __importDefault(require("inquirer"));
 const TOML = __importStar(require("@iarna/toml"));
+const child_process_1 = require("child_process");
 // ============================================================================
 // Constants
 // ============================================================================
@@ -50,6 +51,17 @@ const CLIX_MCP_SERVER_ENTRY = {
     command: "npx",
     args: ["-y", "@clix-so/clix-mcp-server@latest"],
 };
+const CLAUDE_CODE_MCP_ADD_ARGS = [
+    "mcp",
+    "add",
+    "--transport",
+    "stdio",
+    "clix-mcp-server",
+    "--",
+    "npx",
+    "-y",
+    "@clix-so/clix-mcp-server@latest",
+];
 // ============================================================================
 // Helper Functions
 // ============================================================================
@@ -62,6 +74,47 @@ function getErrorMessage(error) {
     }
     return String(error);
 }
+function hasClixServerInClaudeMcpListOutput(output) {
+    return output.toLowerCase().includes("clix-mcp-server");
+}
+/**
+ * Configure MCP for Claude Code using the `claude` CLI (no config file editing).
+ */
+async function configureClaudeCode() {
+    console.log(chalk_1.default.blue("Checking MCP config via Claude Code CLI (`claude mcp`)..."));
+    // Verify Claude CLI exists and supports MCP.
+    const helpRes = (0, child_process_1.spawnSync)("claude", ["mcp", "--help"], { encoding: "utf8" });
+    if (helpRes.error) {
+        console.log(chalk_1.default.yellow(`Could not run Claude CLI (${getErrorMessage(helpRes.error)}). Skipping MCP configuration.`));
+        return;
+    }
+    if (helpRes.status !== 0) {
+        console.log(chalk_1.default.yellow("Claude CLI does not appear to support `claude mcp`. Skipping MCP configuration."));
+        return;
+    }
+    // Best-effort idempotency: if list works and already contains the server, skip.
+    const listRes = (0, child_process_1.spawnSync)("claude", ["mcp", "list"], { encoding: "utf8" });
+    const listOut = `${listRes.stdout ?? ""}\n${listRes.stderr ?? ""}`;
+    if (!listRes.error && listRes.status === 0 && hasClixServerInClaudeMcpListOutput(listOut)) {
+        console.log(chalk_1.default.green("✔ Clix MCP Server is already configured."));
+        return;
+    }
+    const addRes = (0, child_process_1.spawnSync)("claude", CLAUDE_CODE_MCP_ADD_ARGS, { encoding: "utf8" });
+    if (addRes.error || addRes.status !== 0) {
+        const out = `${addRes.stdout ?? ""}\n${addRes.stderr ?? ""}`.trim();
+        console.log(chalk_1.default.yellow(`Failed to configure MCP via Claude Code CLI. ${out ? `Output:\n${out}` : "No output captured."}`));
+        return;
+    }
+    console.log(chalk_1.default.green("✔ Added Clix MCP Server to configuration. Please restart claude."));
+}
+function isClaudeCodeClient(client) {
+    const c = client.toLowerCase();
+    return (c === "claude" ||
+        c === "claude_code" ||
+        c === "claude-code" ||
+        c === "claudecode" ||
+        c === "claude code");
+}
 /**
  * Gets the MCP servers object from JSON config based on client type
  */
@@ -106,19 +159,6 @@ function getClientConfig(client) {
                 format: "json",
             };
         }
-        case "claude": {
-            let configPath = null;
-            if (process.platform === "darwin") {
-                configPath = path_1.default.join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json");
-            }
-            else if (process.platform === "win32") {
-                configPath = path_1.default.join(process.env.APPDATA || "", "Claude", "claude_desktop_config.json");
-            }
-            else if (process.platform === "linux") {
-                configPath = path_1.default.join(home, ".config", "Claude", "claude_desktop_config.json");
-            }
-            return configPath ? { path: configPath, configKey: "mcpServers", format: "json" } : null;
-        }
         case "vscode":
             return {
                 path: path_1.default.join(home, ".vscode", "mcp.json"),
@@ -306,7 +346,7 @@ async function configureMCP(client) {
                 message: "Which AI client are you using?",
                 choices: [
                     { name: "Cursor", value: "cursor" },
-                    { name: "Claude Desktop", value: "claude" },
+                    { name: "Claude Code", value: "claude" },
                     { name: "VS Code", value: "vscode" },
                     { name: "Amp", value: "amp" },
                     { name: "Kiro", value: "kiro" },
@@ -322,10 +362,19 @@ async function configureMCP(client) {
         ]);
         targetClient = answers.client;
     }
+    if (!targetClient) {
+        console.log(chalk_1.default.yellow("No client selected. Skipping MCP configuration."));
+        return;
+    }
     if (targetClient === "manual") {
         console.log(chalk_1.default.blue("Skipping automatic MCP configuration."));
         return;
     }
+    // Claude Code is configured via the `claude` CLI (no file editing).
+    if (targetClient && isClaudeCodeClient(targetClient)) {
+        await configureClaudeCode();
+        return;
+    }
     // Handle OpenCode separately (different JSON structure)
     if (targetClient === "opencode") {
         await configureOpenCode();

package/llms.txt

@@ -54,6 +54,24 @@ Integrates Clix Mobile SDK into iOS, Android, Flutter, and React Native projects
 
 ---
 
+## clix-personalization
+
+Helps developers author and debug Clix personalization templates (Liquid-style) for message content, deep links/URLs, and audience targeting. Use when the user mentions personalization variables, Liquid, templates, conditional logic, loops, filters, deep links, message logs, or when the user types `clix-personalization`.
+
+- [clix-personalization](https://raw.githubusercontent.com/clix-so/skills/refs/heads/main/skills/personalization/SKILL.md): Helps developers author and debug Clix personalization templates (Liquid-style) for message content, deep links/URLs, and audience targeting. Use when the user mentions personalization variables, Liquid, templates, conditional logic, loops, filters, deep links, message logs, or when the user types `clix-personalization`.
+
+### References
+
+- [Common Patterns (Reference)](https://raw.githubusercontent.com/clix-so/skills/refs/heads/main/skills/personalization/references/common-patterns.md): Reference documentation for personalization skill
+- [Debugging (Reference)](https://raw.githubusercontent.com/clix-so/skills/refs/heads/main/skills/personalization/references/debugging.md): Reference documentation for personalization skill
+- [Template Syntax (Reference)](https://raw.githubusercontent.com/clix-so/skills/refs/heads/main/skills/personalization/references/template-syntax.md): Reference documentation for personalization skill
+
+### Scripts
+
+- [Validate Template (Script)](https://raw.githubusercontent.com/clix-so/skills/refs/heads/main/skills/personalization/scripts/validate-template.sh): Utility script for personalization skill
+
+---
+
 ## clix-user-management
 
 Implements Clix user identification and user properties (setUserId, removeUserId, setUserProperty/setUserProperties, removeUserProperty/removeUserProperties) with safe schemas, logout best practices, and campaign-ready personalization/audience usage. Use when the user mentions login/logout, userId, user properties, personalization, audience targeting or when the user types `clix-user-management`.

package/package.json

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

package/skills/event-tracking/SKILL.md

@@ -97,7 +97,7 @@ bash <skill-dir>/scripts/validate-event-plan.sh event-plan.json
 The skill directory is typically:
 
 - `.cursor/skills/event-tracking/` (Cursor)
-- `.claude/skills/event-tracking/` (Claude Desktop)
+- `.claude/skills/event-tracking/` (Claude Code)
 - `.vscode/skills/event-tracking/` (VS Code/Amp)
 - Or check where this skill was installed
 

package/skills/integration/SKILL.md

@@ -38,11 +38,12 @@ latest verified SDK source code.
   1. **Ask the user**: "The Clix MCP Server is not detected. It provides the
      latest official SDK code. Would you like me to install it now?"
   2. **If User says YES**:
-     - Run: `bash scripts/install-mcp.sh`
+     - Run: `bash scripts/install-mcp.sh --client <your-client>`
      - The script will:
        - Verify the package is available
-       - Auto-detect the MCP client (OpenCode, Amp, Codex, Cursor, Claude
-         Desktop, VS Code, etc.)
+       - Configure the MCP server for the specified client
+       - (If you omit `--client` and multiple clients are installed, the script
+         will stop and ask you to choose.)
        - Automatically configure the MCP server in the appropriate config file
        - Provide clear instructions for restart
      - Instruct user to restart their agent/IDE to load the new server.

package/skills/integration/references/mcp-integration.md

@@ -263,26 +263,6 @@ claude mcp add --transport stdio clix-mcp-server -- npx -y @clix-so/clix-mcp-ser
 }
 ```
 
-#### Claude Desktop App
-
-**Setup**
-
-1. Open config
-   (`~/Library/Application Support/Claude/claude_desktop_config.json` or
-   `%APPDATA%\\Claude\\claude_desktop_config.json`).
-2. Add and restart:
-
-```json
-{
-  "mcpServers": {
-    "clix-mcp-server": {
-      "command": "npx",
-      "args": ["-y", "@clix-so/clix-mcp-server@latest"]
-    }
-  }
-}
-```
-
 #### Amp
 
 **Setup**