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

package/README.md

@@ -21,6 +21,9 @@ by AI clients.
 - **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
+- **clix-skill-creator**: Create new Clix agent skills by researching Clix SDK +
+  docs via Clix MCP Server, then generating a complete skill folder (SKILL.md,
+  references, scripts, examples) aligned with this repo’s conventions
 
 ## Installing Skills
 
@@ -68,7 +71,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, personalization, api-triggered-campaigns
+# This will install: integration, event-tracking, user-management, personalization, api-triggered-campaigns, skill-creator
 
 # Install all available skills globally (system root)
 npx @clix-so/clix-agent-skills@latest install --all --client cursor --global
@@ -78,13 +81,13 @@ npx @clix-so/clix-agent-skills@latest install --all --client cursor --global
 
 | Client         | Flag                                 | Default Path       |
 | -------------- | ------------------------------------ | ------------------ |
-| Amp            | `--client amp`                       | `.amp/skills/`     |
+| Amp            | `--client amp`                       | `.agents/skills/`  |
 | Claude Code    | `--client claude` (or `claude-code`) | `.claude/skills/`  |
 | Codex          | `--client codex`                     | `.codex/skills/`   |
 | Cursor         | `--client cursor`                    | `.cursor/skills/`  |
 | Gemini CLI     | `--client gemini`                    | `.gemini/skills/`  |
 | GitHub Copilot | `--client github`                    | `.github/skills/`  |
-| Goose          | `--client goose`                     | `.goose/skills/`   |
+| Goose          | `--client goose`                     | `.agents/skills/`  |
 | Letta          | `--client letta`                     | `.skills/`         |
 | OpenCode       | `--client opencode`                  | `.opencode/skill/` |
 | VS Code        | `--client vscode`                    | `.vscode/skills/`  |
@@ -103,7 +106,7 @@ To install specific skills:
 1. Visit the Marketplace section in `/plugin`
 2. Select `Browse plugins`
 3. Choose the skills you wish to install
-4. Install skill
+4. Install your preferred skill
 
 Alternatively, you can install a single skill directly by running:
 

package/dist/bin/commands/install.js

@@ -67,7 +67,9 @@ async function installSkill(skillName, options) {
                 relativeDest = ".amazonq/skills";
                 break;
             case "amp":
-                relativeDest = ".amp/skills";
+                // Amp looks for workspace skills in `.agents/skills/` and user skills in `~/.config/agents/skills/`.
+                // We map `--global` to the user-level location.
+                relativeDest = options.global ? ".config/agents/skills" : ".agents/skills";
                 break;
             case "claude":
             case "claude-code":
@@ -92,7 +94,11 @@ async function installSkill(skillName, options) {
                 relativeDest = ".skills";
                 break;
             case "goose":
-                relativeDest = ".goose/skills";
+                // Goose supports portable skill locations too:
+                // - project: `./.agents/skills/`
+                // - global : `~/.config/agents/skills/`
+                // We default to the portable locations, but users can still override via --path.
+                relativeDest = options.global ? ".config/agents/skills" : ".agents/skills";
                 break;
             case "kiro":
                 relativeDest = ".kiro/skills";

package/llms.txt

@@ -9,9 +9,7 @@ Each entry includes the file path, type, and description for semantic search.
 
 ## clix-api-triggered-campaigns
 
-Helps developers configure API-triggered campaigns in the Clix console and trigger them from backend services with safe auth, payload schemas, dynamic audience filters (trigger.*), and personalization best practices. Use when the user mentions transactional notifications, backend-triggered sends, campaign_id trigger APIs, or "API-triggered campaigns".
-
-- [clix-api-triggered-campaigns](https://raw.githubusercontent.com/clix-so/skills/refs/heads/main/skills/api-triggered-campaigns/SKILL.md): Helps developers configure API-triggered campaigns in the Clix console and trigger them from backend services with safe auth, payload schemas, dynamic audience filters (trigger.*), and personalization best practices. Use when the user mentions transactional notifications, backend-triggered sends, campaign_id trigger APIs, or "API-triggered campaigns".
+- [clix-api-triggered-campaigns](https://raw.githubusercontent.com/clix-so/skills/refs/heads/main/skills/api-triggered-campaigns/SKILL.md): Main skill documentation
 
 ### References
 
@@ -35,9 +33,7 @@ Helps developers configure API-triggered campaigns in the Clix console and trigg
 
 ## clix-event-tracking
 
-Implements Clix event tracking (Clix.trackEvent) with consistent naming, safe property schemas, and campaign-ready validation. Use when adding, reviewing, or debugging event tracking; when configuring event-triggered campaigns; or when the user mentions events, tracking, funnels, or properties — or when the user types `clix-event-tracking`.
-
-- [clix-event-tracking](https://raw.githubusercontent.com/clix-so/skills/refs/heads/main/skills/event-tracking/SKILL.md): Implements Clix event tracking (Clix.trackEvent) with consistent naming, safe property schemas, and campaign-ready validation. Use when adding, reviewing, or debugging event tracking; when configuring event-triggered campaigns; or when the user mentions events, tracking, funnels, or properties — or when the user types `clix-event-tracking`.
+- [clix-event-tracking](https://raw.githubusercontent.com/clix-so/skills/refs/heads/main/skills/event-tracking/SKILL.md): Main skill documentation
 
 ### References
 
@@ -55,9 +51,7 @@ Implements Clix event tracking (Clix.trackEvent) with consistent naming, safe pr
 
 ## clix-integration
 
-Integrates Clix Mobile SDK into iOS, Android, Flutter, and React Native projects. Provides step-by-step guidance for installation, initialization, and verification. Use when the user asks to install, setup, integrate Clix or when the user types `clix-integration` / "clix integration".
-
-- [clix-integration](https://raw.githubusercontent.com/clix-so/skills/refs/heads/main/skills/integration/SKILL.md): Integrates Clix Mobile SDK into iOS, Android, Flutter, and React Native projects. Provides step-by-step guidance for installation, initialization, and verification. Use when the user asks to install, setup, integrate Clix or when the user types `clix-integration` / "clix integration".
+- [clix-integration](https://raw.githubusercontent.com/clix-so/skills/refs/heads/main/skills/integration/SKILL.md): Main skill documentation
 
 ### References
 
@@ -82,9 +76,7 @@ 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`.
+- [clix-personalization](https://raw.githubusercontent.com/clix-so/skills/refs/heads/main/skills/personalization/SKILL.md): Main skill documentation
 
 ### References
 
@@ -98,11 +90,30 @@ Helps developers author and debug Clix personalization templates (Liquid-style)
 
 ---
 
-## clix-user-management
+## clix-skill-creator
+
+- [clix-skill-creator](https://raw.githubusercontent.com/clix-so/skills/refs/heads/main/skills/skill-creator/SKILL.md): Main skill documentation
+
+### References
+
+- [Mcp Research Playbook (Reference)](https://raw.githubusercontent.com/clix-so/skills/refs/heads/main/skills/skill-creator/references/mcp-research-playbook.md): Reference documentation for skill-creator skill
+- [Skill Template (Reference)](https://raw.githubusercontent.com/clix-so/skills/refs/heads/main/skills/skill-creator/references/skill-template.md): Reference documentation for skill-creator skill
 
-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`.
+### Examples
+
+- [Skill Brief Example (Example)](https://raw.githubusercontent.com/clix-so/skills/refs/heads/main/skills/skill-creator/examples/skill-brief-example.yaml): Code example for skill-creator skill
+
+### Scripts
+
+- [Validate Same Scope (Script)](https://raw.githubusercontent.com/clix-so/skills/refs/heads/main/skills/skill-creator/scripts/validate-same-scope.sh): Utility script for skill-creator skill
+- [Validate Skill Location (Script)](https://raw.githubusercontent.com/clix-so/skills/refs/heads/main/skills/skill-creator/scripts/validate-skill-location.sh): Utility script for skill-creator skill
+- [Validate Skill Scaffold (Script)](https://raw.githubusercontent.com/clix-so/skills/refs/heads/main/skills/skill-creator/scripts/validate-skill-scaffold.sh): Utility script for skill-creator skill
+
+---
+
+## clix-user-management
 
-- [clix-user-management](https://raw.githubusercontent.com/clix-so/skills/refs/heads/main/skills/user-management/SKILL.md): 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`.
+- [clix-user-management](https://raw.githubusercontent.com/clix-so/skills/refs/heads/main/skills/user-management/SKILL.md): Main skill documentation
 
 ### References
 

package/package.json

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

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

@@ -2,8 +2,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
+description: Helps developers configure API-triggered campaigns in the Clix console and
   trigger them from backend services with safe auth, payload schemas, dynamic
   audience filters (trigger.*), and personalization best practices. Use when the
   user mentions transactional notifications, backend-triggered sends,

package/skills/event-tracking/SKILL.md

@@ -2,8 +2,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
+description: Implements Clix event tracking (Clix.trackEvent) with consistent naming, safe
   property schemas, and campaign-ready validation. Use when adding, reviewing,
   or debugging event tracking; when configuring event-triggered campaigns; or
   when the user mentions events, tracking, funnels, or properties — or when the
@@ -101,7 +100,8 @@ The skill directory is typically:
 
 - `.cursor/skills/event-tracking/` (Cursor)
 - `.claude/skills/event-tracking/` (Claude Code)
-- `.vscode/skills/event-tracking/` (VS Code/Amp)
+- `.vscode/skills/event-tracking/` (VS Code)
+- `.agents/skills/event-tracking/` (Amp)
 - Or check where this skill was installed
 
 If validation fails: fix the plan first, then implement.

package/skills/integration/SKILL.md

@@ -2,8 +2,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
+description: Integrates Clix Mobile SDK into iOS, Android, Flutter, and React Native
   projects. Provides step-by-step guidance for installation, initialization, and
   verification. Use when the user asks to install, setup, integrate Clix or when
   the user types `clix-integration` / "clix integration".

package/skills/integration/references/error-handling.md

@@ -241,8 +241,7 @@ try {
 ### Provide Fallbacks
 
 ```typescript
-const projectId =
-  process.env.CLIX_PROJECT_ID || process.env.REACT_APP_CLIX_PROJECT_ID || "";
+const projectId = process.env.CLIX_PROJECT_ID || process.env.REACT_APP_CLIX_PROJECT_ID || "";
 
 if (!projectId) {
   console.warn("Clix: No project ID found, analytics disabled");

package/skills/personalization/SKILL.md

@@ -2,8 +2,7 @@
 name: clix-personalization
 display-name: Personalization
 short-description: Personalization templates
-description:
-  Helps developers author and debug Clix personalization templates
+description: 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

package/skills/skill-creator/LICENSE.txt

@@ -0,0 +1,204 @@
+Copyright (c) 2026 Clix (https://clix.so/)
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright (c) 2026 Clix (https://clix.so/)
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+

package/skills/skill-creator/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: clix-skill-creator
+display-name: Skill Creator
+short-description: Generate new Clix agent skills
+description: Helps authors create new Clix agent skills by first researching the latest Clix
+  SDK + docs via the Clix MCP Server, then generating a complete skill folder
+  (SKILL.md, references, scripts, examples) aligned with the conventions in this
+  repository. Use when the user asks to create/author a new Clix skill, extend
+  the skills library, or when the user types `clix-skill-creator`.
+user-invocable: true
+---
+
+# Clix Skill Creator
+
+Use this skill to **create a new Clix skill** that matches a user's need, while
+avoiding duplicated scope and **preventing hallucinated API usage** by relying
+on the Clix MCP server as the source of truth.
+
+This is a “meta-skill”: it does not integrate an SDK directly; it guides you to
+produce **another skill folder** (docs + deterministic scripts) that does.
+
+## When to use this skill
+
+- User says: “Create a new skill for Clix that helps with X”
+- Internal request: “We need a new skill for feature X in Clix”
+- User provides a workflow that is not well-covered by existing skills
+- User types: `clix-skill-creator`
+
+## Non-goals (important)
+
+- Do **not** create a new skill if the request can be satisfied by combining
+  existing skills (integration + event tracking + personalization + user
+  management + API-triggered campaigns).
+- Do **not** invent SDK methods, endpoints, or constraints. If you can’t confirm
+  via MCP, treat it as unknown and ask the user or add a TODO note.
+- Do **not** embed secrets, project IDs, API keys, or customer data in the skill.
+
+## MCP-first (mandatory source of truth)
+
+Before writing any new “Clix API behavior” or “SDK signature” into a newly
+generated skill:
+
+- **MUST** use `clix-mcp-server:search_docs` to confirm conceptual behavior,
+  limits, and console semantics.
+- **MUST** use `clix-mcp-server:search_sdk` to confirm exact method signatures
+  for each platform (iOS/Android/Flutter/React Native) that the new skill will
+  mention.
+
+If `clix-mcp-server` tools are not available:
+
+- Ask the user whether to install the MCP server (prefer using the existing
+  installer in `skills/integration/scripts/install-mcp.sh`).
+- If the user declines, proceed with an explicit “static fallback may be
+  outdated” warning and minimize hard claims.
+
+## Workflow (copy + check off)
+
+```
+Clix skill creation progress:
+- [ ] 1) Intake: user need → crisp problem statement + acceptance criteria
+- [ ] 2) Scope check: confirm this isn’t already covered by existing skills
+- [ ] 3) MCP research: gather evidence (docs + SDK signatures) for the target scope
+- [ ] 4) Draft a Skill Brief (name, trigger phrases, inputs/outputs, guardrails)
+- [ ] 5) Generate scaffold (SKILL.md + references/ + scripts/ + examples/)
+- [ ] 6) Validate scaffold (structure + frontmatter + MCP-first section)
+- [ ] 7) Wire-in (README + llms index + tests if needed)
+```
+
+## 1) Intake: minimum questions
+
+Ask only what’s needed to define a stable skill boundary:
+
+- **Goal**: what outcome should the skill reliably produce?
+- **Audience**: app devs, backend devs, marketers/ops, or mixed?
+- **Platform** (if SDK-related): iOS / Android / Flutter / React Native
+- **Clix capability**: push / in-app / email / audiences / journeys / etc.
+- **Constraints**: PII policy, compliance, performance limits, rate limits
+- **Success criteria**: what does “done” look like?
+
+## 2) Reference official skills (match repo style)
+
+Before creating a new skill, use the existing **official Clix skills** in this
+repo as your style guide so the generated skill matches the standards here
+(format, tone, workflow, validators), while still being tailored to the user’s
+need.
+
+- Study how they are written:
+  - YAML frontmatter conventions
+  - MCP-first “source of truth” behavior
+  - Progressive disclosure (`references/`, `scripts/`, `examples/`)
+  - Plan artifacts + deterministic validators (bash scripts)
+- Then generate the new skill based on the user’s need using the same patterns.
+  If the need is clearly a tiny addition to an existing skill, prefer adding a
+  `references/` doc or `examples/` file there instead of creating a new skill.
+
+- `clix-integration`
+- `clix-event-tracking`
+- `clix-user-management`
+- `clix-personalization`
+- `clix-api-triggered-campaigns`
+
+## 3) MCP research: build an “Evidence Pack”
+
+Create a short evidence pack that you will cite while writing the new skill:
+
+- **Docs evidence** (from `clix-mcp-server:search_docs`)
+  - behavior guarantees
+  - constraints/limits
+  - console terminology
+- **SDK evidence** (from `clix-mcp-server:search_sdk`)
+  - exact signatures per platform
+  - initialization / required params
+  - error behavior (throws? returns promise?)
+
+Store the evidence in your notes (or as a `references/` markdown file in the new
+skill), with the search queries you used so future maintainers can refresh it.
+
+## 4) Draft a Skill Brief (output format)
+
+Produce this brief for approval _before_ generating files:
+
+```yaml
+skill:
+  folder_name: "<kebab-case>" # e.g. "push-troubleshooting"
+  name: "clix-<kebab-case>" # e.g. "clix-push-troubleshooting"
+  display_name: "<Title Case>"
+  short_description: "<short>"
+  description: "<2-3 lines>"
+  user_invocable: true
+
+triggers:
+  - "phrases the user might say"
+
+inputs:
+  - "minimal inputs the skill will ask for"
+
+outputs:
+  - "artifacts the skill produces (plan JSON, code changes, checklists)"
+
+guardrails:
+  - "MCP-first requirements"
+  - "security / PII constraints"
+
+files_to_generate:
+  skill_md: true
+  references:
+    - "<doc>.md"
+  scripts:
+    - "<script>.sh"
+  examples:
+    - "<optional>"
+```
+
+## 5) Generate scaffold (repo conventions)
+
+In this repository, a “complete” skill folder should include:
+
+- `SKILL.md` (with YAML frontmatter; MCP-first; workflow; progressive disclosure)
+- `LICENSE.txt`
+- `references/` (markdown docs; not empty)
+- `scripts/` (deterministic bash scripts; not empty)
+- `examples/` (optional, but recommended when copy/paste code is useful)
+
+## 6) Validate scaffold (fast feedback loop)
+
+After generating a new skill folder, validate it:
+
+```bash
+bash <skill-dir>/scripts/validate-same-scope.sh path/to/installed/skill-creator path/to/new-skill-folder
+bash <skill-dir>/scripts/validate-skill-location.sh path/to/new-skill-folder --mode repo
+bash <skill-dir>/scripts/validate-skill-scaffold.sh path/to/new-skill-folder
+```
+
+This should check:
+
+- the new skill is installed at the **same scope** as `skill-creator` (project-level
+  vs user-level), i.e. the new skill folder lives next to the installed
+  `skill-creator` under the same `.../skills/` directory
+- the skill folder is in the correct `skills/<name>/` location (for this repo)
+- required files exist
+- `references/` and `scripts/` are present and non-empty
+- `SKILL.md` has valid frontmatter keys
+- the skill includes an MCP-first section referencing `clix-mcp-server`
+
+## Progressive Disclosure
+
+- **Level 1**: This `SKILL.md` (always loaded)
+- **Level 2**: `references/` (load when authoring the new skill)
+- **Level 3**: `examples/` (load when copy/pasting scaffolds)
+- **Level 4**: `scripts/` (execute directly; do not load into context)
+
+## References
+
+- `references/skill-template.md`
+- `references/mcp-research-playbook.md`

package/skills/skill-creator/examples/skill-brief-example.yaml

@@ -0,0 +1,41 @@
+skill:
+  folder_name: 'push-troubleshooting'
+  name: 'clix-push-troubleshooting'
+  display_name: 'Push Troubleshooting'
+  short_description: 'Debug push delivery and rendering issues'
+  description: >
+    Helps developers diagnose push notification delivery, permissions, token
+    registration, and template rendering issues. Uses Clix MCP Server as the
+    source of truth for SDK signatures and docs behavior.
+  user_invocable: true
+
+triggers:
+  - 'push notifications not arriving'
+  - 'APNs token not registered'
+  - 'FCM token changed'
+  - 'message logs show template error'
+
+inputs:
+  - 'platform (iOS/Android/Flutter/React Native)'
+  - 'app state (fresh install vs update)'
+  - 'what you see in Clix Message Logs (if available)'
+
+outputs:
+  - 'a step-by-step debug plan'
+  - 'a minimal repro checklist'
+  - 'code changes (if needed) to fix initialization/token registration'
+
+guardrails:
+  - 'MCP-first: do not claim SDK signatures without clix-mcp-server:search_sdk'
+  - 'no secrets; redact tokens and IDs'
+  - 'avoid duplicated scope with clix-integration unless troubleshooting-specific'
+
+files_to_generate:
+  skill_md: true
+  references:
+    - 'debugging-checklist.md'
+    - 'common-failure-modes.md'
+  scripts:
+    - 'validate-debug-plan.sh'
+  examples:
+    - 'sample-log-snippets.md'

package/skills/skill-creator/references/mcp-research-playbook.md

@@ -0,0 +1,75 @@
+# MCP Research Playbook (Clix)
+
+This playbook helps you **research accurately** before authoring a new Clix
+skill. The goal is to collect enough evidence so the skill can be maintained
+without guessing.
+
+## Golden rules
+
+- **SDK signatures must come from** `clix-mcp-server:search_sdk` (not memory).
+- **Behavior/limits must come from** `clix-mcp-server:search_docs`.
+- When evidence is unclear, write that uncertainty into the skill and ask the
+  user for confirmation instead of asserting.
+
+## Recommended research sequence
+
+### 1) Identify the “feature nouns”
+
+Extract the keywords from the user need:
+
+- Channel: push / in-app / email / SMS / etc.
+- Trigger type: event-triggered / API-triggered / scheduled
+- Domain: journeys, segments, templates, attribution, deep links, etc.
+- Platform: iOS / Android / Flutter / React Native (if SDK involved)
+
+### 2) Search docs first (conceptual contracts)
+
+Use `clix-mcp-server:search_docs` queries like:
+
+- `"<feature> limits"`
+- `"<feature> troubleshooting"`
+- `"<feature> required fields"`
+- `"<endpoint or concept> authentication headers"`
+- `"Message Logs template rendering errors"`
+
+Record:
+
+- constraints/limits (e.g. maximum attributes, payload limits)
+- required fields
+- “this is how the console behaves” statements
+
+### 3) Search SDK next (exact signatures)
+
+Use `clix-mcp-server:search_sdk` queries like:
+
+- `"initialize"`
+- `"setUserId"`
+- `"setUserProperty"`
+- `"trackEvent"`
+- `"push token"`
+- `"<feature name>"` + platform filters
+
+For each platform you care about, capture:
+
+- method name + parameters (types if available)
+- return type (sync vs async)
+- error behavior (throws? returns error object?)
+
+### 4) Convert evidence into a skill contract
+
+In the new skill’s `SKILL.md`:
+
+- include an MCP-first section
+- include concrete “workflow” steps
+- avoid large static API tables unless you can keep them synced (prefer “use MCP
+  to fetch the exact signature” instead)
+
+## Suggested “Evidence Pack” format
+
+In the new skill’s `references/`, create an `evidence.md` (or similar) containing:
+
+- the **queries** you ran
+- the **high-signal excerpts** (short)
+- a short “what we conclude” paragraph per excerpt
+
+This makes maintenance and debugging dramatically easier.

package/skills/skill-creator/references/skill-template.md

@@ -0,0 +1,74 @@
+# Skill Template (for new Clix skills)
+
+This document is a **copy/paste scaffold** for creating a new skill in the style
+of this repository.
+
+## Folder structure
+
+Create:
+
+- `skills/<folder-name>/SKILL.md`
+- `skills/<folder-name>/LICENSE.txt`
+- `skills/<folder-name>/references/<docs>.md` (at least 1 file)
+- `skills/<folder-name>/scripts/<script>.sh` (at least 1 file)
+- `skills/<folder-name>/examples/` (optional but recommended)
+
+## `SKILL.md` skeleton
+
+```markdown
+---
+name: clix-<kebab-case>
+display-name: <Title Case>
+short-description: <short>
+description: <2-3 lines. Include when to use. Mention MCP-first explicitly.>
+user-invocable: true
+---
+
+# <Title Case>
+
+## What this skill does
+
+- ...
+
+## MCP-first (source of truth)
+
+If Clix MCP tools are available, treat them as the **source of truth**:
+
+- `clix-mcp-server:search_docs` for conceptual behavior + limits
+- `clix-mcp-server:search_sdk` for platform signatures (when SDK calls are involved)
+
+If MCP tools are not available:
+
+- Ask to install MCP (preferred), otherwise use references/ and clearly warn that
+  static docs may be outdated.
+
+## Workflow (copy + check off)
+```
+
+<Skill> progress:
+
+- [ ] 1. Confirm minimum inputs
+- [ ] 2. Draft a plan artifact (JSON / checklist / table)
+- [ ] 3. Validate plan (script)
+- [ ] 4. Implement (code/config)
+- [ ] 5. Verify (Clix console + runtime)
+
+```
+
+## Progressive Disclosure
+
+- **Level 1**: This `SKILL.md`
+- **Level 2**: `references/`
+- **Level 3**: `examples/`
+- **Level 4**: `scripts/` (execute; do not load)
+```
+
+## Quality checklist (before publishing)
+
+- **No hallucinations**: every SDK signature in the skill can be re-derived from
+  `clix-mcp-server:search_sdk` queries documented in references.
+- **No secrets**: no project IDs / API keys / customer data in examples.
+- **Scope crisp**: the skill does one job well; if it’s a grab bag, split it.
+- **Backstops**: include a deterministic script for validating the “plan artifact”
+  (JSON schema or structure checks).
+- **Good UX**: minimal intake questions; concrete outputs the user can approve.

package/skills/skill-creator/scripts/validate-same-scope.sh

@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+#
+# Validate that a newly generated skill is installed at the same scope as this skill:
+# it must live under the same parent "skills" directory as the installed `skill-creator`.
+#
+# Rationale:
+# - If `skill-creator` is installed at project level (e.g. .cursor/skills/skill-creator),
+#   the generated skill should also be project level (e.g. .cursor/skills/<new-skill>).
+# - If `skill-creator` is installed at user/global level (e.g. ~/.cursor/skills/skill-creator),
+#   the generated skill should also be user/global (e.g. ~/.cursor/skills/<new-skill>).
+#
+# Usage:
+#   bash skills/skill-creator/scripts/validate-same-scope.sh <skill-creator-dir> <new-skill-dir>
+#
+set -euo pipefail
+
+creator_dir="${1:-}"
+new_skill_dir="${2:-}"
+
+if [[ -z "$creator_dir" || -z "$new_skill_dir" ]]; then
+  echo "Usage: bash skills/skill-creator/scripts/validate-same-scope.sh <skill-creator-dir> <new-skill-dir>" >&2
+  exit 2
+fi
+
+if [[ ! -d "$creator_dir" ]]; then
+  echo "Error: skill-creator directory not found: $creator_dir" >&2
+  exit 2
+fi
+
+if [[ ! -d "$new_skill_dir" ]]; then
+  echo "Error: new skill directory not found: $new_skill_dir" >&2
+  exit 2
+fi
+
+creator_parent="$(dirname "$creator_dir")"
+new_parent="$(dirname "$new_skill_dir")"
+
+creator_parent_base="$(basename "$creator_parent")"
+new_parent_base="$(basename "$new_parent")"
+
+if [[ "$creator_parent_base" != "skills" && "$creator_parent_base" != "skill" && "$creator_parent_base" != ".skills" ]]; then
+  echo "ERROR: skill-creator must live under a skills directory (skills/ or skill/ or .skills/)." >&2
+  echo "  creator_dir: $creator_dir" >&2
+  exit 1
+fi
+
+if [[ "$new_parent_base" != "skills" && "$new_parent_base" != "skill" && "$new_parent_base" != ".skills" ]]; then
+  echo "ERROR: new skill must live under a skills directory (skills/ or skill/ or .skills/)." >&2
+  echo "  new_skill_dir: $new_skill_dir" >&2
+  exit 1
+fi
+
+if [[ "$creator_parent" != "$new_parent" ]]; then
+  echo "ERROR: scope mismatch. Expected new skill to be installed next to skill-creator under the same skills directory." >&2
+  echo "  skill_creator_parent: $creator_parent" >&2
+  echo "  new_skill_parent:     $new_parent" >&2
+  exit 1
+fi
+
+echo "OK: skill scope matches (same parent skills directory)"
+

package/skills/skill-creator/scripts/validate-skill-location.sh

@@ -0,0 +1,204 @@
+#!/usr/bin/env bash
+#
+# Validate that a generated skill folder is placed in the correct "skills" directory.
+#
+# Usage:
+#   bash skills/skill-creator/scripts/validate-skill-location.sh <skill-folder> [--mode repo|client] [--client <name>]
+#
+# Modes:
+# - repo  : expects the skill folder to live under: skills/<skill-folder-name>/
+# - client: expects the skill folder to live under a client skills directory:
+#           (.*)/skills/<skill-folder-name>/  OR  (.*)/skill/<skill-folder-name>/ (OpenCode)
+#
+# If --client is provided in client mode, this script will also check that the path
+# contains the expected client directory segment (best-effort).
+#
+set -euo pipefail
+
+skill_dir="${1:-}"
+mode="repo"
+client=""
+
+shift || true
+while [[ "${1:-}" != "" ]]; do
+  case "$1" in
+    --mode)
+      if [[ -z "${2:-}" || "${2:-}" == "-"* ]]; then
+        echo "Error: --mode requires a value" >&2
+        exit 2
+      fi
+      mode="${2:-}"
+      shift 2
+      ;;
+    --client)
+      if [[ -z "${2:-}" || "${2:-}" == "-"* ]]; then
+        echo "Error: --client requires a value" >&2
+        exit 2
+      fi
+      client="${2:-}"
+      shift 2
+      ;;
+    -h|--help)
+      cat <<'EOF'
+Validate skill folder location.
+
+Usage:
+  bash skills/skill-creator/scripts/validate-skill-location.sh <skill-folder> [--mode repo|client] [--client <name>]
+
+Examples:
+  bash skills/skill-creator/scripts/validate-skill-location.sh skills/personalization --mode repo
+  bash skills/skill-creator/scripts/validate-skill-location.sh .cursor/skills/personalization --mode client --client cursor
+EOF
+      exit 0
+      ;;
+    *)
+      echo "Unknown arg: $1" >&2
+      exit 2
+      ;;
+  esac
+done
+
+if [[ -z "$skill_dir" ]]; then
+  echo "Error: missing <skill-folder> argument" >&2
+  exit 2
+fi
+
+if [[ ! -d "$skill_dir" ]]; then
+  echo "Error: directory not found: $skill_dir" >&2
+  exit 2
+fi
+
+skills_parent="$(basename "$(dirname "$skill_dir")")"
+
+case "$mode" in
+  repo)
+    if [[ "$skills_parent" != "skills" ]]; then
+      echo "ERROR: Invalid location: expected skill folder under 'skills/<name>/' but got parent '$skills_parent'." >&2
+      echo "   Path: $skill_dir" >&2
+      exit 1
+    fi
+    ;;
+  client)
+    # Client installs usually use "skills/" (most clients), "skill/" (OpenCode),
+    # or ".skills/" (Letta).
+    if [[ "$skills_parent" != "skills" && "$skills_parent" != "skill" && "$skills_parent" != ".skills" ]]; then
+      echo "ERROR: Invalid location: expected skill folder under '<client>/(skills|skill|.skills)/<name>/' but got parent '$skills_parent'." >&2
+      echo "   Path: $skill_dir" >&2
+      exit 1
+    fi
+
+    if [[ -n "$client" ]]; then
+      # Best-effort path segment checks (not exhaustive, but catches common mistakes).
+      case "${client,,}" in
+        cursor)
+          [[ "$skill_dir" == *"/.cursor/skills/"* || "$skill_dir" == ".cursor/skills/"* ]] || {
+            echo "ERROR: Expected Cursor skill path to include '.cursor/skills/'" >&2
+            echo "   Path: $skill_dir" >&2
+            exit 1
+          }
+          ;;
+        claude|claude-code)
+          [[ "$skill_dir" == *"/.claude/skills/"* || "$skill_dir" == ".claude/skills/"* ]] || {
+            echo "ERROR: Expected Claude skill path to include '.claude/skills/'" >&2
+            echo "   Path: $skill_dir" >&2
+            exit 1
+          }
+          ;;
+        codex)
+          [[ "$skill_dir" == *"/.codex/skills/"* || "$skill_dir" == ".codex/skills/"* ]] || {
+            echo "ERROR: Expected Codex skill path to include '.codex/skills/'" >&2
+            echo "   Path: $skill_dir" >&2
+            exit 1
+          }
+          ;;
+        opencode)
+          [[ "$skill_dir" == *"/.opencode/skill/"* || "$skill_dir" == ".opencode/skill/"* ]] || {
+            echo "ERROR: Expected OpenCode skill path to include '.opencode/skill/'" >&2
+            echo "   Path: $skill_dir" >&2
+            exit 1
+          }
+          # OpenCode uses singular "skill", reject "skills" for this client.
+          [[ "$skill_dir" != *"/.opencode/skills/"* && "$skill_dir" != ".opencode/skills/"* ]] || {
+            echo "ERROR: Expected OpenCode skill path to include '.opencode/skill/' (singular), not '.opencode/skills/'" >&2
+            echo "   Path: $skill_dir" >&2
+            exit 1
+          }
+          ;;
+        vscode)
+          [[ "$skill_dir" == *"/.vscode/skills/"* || "$skill_dir" == ".vscode/skills/"* ]] || {
+            echo "ERROR: Expected VS Code skill path to include '.vscode/skills/'" >&2
+            echo "   Path: $skill_dir" >&2
+            exit 1
+          }
+          ;;
+        amp)
+          # Amp uses `.agents/skills/` in a workspace and `~/.config/agents/skills/` globally.
+          [[ "$skill_dir" == *"/.agents/skills/"* || "$skill_dir" == ".agents/skills/"* ]] || {
+            echo "ERROR: Expected Amp skill path to include '.agents/skills/'" >&2
+            echo "   Path: $skill_dir" >&2
+            exit 1
+          }
+          ;;
+        goose)
+          # Goose supports both goose-specific and portable skill locations.
+          [[
+            "$skill_dir" == *"/.goose/skills/"* ||
+            "$skill_dir" == ".goose/skills/"* ||
+            "$skill_dir" == *"/.agents/skills/"* ||
+            "$skill_dir" == ".agents/skills/"*
+          ]] || {
+            echo "ERROR: Expected Goose skill path to include '.goose/skills/' or '.agents/skills/'" >&2
+            echo "   Path: $skill_dir" >&2
+            exit 1
+          }
+          ;;
+        github|copilot)
+          [[ "$skill_dir" == *"/.github/skills/"* || "$skill_dir" == ".github/skills/"* ]] || {
+            echo "ERROR: Expected GitHub Copilot skill path to include '.github/skills/'" >&2
+            echo "   Path: $skill_dir" >&2
+            exit 1
+          }
+          ;;
+        gemini)
+          [[ "$skill_dir" == *"/.gemini/skills/"* || "$skill_dir" == ".gemini/skills/"* ]] || {
+            echo "ERROR: Expected Gemini skill path to include '.gemini/skills/'" >&2
+            echo "   Path: $skill_dir" >&2
+            exit 1
+          }
+          ;;
+        kiro)
+          [[ "$skill_dir" == *"/.kiro/skills/"* || "$skill_dir" == ".kiro/skills/"* ]] || {
+            echo "ERROR: Expected Kiro skill path to include '.kiro/skills/'" >&2
+            echo "   Path: $skill_dir" >&2
+            exit 1
+          }
+          ;;
+        amazonq)
+          [[ "$skill_dir" == *"/.amazonq/skills/"* || "$skill_dir" == ".amazonq/skills/"* ]] || {
+            echo "ERROR: Expected AmazonQ skill path to include '.amazonq/skills/'" >&2
+            echo "   Path: $skill_dir" >&2
+            exit 1
+          }
+          ;;
+        letta)
+          # Letta uses a root-level `.skills/` directory.
+          [[ "$skill_dir" == *"/.skills/"* || "$skill_dir" == ".skills/"* ]] || {
+            echo "ERROR: Expected Letta skill path to include '.skills/'" >&2
+            echo "   Path: $skill_dir" >&2
+            exit 1
+          }
+          ;;
+        *)
+          # Unknown client; skip strict segment check.
+          ;;
+      esac
+    fi
+    ;;
+  *)
+    echo "Error: --mode must be 'repo' or 'client' (got '$mode')" >&2
+    exit 2
+    ;;
+esac
+
+echo "OK: skill location looks OK ($mode)"
+

package/skills/skill-creator/scripts/validate-skill-scaffold.sh

@@ -0,0 +1,207 @@
+#!/usr/bin/env bash
+#
+# Validate a Clix Agent Skill scaffold (folder structure + frontmatter).
+#
+# Usage:
+#   bash skills/skill-creator/scripts/validate-skill-scaffold.sh path/to/skill-folder
+#
+# Validates:
+# - SKILL.md and LICENSE.txt exist
+# - references/ and scripts/ exist and are non-empty
+# - SKILL.md has YAML frontmatter with required keys
+# - SKILL.md contains an MCP-first section that references `clix-mcp-server`
+#
+set -euo pipefail
+
+skill_dir="${1:-}"
+if [[ -z "$skill_dir" ]]; then
+  echo "Usage: bash skills/skill-creator/scripts/validate-skill-scaffold.sh path/to/skill-folder" >&2
+  exit 2
+fi
+
+if [[ ! -d "$skill_dir" ]]; then
+  echo "Error: directory not found: $skill_dir" >&2
+  exit 2
+fi
+
+validate_with_python() {
+  python3 - "$skill_dir" <<'PY'
+import os
+import re
+import sys
+
+skill_dir = sys.argv[1]
+
+errors = []
+
+def require_file(name: str):
+  p = os.path.join(skill_dir, name)
+  if not os.path.isfile(p):
+    errors.append(f"missing required file: {name}")
+  return p
+
+def require_non_empty_dir(name: str):
+  p = os.path.join(skill_dir, name)
+  if not os.path.isdir(p):
+    errors.append(f"missing required directory: {name}/")
+    return
+  entries = [e for e in os.listdir(p) if not e.startswith(".")]
+  if len(entries) == 0:
+    errors.append(f"required directory is empty: {name}/")
+
+skill_md_path = require_file("SKILL.md")
+require_file("LICENSE.txt")
+require_non_empty_dir("references")
+require_non_empty_dir("scripts")
+
+frontmatter = None
+try:
+  with open(skill_md_path, "r", encoding="utf-8") as f:
+    content = f.read()
+except Exception as e:
+  errors.append(f"failed to read SKILL.md: {e}")
+  content = ""
+
+m = re.match(r"^---\n([\s\S]*?)\n---\n", content)
+if not m:
+  errors.append("SKILL.md must start with YAML frontmatter delimited by ---")
+else:
+  frontmatter = m.group(1)
+  # IMPORTANT: avoid substring false-positives:
+  # - "display-name:" contains "name:"
+  # - "short-description:" contains "description:"
+  # So we must match keys at beginning-of-line only.
+  def has_key(key: str) -> bool:
+    return re.search(rf"^{re.escape(key)}\s*", frontmatter, re.M) is not None
+
+  required_keys = [
+    "name:",
+    "display-name:",
+    "short-description:",
+    "description:",
+    "user-invocable:",
+  ]
+  for k in required_keys:
+    if not has_key(k):
+      errors.append(f"frontmatter missing key: {k.rstrip(':')}")
+
+  name_match = re.search(r"^name:\s*(.+)$", frontmatter, re.M)
+  if name_match:
+    name = name_match.group(1).strip()
+    if not name.startswith("clix-"):
+      errors.append("frontmatter name should start with 'clix-'")
+
+  inv_match = re.search(r"^user-invocable:\s*(.+)$", frontmatter, re.M)
+  if inv_match:
+    val = inv_match.group(1).strip().lower()
+    if val not in ("true", "false"):
+      errors.append("frontmatter user-invocable must be true or false")
+
+if "clix-mcp-server" not in content:
+  errors.append("SKILL.md must reference 'clix-mcp-server' (MCP-first requirement)")
+
+if errors:
+  print("ERROR: skill scaffold validation failed:")
+  for e in errors:
+    print(f"- {e}")
+  sys.exit(1)
+
+print("OK: skill scaffold validation passed")
+PY
+}
+
+if command -v python3 >/dev/null 2>&1; then
+  validate_with_python
+  exit 0
+fi
+
+echo "Warning: python3 not found; falling back to basic checks with node if available." >&2
+if command -v node >/dev/null 2>&1; then
+  node - "$skill_dir" <<'NODE'
+const fs = require("fs");
+const path = require("path");
+
+const skillDir = process.argv[1];
+const errors = [];
+
+function hasFrontmatterKey(frontmatter, key) {
+  // Match key at beginning of line only (avoid substring collisions):
+  // - "display-name:" contains "name:"
+  // - "short-description:" contains "description:"
+  const re = new RegExp(`^${key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*`, "m");
+  return re.test(frontmatter);
+}
+
+function requireFile(name) {
+  const p = path.join(skillDir, name);
+  if (!fs.existsSync(p) || !fs.statSync(p).isFile()) errors.push(`missing required file: ${name}`);
+  return p;
+}
+
+function requireNonEmptyDir(name) {
+  const p = path.join(skillDir, name);
+  if (!fs.existsSync(p) || !fs.statSync(p).isDirectory()) {
+    errors.push(`missing required directory: ${name}/`);
+    return;
+  }
+  const entries = fs.readdirSync(p).filter((e) => !e.startsWith("."));
+  if (entries.length === 0) errors.push(`required directory is empty: ${name}/`);
+}
+
+const skillMd = requireFile("SKILL.md");
+requireFile("LICENSE.txt");
+requireNonEmptyDir("references");
+requireNonEmptyDir("scripts");
+
+let content = "";
+try {
+  content = fs.readFileSync(skillMd, "utf8");
+} catch (e) {
+  errors.push(`failed to read SKILL.md: ${String(e)}`);
+}
+
+// Frontmatter validation (best-effort; mirrors Python validator behavior).
+if (!content.startsWith("---\n")) {
+  errors.push("SKILL.md must start with YAML frontmatter (---)");
+} else {
+  const m = content.match(/^---\n([\s\S]*?)\n---\n/);
+  if (!m) {
+    errors.push("SKILL.md must start with YAML frontmatter delimited by ---");
+  } else {
+    const frontmatter = m[1];
+    const required = ["name:", "display-name:", "short-description:", "description:", "user-invocable:"];
+    for (const k of required) {
+      if (!hasFrontmatterKey(frontmatter, k)) {
+        errors.push(`frontmatter missing key: ${k.replace(/:$/, "")}`);
+      }
+    }
+
+    const nameMatch = frontmatter.match(/^name:\s*(.+)$/m);
+    if (nameMatch) {
+      const name = (nameMatch[1] || "").trim();
+      if (!name.startsWith("clix-")) errors.push("frontmatter name should start with 'clix-'");
+    }
+
+    const invMatch = frontmatter.match(/^user-invocable:\s*(.+)$/m);
+    if (invMatch) {
+      const val = (invMatch[1] || "").trim().toLowerCase();
+      if (!["true", "false"].includes(val)) errors.push("frontmatter user-invocable must be true or false");
+    }
+  }
+}
+if (!content.includes("clix-mcp-server")) errors.push("SKILL.md must reference 'clix-mcp-server'");
+
+if (errors.length) {
+  console.error("ERROR: skill scaffold validation failed:");
+  for (const e of errors) console.error(`- ${e}`);
+  process.exit(1);
+}
+
+console.log("OK: skill scaffold validation passed");
+NODE
+  exit 0
+fi
+
+echo "Error: neither python3 nor node found; cannot validate." >&2
+exit 2
+

package/skills/user-management/SKILL.md

@@ -2,8 +2,7 @@
 name: clix-user-management
 display-name: User Management
 short-description: User management setup
-description:
-  Implements Clix user identification and user properties (setUserId,
+description: 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