Freshworks Agentic Developer Toolkit

AI-powered toolkit for building Freshworks apps in Claude Code, Cursor, and OpenAI Codex

Build Freshworks marketplace apps faster with AI assistance.
Supports Platform 3.0 with modern best practices.

Platform 3.0 · Cursor Plugins · Crayons · Request Templates · OAuth · fdk validate

Contents

Section	Purpose
What You Can Do	Capability overview
Installation	One command for Cursor, Claude Code, and Codex
Prerequisites	Before you run fdk or publish
Available Tools	Five skills at a glance
Workflow	Idea → validated app → publish
MCP (publish)	MCP / JWT — token setup and tool names
Troubleshooting	Skills, rules, PATH, Codex
Resources	Docs, links, runbooks
Support	Issues and community
Contributing	Plugin layout, PR hygiene
Changelog	Release history
License	MIT

What You Can Do

• Set up your development environment — fw-setup installs and manages the Freshworks Development Kit (FDK) and Node.js.
• Scaffold a Platform 3.0 app — /fdk-fix and /fdk-migrate get you from a blank folder or a legacy 2.x app to a passing fdk validate output.
• Connect third-party APIs — fw-ai-actions-app generates actions.json, SMI handlers, and OAuth request templates for services like Slack or Google.
• Catch issues before review — fw-review runs the same checks marketplace reviewers use and outputs a structured report you can act on.
• Publish without leaving your IDE — fw-publish guides you through fdk validate → pack → upload → submit via MCP, no browser required.

---

Installation

npx @freshworks/fw-dev-tools install

Auto-detects Cursor, Claude Code, and OpenAI Codex. Installs all five skills and configures MCP for publish workflows.

Options:

npx @freshworks/fw-dev-tools install --tools cursor        # specific client
npx @freshworks/fw-dev-tools install --tools cursor,claude # multiple clients
npx @freshworks/fw-dev-tools install --yes                 # non-interactive

After install: restart your IDE and type /fw-setup- — autocomplete confirms the skills are active. For publish workflows, follow the MCP setup step the installer prints once to enable fw-publish.

Keep skills up to date:

npx @freshworks/fw-dev-tools update
npx @freshworks/fw-dev-tools status

Previously installed via npx skills add or manual copy? Run npx @freshworks/fw-dev-tools install — it migrates automatically.

---

Prerequisites

Topic	Guidance
Installing these skills into an IDE	Works without FDK installed first; skill content lives in skills/*/SKILL.md and plugin manifests.
Running Freshworks workflows (fdk, validate, pack)	Use fw-setup (FDK 10.x, Node 24.11.x per engine-matrix.md).
Publishing to Marketplace (MCP)	One-time Developer Portal JWT + fw-dev-mcp config — see MCP (marketplace publish) (no keys in chat).
Corporate networks	Firewall / proxy: network-requirements.md.

---

Available Tools

Each tool helps with a specific part of app development. Use them in the order below for a complete workflow:

Tool	What it does
fw-setup	Install and manage FDK (Freshworks Development Kit) and Node.js
fw-app-dev	Build complete marketplace apps with UI, OAuth, and integrations
fw-ai-actions-app	Add AI Actions and connect to third-party services
fw-review	Check your app for common issues before submission
fw-publish	Upload and publish your app to the Freshworks Marketplace

---

Step-by-Step Workflow

1. Set up your environment — fw-setup

Installs FDK 10.x + Node.js 24.x via nvm. Run this first — other skills require it.

Command	What it does
/fw-setup-install	Install FDK and Node.js
/fw-setup-status	Check what's currently installed
/fw-setup-troubleshoot	Fix PATH and shell config issues

2. Build your app — fw-app-dev

Scaffold and develop a Platform 3.0 app with Crayons UI, OAuth, and serverless functions.

Command	What it does
/fdk-fix	Fix fdk validate errors automatically
/fdk-migrate	Upgrade a legacy 2.x app to Platform 3.0

Validation order: fw-setup first (when Node/FDK is wrong) → /fdk-migrate (legacy apps) → fdk validate

3. Add AI features — fw-ai-actions-app (optional)

Connect to external APIs (Slack, Google, etc.) and add AI Actions using actions.json, SMI handlers, and request templates.

4. Review before submitting — fw-review

Runs the same checks marketplace reviewers use: manifest, iparams, frontend, and security. Outputs a structured report with blocking vs non-blocking findings.

5. Publish — fw-publish

Guides you through fdk validate → pack → upload → submit via MCP without leaving your IDE.

One-time setup:

1. Get an API key from developers.freshworks.com/developer/
2. Configure the fw-dev-mcp server in your IDE — see MCP section below

---

MCP (marketplace publish)

Publishing uses the fw-dev-mcp server. This repo bundles .mcp.json at the repository root (URL + Authorization header). MCP token placement, copy-paste blocks, and tool names are documented in the publish skill under skills/fw-publish/.

---

Troubleshooting

Having issues with skills installation or usage?

• 📋 TROUBLESHOOTING.md — Covers Cursor, Claude Code, and OpenAI Codex

Common issues:

• Skills not appearing after install → Restart your IDE; for Claude Code check ~/.claude/CLAUDE.md has the routing block
• Commands not working in Cursor → Check ~/.cursor/rules/fw-dev-tools.mdc exists
• fdk or node not found → Run /fw-setup-troubleshoot
• Codex MCP config missing → Re-run npx @freshworks/fw-dev-tools install --tools codex --yes; installer writes ~/.codex/mcp.json

---

Resources

Doc	Purpose
skills/fw-publish/	MCP config and publish workflow
TROUBLESHOOTING.md	Install and runtime issues
engine-matrix.md	FDK ↔ Node version matrix
network-requirements.md	Firewall / proxy requirements
CONTRIBUTING.md	Plugin layout, PR hygiene
Platform 3.0 App Development	Official SDK docs
Marketplace Publishing Guide	Submission requirements
FDK CLI Reference	CLI commands

---

Support

• Report Issues
• Freshworks Developer Docs
• Community standards: CODE_OF_CONDUCT.MD

Contributing

Contributions welcome — new commands, rule fixes, reference docs, and new skills. See CONTRIBUTING.md for:

• Skill and rule file structure
• How to keep AGENTS.md and plugin manifests in sync
• PR process and docs hygiene scripts
• Marketplace listing kit (canonical strings, logos, blurbs)

License

MIT