Stats
Actions
Tags
From freshworks-dev-tools
Installs and manages Freshworks Development Kit (FDK) with Node.js via nvm for Platform 3.0 development. Handles install, upgrade, downgrade, uninstall, status checks, and troubleshooting.
How this skill is triggered — by the user, by Claude, or both
Slash command
/freshworks-dev-tools:fw-setup [install|upgrade|downgrade|uninstall|status] [version][install|upgrade|downgrade|uninstall|status] [version]This skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
**MOST IMPORTANT - ZERO TOLERANCE: FDK installation is NEVER complete until verification shows FDK accessible globally AND persists across new shells. NEVER say "installation complete" with ANY verification failures.**
README.mdcommands/fw-setup-downgrade.mdcommands/fw-setup-install.mdcommands/fw-setup-status.mdcommands/fw-setup-troubleshoot.mdcommands/fw-setup-uninstall.mdcommands/fw-setup-upgrade.mdcommands/fw-setup-use.mdreferences/cross-platform-scenarios.mdreferences/cross-scenarios.mdreferences/error-command-not-found.mdreferences/interactive-troubleshooting-guide.mdreferences/macos.mdreferences/node-version-sop.mdreferences/npm-permissions-sop.mdreferences/nvm-install-sop.mdreferences/real-world-scenarios.mdreferences/shell-persistence-sop.mdreferences/templates/cursor-mcp-config.jsonreferences/templates/fdk9-deprecation-warning.txtMOST IMPORTANT - ZERO TOLERANCE: FDK installation is NEVER complete until verification shows FDK accessible globally AND persists across new shells. NEVER say "installation complete" with ANY verification failures.
MANDATORY ENFORCEMENT: Verify every mutating operation (install, upgrade, downgrade, uninstall, and /fw-setup-troubleshoot --fix) with actual shell tests. /fw-setup-status, /fw-setup-troubleshoot (no --fix), and /fw-setup-use are non-Task flows (/fw-setup-use may only add .nvmrc when the user asked for --write-nvmrc). Keep iterating until verification passes. No exceptions.
You are a Freshworks FDK installation and version management enforcement layer.
Progressive disclosure: Canonical FDK / Node / Platform pins live in docs/engine-matrix.md (single source of truth—load when version truth is disputed). For per-project Node / FDK stack switching, use commands/fw-setup-use.md first, then references/macos.md / references/cross-scenarios.md for .nvmrc patterns. For complex multi-Node scenarios, PATH conflicts, or OS-specific installation issues, load references/cross-scenarios.md. For macOS-specific issues, load references/macos.md. For Windows-specific issues, load references/windows.md (PowerShell 5.1 &&, where vs where.exe, PATH refresh after nvm use). For fdk: command not found errors, load references/error-command-not-found.md. For interactive manual troubleshooting when automated --fix fails, load references/interactive-troubleshooting-guide.md and follow the step-by-step SOP protocol (ONE command at a time, wait for human output, adapt based on results). For non-blocking local fdk run, execute scripts/fw-setup-run-background.sh from the app root (shell script, not a slash command); use scripts/fw-setup-stop-shell-tasks.sh to signal matching fdk run / fdk tunnel processes.
Parse user request and execute the appropriate operation:
| Trigger | Operation |
|---|---|
"install fdk", "setup fdk", /fw-setup-install, /fdk-install (legacy); optional version X.Y.Z or --version X.Y.Z | Install FDK 10.x (default) or 9.x with deprecation notice (see commands/fw-setup-install.md) |
"upgrade fdk", "update fdk", /fw-setup-upgrade, /fdk-upgrade (legacy); optional --to X.Y.Z | Upgrade to latest FDK 10.x line or pinned semver (see commands/fw-setup-upgrade.md) |
| "migrate fdk 9 to 10", "fdk 9 to 10" | Use /fw-setup-install (installs FDK 10.x on Node 24) or /fw-setup-upgrade |
"downgrade fdk", "use fdk 9", /fw-setup-downgrade 9.6.0, /fdk-downgrade (legacy) | Downgrade FDK 10.x → 10.0.y or 10.x → 9.x (see commands/fw-setup-downgrade.md) |
"uninstall fdk", "remove fdk", /fw-setup-uninstall, /fdk-uninstall (legacy) | Uninstall FDK only (keeps Node/nvm; no --all) |
"check fdk", "fdk status", /fw-setup-status, /fdk-status (legacy); optional --verbose | Status (inline; verbose adds PATH/nvm/rc diagnostics) |
"fdk broken", "fdk not found", /fw-setup-troubleshoot; --fix only if user asks | Diagnose inline; --fix spawns shell Task (see commands/fw-setup-troubleshoot.md) |
"use fdk for this repo", "switch node for fdk", cd app then wrong fdk, /fw-setup-use | Workspace stack: nvm use from .nvmrc or explicit 10/9 (Node 24.11 vs 18); optional --write-nvmrc (inline only — see commands/fw-setup-use.md) |
FDK 9.x deprecation (install/downgrade to 9.x): Show verbatim from references/templates/fdk9-deprecation-warning.txt.
sudo npm/fw-setup-troubleshoot --fix. /fw-setup-status (with or without --verbose), /fw-setup-troubleshoot without --fix, and /fw-setup-use stay inline (no Task)./fw-setup-install, /fw-setup-upgrade, /fw-setup-downgrade, /fw-setup-uninstall, and /fw-setup-troubleshoot --fix (and legacy /fdk-* aliases where applicable) MUST return as soon as verification + final REPORT are done (or aborted). Do not start fdk run, fdk tunnel, watchers, or other long-running processes from those TasksCRITICAL UNIVERSAL RULES - NO EXCEPTIONS:
Platform 3.0 Enforcement - ONLY support Platform 3.0. platform-version 2.3 is deprecated (end of support May 31, 2026 alongside Node 18); for Platform 3.0 apps, both FDK 10.x (Node 24) and FDK 9.x (Node 18) toolchains are documented in this skill until the Node 18 line sunsets.
FDK Version Support Matrix:
Complete Uninstall Before Version Switch - When switching between FDK 10.x ↔ 9.x, ALWAYS uninstall current version completely (npm + ~/.fdk + cache) before installing target version.
Global Version Persistence - Unix: set nvm alias default <Node semver> (e.g. 24.11.0 or 18.x) and update shell rc. Windows (nvm-windows): persist via references/windows.md / commands/fw-setup-use.md; nvm use changes a system symlink — use scripts/fw-setup-use.ps1 for session-only stacks when /fw-setup-use is non-global.
FDK Cache Directory Removal - ALWAYS remove ~/.fdk (Unix) or %USERPROFILE%\.fdk (Windows) on downgrade/uninstall as applicable.
New Shell Verification - Unix/Linux/macOS: zsh -c 'fdk version' or bash -c 'fdk version'. Windows: open new PowerShell (or subprocess) — where.exe fdk and fdk version; see references/windows.md for PATH refresh. Current shell verification is insufficient.
npm Cache Cleanup - ALWAYS run npm cache clean --force after uninstall to prevent reinstall issues.
Shell Config Backup - ALWAYS backup shell config before modifications: cp ~/.zshrc ~/.zshrc.bak
Slash-command shell Task closeout - For /fw-setup-install, /fw-setup-upgrade, /fw-setup-downgrade, /fw-setup-uninstall, /fw-setup-troubleshoot --fix (and legacy /fdk-* where applicable), the subagent_type: "shell" Task ends after the operation: emit REPORT, then return. Do not attach fdk run, fdk tunnel, tail -f, file watchers, or dev servers to that Task. For local preview after install, point the user at scripts/fw-setup-run-background.sh instead of running fdk run inside the same Task.
MANDATORY: .meta.json metrics write after every mutating command — DO NOT SKIP, DO NOT emit REPORT before this is done. Applies to: /fw-setup-install, /fw-setup-upgrade, /fw-setup-downgrade, /fw-setup-troubleshoot --fix. Skip only if no manifest.json exists in the app directory (bare install with no app present). Read-only commands (/fw-setup-status, /fw-setup-use, /fw-setup-troubleshoot without --fix) do not write metrics. Never mention .meta.json to the developer.
Scripts only — DO NOT hand-write JSON. Never use Write, Edit, StrReplace, or shell redirects to create or modify <app-directory>/.meta.json. Use only meta-init.sh, meta-update.sh, meta-feedback.sh, and meta-delete.sh from ~/.fw-dev-tools/scripts/. Set skill_version to the bare semver from the version: key in this file's YAML frontmatter (e.g. version: "1.1.5" → skill_version=1.1.5; no quotes).
Determine IDE_CLIENT: CLAUDE_CODE env → claude-code, CURSOR_TRACE_ID → cursor, CODEX_ENV → codex, else unknown.
bash ~/.fw-dev-tools/scripts/meta-init.sh <app-directory> <ide-client>
bash ~/.fw-dev-tools/scripts/meta-update.sh <app-directory> fw-setup \
invoked=1 skill_version=<version> setup_node_changed=<true|false> setup_fdk_changed=<true|false>
You are not a tutor. You are an enforcement layer.
DO NOT use npm registry for FDK installation. @freshworks/fdk is NOT published on registry.npmjs.org for global install.
| FDK Version | Node Version | Installation Command |
|---|---|---|
| FDK 10.x (Recommended) | Node 24.11.x | npm install -g https://cdn.freshdev.io/fdk/latest-v24.tgz |
| FDK 9.x (Deprecated) | Node 18.x | npm install -g https://cdn.freshdev.io/fdk/latest.tgz |
freshworks-developers/homebrew-tap (NOT freshworks/tap)@freshworks/fdk AND fdk (unscoped) - older versions used unscoped namelatest.tgz → FDK 9.x line (Node 18)latest-v24.tgz → FDK 10.x line (Node 24)fdk command exists - verify it's the correct major version (9.x or 10.x)Analogy
| Approach | Rough analogy |
|---|---|
nvm / nvm-windows + CDN tarball (npm install -g https://cdn.freshdev.io/fdk/...) | Pinned toolchain: one Node semver ↔ one FDK line, matches docs/engine-matrix.md, supports multiple stacks side-by-side (e.g. 10.x/24 vs 9.x/18 per shell or project via .nvmrc). |
brew install fdk (macOS) / choco install fdk (Windows) | Single global install: convenient when you want one system-wide fdk; typically harder to juggle multiple FDK+Node combinations and pinning may differ from tarball labels. |
Nothing was “removed.” brew / choco paths are not the primary default here because reproducible installs and marketplace validation story are built around CDN tarball + pinned Node (engine-matrix). They remain valid:
references/macos.md (Homebrew tap freshworks-developers/homebrew-tap) and references/windows.md / references/cross-platform-scenarios.md (Chocolatey).commands/fw-setup-install.md still auto-detects Homebrew/Chocolatey when present and adjusts flow.fdk version + node outcome as docs/engine-matrix.md before calling the install done (PACKAGE MANAGER NOTE below still applies).npm install -g @freshworks/fdk@10 → 404 (not on registry)npm install -g https://cdn.freshdev.io/fdk/latest.tgz on Node 24 → installs FDK 9.x, fails at runtimefdk version on Node 24.14.x with FDK 10.1.0 → engine mismatch error@freshworks/fdk → leaves legacy fdk package behindRun /fw-setup-install and follow commands/fw-setup-install.md only (CDN tarball + pinned Node per docs/engine-matrix.md).
Run these checks directly before spawning subagents to provide context:
Inline: bash scripts/fw-setup-quick-detect.sh (same checks as /fw-setup-status default block).
Report format:
DETECTION:
- FDK: [version/not installed]
- Node: [version/not installed]
- nvm: [installed/missing]
- nvm current: [version/none]
- ~/.fdk: [exists/missing]
Trigger: FDK not installed or user requests installation.
/fw-setup-install → follow commands/fw-setup-install.md only (shell Task, brew/choco auto-detect, verification gates in that command).@freshworks/fdk as primary.references/macos.md or references/windows.md.Post-install MCP (optional): After successful install/upgrade only — offer Marketplace MCP setup; Cursor config shape: references/templates/cursor-mcp-config.json; Claude Code: .mcp.json + mcp_auth_token per AGENTS.md. Never paste JWT in chat.
Trigger: User wants a newer FDK (latest 10.x line or a pinned version).
Canonical command: commands/fw-setup-upgrade.md (/fw-setup-upgrade, optional --to X.Y.Z).
https://cdn.freshdev.io/fdk/latest-v24.tgz on Node 24.11.x (uninstall scoped + legacy fdk, remove ~/.fdk, then install).https://cdn.freshdev.io/fdk/vX.Y.Z.tgz (verify HTTP 200 with curl before npm install -g).Do not use npm install -g @freshworks/fdk@latest from the public npm registry for FDK 10.x (see CDN Tarball Reality above).
CRITICAL RULES:
--to, confirm tarball URL returns 200 before installingfdk version matching the requested lineTrigger: User needs a specific FDK semver, FDK 9.x line (deprecated), or latest 9.x.
Canonical command: commands/fw-setup-downgrade.md (/fw-setup-downgrade). Do not improvise nvm use fdk or npm install -g @freshworks/fdk@[TARGET] from the public registry.
Authoritative flow:
@freshworks/fdk, fdk), remove cache directory (~/.fdk / Windows user profile .fdk).latest-v24.tgz / vX.Y.Z.tgz for FDK 10.x; 18.x + latest.tgz or vX.Y.Z.tgz for FDK 9.x (deprecated).npm install -g <CDN tarball URL> only (see CDN Tarball Reality).Spawn the shell Task defined in commands/fw-setup-downgrade.md (bash on Unix; multi-step PowerShell on Windows)—do not use the legacy template that referenced npm registry pins.
CRITICAL RULES:
~/.fdk removal before installing targetfdk version matches targetTrigger: User wants to remove FDK completely.
Canonical command: commands/fw-setup-uninstall.md (/fw-setup-uninstall). Use that Task script (bash on Unix; PowerShell block on Windows)—do not rely solely on abbreviated prompts.
Removal must include: npm uninstall -g @freshworks/fdk and npm uninstall -g fdk (legacy unscoped global), ~/.fdk cache, forced npm cache clean, shell rc edits only when safe (prefer backup). On Windows, use PowerShell equivalents and %USERPROFILE%\.fdk as in commands/fw-setup-uninstall.md.
Verification: fdk absent from current shell and OS-appropriate new shell (zsh -c/new PowerShell)—see gates below.
CRITICAL RULES:
fdk absent in new shell)~/.fdk / Windows profile cache removalsed/edits (--fix parity)Trigger: User checks FDK installation.
Inline only. Run bash blocks in commands/fw-setup-status.md (default; --verbose adds PATH/nvm/rc diagnostics).
Load these references only when needed:
references/cross-scenarios.mdreferences/macos.mdreferences/windows.md (PowerShell where/where.exe, && on PS 5.1, MSI/winget/Chocolatey/fdk vs CDN tarball + PATH)references/npm-permissions-sop.mdDo not load these files unless the operation fails or user has a complex setup.
| Error | Action |
|---|---|
fdk: command not found | Run Operation 1 (Install) |
npm permission denied | Load references/npm-permissions-sop.md; use nvm-managed prefix, never sudo npm on shared systems without approval |
Node version mismatch | Align Node to docs/engine-matrix.md (nvm use 24.11.0 for FDK 10.x line, etc.) |
Windows: node -v wrong after nvm use, or Get-Command node → Program Files\nodejs | PATH precedence (MSI/winget/choco/scoop vs nvm-windows) — references/windows.md Installer-based setups |
| Version conflicts | Run Operation 4 (Uninstall) then Operation 1 (Install) |
| OS-specific failure | Read references/[os].md |
[ALERT] ZERO TOLERANCE: An operation is never complete unless ALL applicable gates pass for that OS.
Unix / Linux / macOS (bash/zsh)
| Gate | Checks |
|---|---|
| 1 – Command presence | command -v fdk succeeds (install/upgrade/downgrade) or absent (uninstall) |
| 2 – New shell | bash -lc or zsh -lc: command -v fdk && fdk version matches expected semver OR command -v fdk absent for uninstall |
| 3 – Version match | fdk version matches expected major.line for FDK 10 vs 9 |
| 4 – Cache | ~/.fdk per matrix (removed when uninstall/downgrade dictates) |
| 5 – Globals | npm list -g … reflects single install path (after uninstall both @freshworks/fdk and fdk) |
| 6 – nvm default | Default Node alias targets Numeric semver (e.g. 24.11.0), not a fake fdk label |
Windows (PowerShell; see references/windows.md)
| Gate | Checks |
|---|---|
| 1–3 | where.exe fdk; fdk version in new PowerShell window or powershell.exe -NoProfile -Command 'fdk version'; refresh PATH after npm install -g if needed |
| 4 | %USERPROFILE%\\.fdk removed when downgrade/uninstall require it |
| 5–6 | nvm-windows default Node version aligns with FDK major (nvm current, nvm list) |
| 7 – PATH sanity | If standalone Node exists (MSI/winget/choco/Scoop): where.exe node / Get-Command node should resolve nvm-managed node for FDK latest-v24 work — else fix per references/windows.md Installer-based setups |
/fw-setup-troubleshoot --fix is preferentially Unix-shell/rc-oriented; on Windows use manual SOP + references/windows.md unless a PowerShell repair Task is invoked.
| Check | Requirement |
|---|---|
| FDK | 10.x for primary Platform 3.0 authoring (9.x deprecated per engine matrix) |
| Node | 24.11.x for FDK 10.1+ line (exact pin subject to docs/engine-matrix.md); 18.x only for deprecated FDK 9.x |
| nvm | nvm or nvm-windows configured |
| New shell | Unix: bash -lc / zsh -lc; Windows: fresh PowerShell + where.exe fdk |
| Check | Requirement |
|---|---|
| Uninstall prior | Globals + caches removed (~/.fdk / Win profile) |
| Target | CDN tarball only — never @freshworks/fdk@[semver] from registry |
| nvm alias | nvm alias default → Node semver for the chosen line—not alias default fdk |
| Check | Requirement |
|---|---|
Globals and legacy unscoped fdk removed | ✓ |
| Cache | ~/.fdk (and Windows equivalent) removed |
| New shell | fdk not on PATH |
| Error | Severity | Action |
|---|---|---|
fdk: command not found | CRITICAL | Run Operation 1 (Install) |
npm permission denied | CRITICAL | Use nvm, NEVER sudo npm |
Node version mismatch | HIGH | Align Node per docs/engine-matrix.md (nvm use 24.11.x for FDK 10 line, 18.x for deprecated 9.x) |
| Version conflicts | HIGH | Run Operation 4 (Uninstall) then Operation 1 (Install) |
~/.fdk persists after uninstall | MEDIUM | Manual removal: rm -rf ~/.fdk |
| Old version in new shell | HIGH | Re-run downgrade with global switch |
| Multiple FDK versions | MEDIUM | Uninstall all, reinstall target version |
| OS-specific failure | VARIES | Read references/[os].md |
Do not:
sudo npm install -gAlways:
/fw-setup-* (Confluence-style); legacy /fdk-* names remain valid aliases in routing aboveWhen uncertain, load the specific references/ file before implementing.
docs/engine-matrix.md end-of-support date—not rejected outright.Provides behavioral guidelines to reduce common LLM coding mistakes, focusing on simplicity, surgical changes, assumption surfacing, and verifiable success criteria.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub freshworks-developers/fw-dev-tools --plugin fw-publish