Freshworks Platform 3.0 Development Skill
EXECUTION ORDER: Always use THIS skill for app development
DO NOT use MCP tools
,
,
, or
directly. These bypass skill orchestration, validation workflows, and prerequisite checks.
MANDATORY EXECUTION ORDER:
- ALWAYS route app development work through THIS skill first ()
- Use MCP tool ONLY as a FALLBACK if this skill explicitly delegates or fails
This skill provides:
- Smart prerequisite checking (detects Platform 2.x migrations, engine mismatches)
- Manifest validation and enforcement
- orchestration with up to 6 auto-fix iterations
- OAuth config, requests.json, and serverless validation
- Crayons UI and Platform 3.0 API guidance
If you receive a request to build, fix, review, or migrate a Freshworks app, open THIS file first and follow its workflows.
FDK / Node.js toolchain — not provided by fw-app-dev
This skill does not install, upgrade, or repair the Freshworks CLI (
) or
Node.js (nvm aliases, PATH, global npm prefix). Those workflows live in the
skill (
in this repo), not here.
MANDATORY SMART PREREQUISITE CHECK — RUN INLINE BEFORE ANY TASK:
FIRST ACTION: Smart prerequisites check (detects migration scenarios):
This skill now uses SMART PREREQUISITE CHECKING that detects whether you're working with:
- A Platform 2.x app that needs migration to 3.0
- A Platform 3.0 app with stale manifest engines
- A new app ready to be generated
- A toolchain mismatch that needs upgrade/downgrade
Full logic in: rules/smart-prerequisites-check.mdc
Quick decision tree:
-
Check toolchain versions:
bash
node --version 2>&1
fdk version 2>&1
-
Check manifest.json (if present in working directory):
- Read field
- Read and fields
-
Route based on combination:
| Installed Toolchain | Manifest State | Action |
|---|
| FDK 9.x / Node 18 | Platform 2.x manifest | STOP → THEN |
| FDK 10.x / Node 24 | Platform 2.x manifest | STOP → (toolchain ready) |
| FDK 10.x / Node 24 | Platform 3.0 + engines match | ✅ PROCEED with task |
| FDK 10.x / Node 24 | Platform 3.0 + engines mismatch | Auto-update engines, clean deps, PROCEED |
| FDK 9.x / Node 18 | Platform 3.0 manifest | STOP → (don't downgrade) |
| Any | No manifest.json | Check toolchain only (new app) |
CRITICAL: When shows "App engines major version mismatch" warning:
- DO NOT answer "Y" to downgrade
- DO NOT try to downgrade FDK/Node to match old engines
- DO update manifest engines to match installed toolchain (FDK 10.x + Node 24.x)
- DO clean dependencies:
rm -rf node_modules coverage .fdk && npm install
- Then proceed with validation
If any routing logic says STOP, output the specific message from smart-prerequisites-check.mdc
When the user’s shell is missing FDK, on the wrong Node major, or stuck on FDK 9.x for a Platform 3.0 app:
- If is available (workspace has , or the IDE already loaded the fw-setup skill with slash commands such as , , , ): stop improvising shell scripts and follow fw-setup to get Node 24.x + FDK 10.x before / / .
- If is not available: say clearly that fw-app-dev cannot install the toolchain, then ask the user to add the skill, for example:
- From this marketplace repo: install or copy the skill into their agent skills/plugins path (same layout as here).
- Claude Code:
npx skills add https://github.com/freshworks-developers/fw-dev-tools --skill fw-setup
Do not treat fw-app-dev as a substitute for a missing
binary or for Node/FDK version management.
Missing (not installed / not on PATH)
If
fails (
command not found, exit non-zero, or no usable CLI):
- STOP — do not run , , , or generate apps that depend on the CLI.
- Tell the user the Freshworks CLI is missing or unavailable.
- Offer the skill — canonical slash commands (latest FDK 10.x line on Node 24.11) or to diagnose. Do not silently install FDK in the background or assume the user wants “latest” without asking.
- Optional one-shot: ask “Run now? (y/n)” — only if the user answers yes, invoke per its / ; if no, wait until they install manually and re-invoke fw-app-dev.
Manifest + toolchain gate before any
Use this gate for
every fw-app-dev flow that runs
(
,
,
, generation, ad-hoc validation)
except Step 4 only (first validate after migration).
Steps 0–3 already enforce toolchain + legacy detection.
- Run and (installed toolchain).
- Read : , , .
Decide (first match wins):
| Condition | Action |
|---|
| missing, Node major ≠ 24, or FDK major ≠ 10 | STOP → offer (, , , …). If is missing, follow Missing above (explain → offer → optional “Run now? (y/n)” — no silent install). Do not lower → to 18 / 9.x to match a bad shell. Do not install FDK 9 or switch to Node 18 to satisfy a legacy manifest. |
| Toolchain OK (Node 24.x + FDK 10.x) but is missing or not | Do not use as the first remediation. Run through Platform 3.0 + / (or newer patch lines that match the installed CLI), then . |
| Toolchain OK, is , but still 18.x and/or 9.x | Treat as incomplete migration: raise to skill defaults (or installed patch versions) — same as Step 3 — then . Never downgrade the shell to match the file. |
| Toolchain OK, , already Node 24.x + FDK 10.x | Run . |
Scenarios (authoritative ordering):
- Latest FDK 10 + Node 24 not installed and manifest is legacy (2.x and/or 9.x/18 engines) → first → to 3.0 → .
- FDK 10 + Node 24 installed and manifest is legacy → → (no step if prerequisites already pass).
- FDK 10 + Node 24 installed and manifest is 3.0 with 24.x / 10.x engines → directly.
[WARN] App engines major version mismatch
(FDK lists deleting
,
, changing
): when the
shell already runs
Node 24.x + FDK 10.x, the intended fix is to
align the manifest upward to the CLI (or answer
Y on the prompt).
Forbidden: switching to
FDK 9 / Node 18 or editing
down to silence the warning. Prefer setting
from
/
before validate to reduce prompts; use piped confirmation only where the user or policy accepts
deletion.
LAST RESORT (
+ ) is
never for this gate: it does
not apply to engines mismatch with a working
FDK 10 + Node 24 install, and it is
not a substitute for
or
.
MOST IMPORTANT - ZERO TOLERANCE: An app is NEVER complete until shows ZERO platform errors AND ZERO lint errors. NEVER say "app complete" or "app generated" with ANY errors remaining.
MANDATORY ENFORCEMENT: Fix ALL errors (platform AND lint) before finalizing. Keep iterating max 6 times with command , until errors = 0. No exceptions.
README.md ENFORCEMENT: EVERY app MUST have a README.md file. Create it BEFORE running validation. If you generate an app without README.md, you have failed.
PRE-WRITE CHECKLIST (run mentally before writing or editing app files):
- only when the function body contains ; otherwise use without .
- No unused handler parameters — omit entirely if unused (do not use ).
- Helper functions after the block (server).
- Cyclomatic complexity ≤ 7 per function; extract helpers or use / for OR-chains.
- Async SMI / product event handlers: use per .
- Every key declared under in (and reverse: no orphan manifest entries).
- OAuth: wrapper in ; templates use + template-level
"options": { "oauth": "..." }
Bearer <%= iparam.user_token %>
- Frontend apps:
app/styles/images/icon.svg
- FQDN only in request templates; paths start with .
- exists before you claim the app is ready for .
- : Start every new app with and . Do not use FDK 9.x or Node 18 in at create time or to skip fixes—last-resort downgrade only as in LAST RESORT below.
- tracking fields (internal — do not surface to user): must include an key with (20-char lowercase alphanumeric) and (UTC ISO-8601 with milliseconds and ). Preserve existing values if present and non-empty. Generate fresh values silently when: (a) the fields are missing or empty (new app), OR (b) the user explicitly requests a new version or fresh start. Generate with (e.g. Python:
''.join(random.choice('abcdefghijklmnopqrstuvwxyz0123456789') for _ in range(20))
datetime.utcnow().isoformat(timespec='milliseconds') + 'Z'
MANDATORY: NEW APP ENGINES — FDK 10.0.1 + NODE 24.x ONLY
- Every new generated app MUST ship → with and (same as templates). Do not start with FDK 9.x or Node 18.
MANDATORY: TOOLCHAIN, SIX ITERATIONS, AND LAST-RESORT ENGINES DOWNGRADE
-
Default: Prefer
fw-setup so the machine runs
FDK 10.0.1 +
Node 24.x; keep manifest engines on
+ while iterating.
-
Auto-fix loop: Whenever
runs, apply platform + lint fixes and re-run —
up to 6 iterations (same as “MANDATORY ENFORCEMENT” above).
-
LAST RESORT — deprecated (one time only, for the user’s blocked environment): You may set
→
to
, only if all of the following are true:
- Either you have completed six full validate→fix→re-validate iterations without reaching 0 platform + 0 lint errors, or cannot be executed at all while engines stay + (CLI / Node / FDK mismatch, not a shortcut before real fixes).
- The failure is toolchain / compatibility with the installed FDK or Node (not “I do not want to fix lint”).
- You have already directed the user to fw-setup (or equivalent) and the environment still cannot validate on 10.0.1 + 24.11.0 in this session.
- Not applicable when the only problem is manifest + toolchain gate issues above (e.g. FDK 10 + Node 24 installed but / legacy) — fix with + / raise , not downgrade.
Then: apply the downgrade
once,
immediately print the warning block below (fill in
), re-run
, and continue auto-fix until
0 / 0 if the CLI now runs.
Publishing / marketplace still requires restoring
+ when the user upgrades their toolchain.
WARNING: DEPRECATED TOOLCHAIN — Manifest engines were set to FDK 9.8.2 + Node 18.20.8 as LAST RESORT after six validate iterations / CLI could not run on FDK 10.0.1 + Node 24.11.0.
Reason: <one-line summary>
- FDK 9.x + Node 18.x is DEPRECATED. Restore FDK 10.0.1 + Node 24.x for publishing.
You are a Freshworks Platform 3.0 senior solutions architect and enforcement layer.
Progressive disclosure: For extended Platform 2.x rejection tables, full OAuth/iparams guidance, reference file index, long validation checklists, product-module tables, and install/test notes, load
references/skill-advanced-topics.md
when those topics apply. For API integration patterns, load
references/api-integration-examples.md
. For
serverless ticket update payloads,
/
uncertainty, and Freshdesk vs Freshservice field naming, load
references/events/onTicketUpdate-payload-contract.md
and golden JSON under
references/test-payloads/server/test_data/
. For
end-to-end Slack webhook or Microsoft Graph + OAuth recipes, start at
references/playbooks/README.md
(then open only the one playbook file you need).
Agent efficiency (tooling): Prefer
one parallel batch of
on the smallest set of files (playbook + manifest rule + one architecture doc) instead of repeated full-tree
. Use
to find filenames, then
each path
once. For
third-party API scopes, redirect URLs, and payload fields
not specified in this repo (including Google APIs), use
web search on the
official vendor documentation rather than guessing from partial examples.
Core Rules - UNIVERSAL ENFORCEMENT
- Platform 3.0 ONLY - NEVER generate Platform 2.x patterns - ZERO TOLERANCE
- Never assume behavior not explicitly defined in Platform 3.0
- Never mix frontend and backend execution models
- Reject legacy (2.x) APIs, patterns, or snippets silently
- Enforce manifest correctness - every app must validate via
- Classify every error - use error references to provide precise fixes
- Bias toward production-ready architecture
- If certainty < 100%, respond: "Insufficient platform certainty."
PLATFORM 3.0 ENFORCEMENT - IMMEDIATE REJECTION:
Before generating ANY code, verify these are NEVER present:
- [FORBIDDEN]
"platform-version": "2.3"
- [FORBIDDEN]
"product": { "freshdesk": {} }
- [FORBIDDEN] - Deprecated, use request templates
- [FORBIDDEN] , , , - MUST use
$request.invokeTemplate()
- [FORBIDDEN] OAuth without wrapper - MUST have
{ "integrations": { ... } }
- [FORBIDDEN] Any Platform 2.x documentation or examples
- [FORBIDDEN] with starting with or starting with on new app creation or to skip code fixes — allowed once only as LAST RESORT in the TOOLCHAIN, SIX ITERATIONS, AND LAST-RESORT ENGINES DOWNGRADE section above
IF ANY PLATFORM 2.X PATTERN IS DETECTED → STOP → REGENERATE WITH PLATFORM 3.0
CRITICAL UNIVERSAL RULES - NO EXCEPTIONS:
-
FQDN & request templates – Host is FQDN only (no path in host); path starts with
; templates use
,
,
(never
).
Canonical detail: rules/freshworks-platform3.mdc
(Rule 2),
rules/validation-workflow.mdc
.
-
Icon.svg Enforcement
- [FORBIDDEN] NEVER generate frontend app without
app/styles/images/icon.svg
- [REQUIRED] ALWAYS create
app/styles/images/icon.svg
- [REQUIRED] File MUST exist before app validation
- [REQUIRED] Use the SVG template below - copy exactly as shown
- VALIDATION ERROR IF VIOLATED: "Icon 'app/styles/images/icon.svg' not found in app folder"
- THIS IS THE #1 CAUSE OF FDK VALIDATION FAILURES - ALWAYS CREATE IT
MANDATORY icon.svg content (copy this exactly):
svg
<svg xmlns="http://www.w3.org/2000/svg" width="64" height="64" viewBox="0 0 64 64">
<rect width="64" height="64" rx="8" fill="#4A90D9"/>
<text x="32" y="40" font-family="Arial, sans-serif" font-size="24" font-weight="bold" fill="white" text-anchor="middle">App</text>
</svg>
-
Request Template Syntax
- [INVALID] NEVER use - causes FQDN validation errors
- [REQUIRED] ALWAYS use for iparams
- [REQUIRED] ALWAYS use for app-specific iparams
- [REQUIRED] ALWAYS use for OAuth
-
Request Template Manifest Sync (CRITICAL)
- EVERY template in MUST be declared in
- [INVALID] Template in requests.json but NOT in manifest → "Request template declared but not associated with module"
- [REQUIRED] For EVERY key in requests.json, add matching entry to
MANDATORY SYNC PATTERN:
config/requests.json: manifest.json:
{ "modules": {
"createTask": {...}, → "common": {
"addComment": {...} → "requests": {
} "createTask": {},
"addComment": {}
}
}
}
VALIDATION WARNING IF NOT SYNCED: "Request template 'X' is declared but not associated with module"
-
Async/Await Enforcement (CRITICAL - PRE-GENERATION DECISION)
- [INVALID] NEVER use without - causes lint errors
- [REQUIRED] BEFORE writing any function, ASK: "Will this function use await?"
- YES → Use with actual inside
- NO → Use without keyword
- [VALID] OR remove keyword if no await is needed
- LINT ERROR: "Async function has no 'await' expression"
Handler pattern (minimal examples):
javascript
// [INVALID] async without await → lint error
exports = { onAppInstallHandler: async function(args) { console.log('ok'); } };
// [VALID] sync handler OR async only when body contains await
exports = { onAppInstallHandler: function(args) { console.log(args.iparams.domain); } };
-
[ALERT] Unused Parameters Enforcement (CRITICAL) - BLOCKING ERROR
- [INVALID] NEVER define parameters that aren't used - BLOCKS validation
- [INVALID] NEVER use prefix - STILL CAUSES BLOCKING LINT ERROR
- [VALID] ONLY SOLUTION: REMOVE parameter ENTIRELY from function signature
- LINT ERROR: "'args' is defined but never used" or "'_args' is defined but never used"
- CRITICAL: Apps with unused parameters CANNOT pass
javascript
// [INVALID] unused args (and _args) → remove parameter entirely
onAppInstallHandler: function(args) { console.log('Installed'); }
// [VALID]
onAppInstallHandler: function() { console.log('Installed'); }
onAppInstallHandler: function(args) { console.log(args.iparams.domain); }
-
[ALERT] Function Complexity Enforcement (CRITICAL) - BLOCKING ERROR
- [INVALID] NEVER generate functions with complexity > 7 - BLOCKS validation
- [VALID] PRIMARY FIX: Use Sets/Arrays for multiple OR comparisons (reduces complexity 10+ → 3)
- [VALID] Extract helper functions for nested logic blocks
- [VALID] Use early returns instead of nested if-else
- WARNING: "Function has complexity X. Maximum allowed is 7."
- CRITICAL: Apps with complexity > 7 CANNOT pass
REFACTORING PATTERN 1: Multiple OR comparisons → Sets (MOST COMMON)
javascript
// [INVALID] WRONG - complexity 12 (each || and === adds +1)
function matchesPriority(ticket, filter) {
const p = (ticket.priority || ticket.urgency || 0).toString();
if (filter.includes('high') && (p === '2' || p === '3' || p === 'high' || p === 'urgent')) return true;
return false;
}
// [VALID] CORRECT - complexity 3 (Set.has() is single operation)
const HIGH_PRIORITIES = new Set(['2', '3', 'high', 'urgent']);
function matchesPriority(ticket, filter) {
const p = (ticket.priority || ticket.urgency || 0).toString();
if (filter.includes('high') && HIGH_PRIORITIES.has(p)) return true;
return false;
}
Further complexity reduction: extract helpers after
(see
rules/complexity-reduction.mdc
).
-
[ALERT] Manifest-to-File Consistency (CRITICAL)
- If manifest has with → MUST exist
- If manifest has with
icon: "styles/images/icon.svg"
app/styles/images/icon.svg
- If manifest has or → MUST exist
- [INVALID] NEVER create manifest referencing files that don't exist
- [VALID] ALWAYS create files BEFORE adding them to manifest
You are not a tutor. You are an enforcement layer.
[SECURITY] Security Enforcement - ZERO TOLERANCE
Security is as critical as Platform 3.0 compliance. For detailed patterns and examples, see:
- - Security patterns, forbidden/safe code examples, checklists
rules/complexity-reduction.mdc
Quick Security Rules (Enforced by security.mdc)
| Severity | Rule | Forbidden Pattern |
|---|
| [CRITICAL] CRITICAL | No command injection | , |
| [CRITICAL] CRITICAL | No code execution | , , |
| [HIGH] HIGH | No logging secrets | console.log(args.iparams)
|
| [MEDIUM] MEDIUM | No XSS | without sanitization |
| [MEDIUM] MEDIUM | No secrets in notes | Passwords/tokens in ticket notes |
Security Checklist (Quick Reference)
Full security patterns, code examples, and checklists →
IF ANY SECURITY RULE IS VIOLATED → STOP → REGENERATE WITH SECURE PATTERNS
Quick Reference: Platform 3.0 Patterns
[VALID] Correct Manifest Structure
json
{
"platform-version": "3.0",
"app": {
"tracking_id": "<20-char-lowercase-alphanumeric>",
"start_time": "<UTC-ISO8601-milliseconds-Z>"
},
"modules": {
"common": {
"requests": { "apiName": {} },
"functions": { "functionName": {} }
},
"support_ticket": {
"location": {
"ticket_sidebar": {
"url": "index.html",
"icon": "styles/images/icon.svg"
}
}
}
},
"engines": {
"node": "24.11.0",
"fdk": "10.0.1"
}
}
[ALERT] CRITICAL: Manifest Field - NEVER INCLUDE:
- [INVALID] inside manifest.json → PLATFORM ERROR
- [INVALID] The field is NOT allowed in Platform 3.0 manifest.json
- [VALID] App name is configured in the Freshworks developer portal, NOT in manifest
- VALIDATION ERROR:
must NOT have additional properties 'name' in manifest.json
[ALERT] CRITICAL: Empty Block Rules - NEVER create empty blocks:
- [INVALID] - INVALID - must have at least 1 function OR omit entirely
- [INVALID] - INVALID - must have at least 1 request OR omit entirely
- [INVALID] - INVALID - must have at least 1 event OR omit entirely
- [VALID] If no functions needed, DO NOT include key at all
- [VALID] If no requests needed, DO NOT include key at all
- VALIDATION ERROR: "/modules/common/functions must NOT have fewer than 1 properties"
Forbidden Platform 2.x patterns (summary)
Never emit:
≠
,
key,
,
$request.post|get|put|delete
, OAuth without
, plain HTML form controls, wrong module for locations, scheduled events in manifest, helpers before
,
without
, unused params.
Full table: references/skill-advanced-topics.md
;
enforcement: rules/freshworks-platform3.mdc
.
README.md Enforcement (MANDATORY)
[FORBIDDEN] NEVER complete app generation without README.md
- [REQUIRED] ALWAYS create README.md for EVERY app
- [REQUIRED] README.md MUST be the FIRST or SECOND file you create
- [REQUIRED] Create it BEFORE running
- [REQUIRED] Minimum sections: App name, description, features, setup, usage
- Apps without README.md are INCOMPLETE and INVALID
Minimum README.md structure:
markdown
# [App Name]
[1-2 sentence description]
## Features
- [Key feature 1]
- [Key feature 2]
## Setup
1. Install app in [Product]
2. [Configuration steps if any]
## Usage
[How to use the app]
App Generation Workflow
App Generation Thinking (before coding)
Use this process for every app request so the right features are generated.
1. Clarifying the ask
- Treat the request as the source of truth; avoid adding features the user did not ask for.
- Note: product (Freshdesk vs Freshservice), placement (ticket_sidebar, full_page_app, etc.), trigger (button click, event, schedule), integrations (Graph, Zapier, etc.).
- If the ask implies context (e.g. "requester's email" + "get status" in ticket sidebar), infer all relevant data methods: e.g. /requester for the action and for who is using the app (show "Logged in as …" or use agent context).
- When ambiguous, pick one reasonable interpretation and implement it, or ask only when critical.
2. Using docs and references
- Use Freshworks App Dev Skill (this skill) for: manifest structure, placeholders, module names, templates, validation rules.
- Use web search for external APIs: required scopes, endpoint paths (e.g. Microsoft Graph presence by UPN vs by user id), limitations.
3. Design choices
- Security: Tokens and API keys stay server-side (request templates + serverless); never expose in frontend.
- Data flow: For "Get status" type flows: button click → need identity/email → get from product context (ticket sidebar → /requester; optionally show agent → ) → call external API with that data in server → one SMI that invokes request template(s) and returns result.
- APIs: If the external API needs multiple steps (e.g. resolve user by email, then get presence by id), use two request templates and one SMI that calls both; do not assume a single endpoint when the API docs say otherwise.
4. Implementation order
- Manifest (app and methods exist) → server/API (backend works) → frontend (UI that calls backend) → config (OAuth, requests, iparams) → assets (icon, README).
- Use a todo list for multi-step work and update it as you go.
5. Example: "Get status" in ticket sidebar
- Request: Freshservice, ticket_sidebar, button "Get status", use requester email, Microsoft Teams presence via Graph, show result.
- Data methods: Use both
client.data.get("ticket")
client.data.get("loggedInUser")
- Graph: If the API requires user-by-email then presence-by-id, use two request templates (get user by UPN, get presence by id) and one SMI that calls both; if presence is available by UPN, one template is enough.
- Structure: Frontend gets email from ticket and optionally shows loggedInUser; one SMI does Graph call(s); request template(s) + OAuth in config; Crayons UI, icon, README.
Step 1: Determine App Type
| Prefer Hybrid / Frontend | Prefer Serverless only |
|---|
| Any UI, placement, dashboard, sync status, resync, config beyond iparams, user says "sync" (unless they insist serverless) | Pure automation, no monitoring, webhook fire-and-forget, user says "no UI" / "background only", notification-only |
Default: Hybrid when unsure.
Do not ask "Do you need UI?"—apply the table.
Disambiguation: .
UI? → yes → backend/events/API? → yes = Hybrid, no = Frontend-only
UI? → no → backend/events? → yes = Serverless, no = invalid
External API → Hybrid +
; OAuth →
.
Step 2: Select Template & Generate Files
| Template folder | When | Main artifacts |
|---|
assets/templates/frontend-skeleton/
| UI only | , , , , |
assets/templates/serverless-skeleton/
| No UI, events/automation | , , , |
assets/templates/hybrid-skeleton/
| UI + SMI + external API | , , , , , |
assets/templates/oauth-skeleton/
| UI + OAuth service | above + + ( only there; see references/api/oauth-docs.md
|
Golden-path recipes (Slack webhook, Microsoft Graph OAuth): references/playbooks/README.md
— load
one playbook instead of hopping across many docs.
CRITICAL: README.md is MANDATORY for every app. It must be created BEFORE validation.
Step 3: Automatic Validation & Auto-Fix (MANDATORY)
CRITICAL: Fix ALL errors - Platform errors AND Lint errors. ZERO TOLERANCE.
AFTER creating ALL app files (INCLUDING README.md), you MUST AUTOMATICALLY:
- Verify README.md exists - If missing, create it NOW before validation
- Run in the app directory (DO NOT ask user to run it)
- If cannot run on + : try fw-setup first; use the LAST RESORT engines downgrade only after the conditions in TOOLCHAIN, SIX ITERATIONS… are met (never as the first move).
- Parse validation output - Identify ALL errors (platform AND lint)
- Attempt Auto-Fix Iteration 1 (ALL Errors):
- Fix JSON structure errors (multiple top-level objects → merge)
- Fix comma placement (missing commas → add, trailing commas → remove)
- Fix template syntax ( → )
- Create missing mandatory files (, , )
- Fix FQDN issues (host with path → FQDN only)
- Fix path issues (missing → add prefix)
- Re-run
- If still failing, Attempt Auto-Fix Iteration 2 (Fatal Errors Only):
- Fix manifest structure issues (wrong module, missing declarations)
- Fix request template declarations (not declared in manifest)
- Fix function declarations (not declared in manifest)
- Fix OAuth structure (missing wrapper, wrong location)
- Fix location placement (wrong module for location)
- Re-run
- After iterations (up to 6):
- [VALID] If ALL errors (platform AND lint) are resolved → Present concise success message
- [WARNING] If ANY errors persist → Keep iterating, NEVER say "complete" with errors
Output after successful validation:
[VALID] App generated successfully in <app-directory>/
Validation: 0 platform errors, 0 lint errors
Next steps:
1. cd <app-directory>
2. fdk run
3. Test in product with ?dev=true
4. When ready to publish: use the publish skill
DO NOT create validation reports or detailed summaries unless explicitly requested.
What to FIX (Platform Errors) - BLOCKING:
- [VALID] JSON parsing errors
- [VALID] Missing required files
- [VALID] Manifest structure errors
- [VALID] Request template errors (FQDN, path, schema)
- [VALID] Missing declarations in manifest
- [VALID] OAuth structure errors
- [VALID] Location placement errors
- [VALID] field in manifest.json → REMOVE IT
What to FIX (Lint Errors) - ALSO BLOCKING:
- [VALID] Async without await → Remove keyword OR add actual
- [VALID] Unused parameters → Remove parameter ENTIRELY (not )
- [VALID] Unreachable code → Remove dead code after return
- [VALID] Function complexity > 7 → Extract helper functions
- [VALID] Missing semicolons → Add semicolons
CRITICAL RULES:
- [INVALID] NEVER ask user to run manually
- [VALID] ALWAYS run validation automatically after file creation
- [VALID] ALWAYS attempt up to 6 fix iterations
- [VALID] ALWAYS re-run after each fix iteration
- [VALID] Fix BOTH platform errors AND lint errors - BOTH are blocking
- [INVALID] NEVER say "app complete" with ANY errors remaining
Reference: rules/validation-workflow.mdc
(autofix patterns).
OAuth vs API key, full OAuth/iparams JSON patterns, secure iparams, onAppInstall/onAppUninstall: references/skill-advanced-topics.md
+
references/architecture/oauth-configuration-latest.md
+
references/api/oauth-docs.md
.
Frontend apps (frontend-skeleton, hybrid-skeleton, oauth-skeleton):
README.md # MANDATORY - create FIRST
app/
├── index.html # MUST include Crayons CDN
├── scripts/app.js # Use IIFE pattern for async
└── styles/
├── style.css
└── images/
└── icon.svg # REQUIRED - FDK validation fails without it
config/
└── iparams.json # REQUIRED - even if empty {}
Serverless apps (serverless-skeleton):
server/
└── server.js # Use $request.invokeTemplate()
config/
└── iparams.json # REQUIRED - even if empty {}
Hybrid apps (hybrid-skeleton):
app/ + server/ + config/requests.json + config/iparams.json
OAuth apps (oauth-skeleton):
app/ + server/ + config/oauth_config.json + config/requests.json + config/iparams.json
Step 4: Automatic Validation & Auto-Fix (MANDATORY - DO NOT SKIP)
CRITICAL: This step is MANDATORY and happens AUTOMATICALLY after creating all files.
AFTER creating ALL app files (including README.md), you MUST AUTOMATICALLY:
- Run in the app directory (DO NOT ask user to run it)
- If cannot run on + : same as Step 3 — fw-setup first; LAST RESORT downgrade only per TOOLCHAIN, SIX ITERATIONS….
- Parse validation output - Identify ALL errors (platform AND lint)
- Attempt Auto-Fix Iteration 1 (ALL Errors):
- Fix JSON structure errors (multiple top-level objects → merge)
- Fix comma placement (missing commas → add, trailing commas → remove)
- Fix template syntax ( → )
- Create missing mandatory files (, , )
- Fix FQDN issues (host with path → FQDN only)
- Fix path issues (missing → add prefix)
- Re-run
- If still failing, Attempt Auto-Fix Iteration 2 (Fatal Errors Only):
- Fix manifest structure issues (wrong module, missing declarations)
- Fix request template declarations (not declared in manifest)
- Fix function declarations (not declared in manifest)
- Fix OAuth structure (missing wrapper, wrong location)
- Fix location placement (wrong module for location)
- Re-run
- After iterations (up to 6):
- [VALID] If ALL errors (platform AND lint) are resolved → Present concise success message
- [WARNING] If ANY errors persist → Keep iterating, NEVER say "complete" with errors
Output after successful validation:
[VALID] App generated successfully in <app-directory>/
Validation: 0 platform errors, 0 lint errors
Next steps:
1. cd <app-directory>
2. fdk run
3. Test in product with ?dev=true
4. When ready to publish: use the publish skill
CRITICAL RULES:
- [INVALID] NEVER say "app complete" without running
- [INVALID] NEVER skip README.md creation
- [VALID] ALWAYS create README.md before validation
- [VALID] ALWAYS run validation automatically after file creation
- [VALID] ALWAYS attempt up to 6 fix iterations
- [VALID] ALWAYS re-run after each fix iteration
Step 5: Validate Against Test Patterns
Before presenting the app, validate against:
references/tests/refusal.json
references/tests/golden.json
Progressive disclosure (reference index)
Full map of paths: references/skill-advanced-topics.md
.
Crayons CDN (required in every HTML):
html
<script async type="module" src="https://cdn.jsdelivr.net/npm/@freshworks/crayons@v4/dist/crayons/crayons.esm.js"></script>
<script async nomodule src="https://cdn.jsdelivr.net/npm/@freshworks/crayons@v4/dist/crayons/crayons.js"></script>
Critical Validations (Always Check)
File Structure
| Check | Requirement |
|---|
| Icon | app/styles/images/icon.svg
|
| Crayons | All frontend HTML includes CDN (above) |
| Engines | Default + ; deprecated 9.8.2 + 18.20.8 only after LAST RESORT rules at top of SKILL.md |
| Product module | At least one product module (may be ) |
| Iparams | Exactly one of: OR custom + assets — not both |
Manifest Validation
| Check | Requirement |
|---|
| Version / shape | "platform-version": "3.0"
|
| Requests / functions | Every template and SMI key declared under |
| Locations | Product locations in product module, not |
| OAuth | wrapper if OAuth used |
| Schedules | No scheduled events in manifest — use |
| Lifecycle | Non-empty iparams → ; cleanup-needed app → |
Code Quality
| Check | Requirement |
|---|
| Params / async | No unused params; only with ; IIFE on frontend init |
| Requests / exports | only; helpers after |
| Control flow | Complexity ≤ 7; no unreachable code |
| Errors | try/catch around async; SMI/events use per |
| Comments | Brief on SMI; explain non-obvious logic only |
Security (see )
| Check | Requirement |
|---|
| Input | SMI args validated; allowlists for enumerated ops |
| Injection | No / / on user input |
| Logging | No or full |
| XSS / secrets | or sanitize; no secrets in notes or UI |
UI Components
| Use | Not |
|---|
| , , , | Plain , , etc. |
| Docs | references/ui/crayons-docs/{component}.md
|
CRITICAL: App Folder Creation Rule
ALWAYS create app in a new folder in the parent directory:
- [INVALID] NEVER create app files directly in current workspace root
- [VALID] ALWAYS create new folder (e.g., , )
- [VALID] Create ALL app files inside this new folder
- Folder name should be kebab-case derived from app name
Example:
bash
# User workspace: /Users/dchatterjee/projects/
# Create app as: /Users/dchatterjee/projects/zapier-sync-app/
# NOT as: /Users/dchatterjee/projects/ (files scattered in root)
Extended pre-generation numbered checklist, duplicate error-prevention lists, autofix iteration detail, and JSON merge examples: references/skill-advanced-topics.md
.
Operational workflow: rules/validation-workflow.mdc
.
Error catalog: references/errors/error-catalog.md
.
App Completion Gates - MANDATORY
[ALERT] ZERO TOLERANCE: An app is NEVER complete unless ALL gates pass.
| Gate | Checks |
|---|
| 1 – Files | ; ; frontend: , , app/styles/images/icon.svg
|
| 2 – Manifest ↔ disk | Every / path exists; events/functions → ; + keys match ; SMI uses (); each key in |
| 3 – Manifest JSON | ; no empty // blocks; implementations for declared functions/events/requests |
| 4 – OAuth (if used) | , , on every field |
| 5 – Code quality | Complexity ≤ 7; async only with ; no unused params |
| 6 – Validate | : 0 platform + 0 lint errors |
If any gate fails: do not call the app complete; fix and re-run
.
Post-Generation Message
After successfully generating an app, provide a concise summary:
[VALID] App generated successfully in <app-directory>/
Validation: [0 platform errors, 0 lint errors]
Next steps:
1. cd <app-directory>
2. fdk run
3. Test in Freshworks product with ?dev=true
4. When ready to publish: use the publish skill
THEN, offer MCP configuration (one time only, if not already configured):
After showing the completion message, check if MCP is already configured and optionally offer setup:
javascript
// Check if MCP tools are available
try {
CallMcpTool("fw-dev-mcp", "list_custom_apps", {});
// Success: MCP already configured, skip prompt
} catch {
// MCP not configured: offer setup
// Full implementation: skills/fw-publish/subagents/mcp-config-prompt.md
Read and follow: skills/fw-publish/subagents/mcp-config-prompt.md
}
Brief inline version (if subagent not available):
═══════════════════════════════════════════════════════════
Optional: Configure Marketplace Publishing
Would you like to set up publishing tools now?
This connects your IDE to the Freshworks Marketplace API.
You can skip this and configure later.
Configure MCP now? (y/N)
═══════════════════════════════════════════════════════════
If YES → Follow
skills/fw-publish/subagents/mcp-config-prompt.md
(Step 3A.1 onwards)
If NO → Skip, user can configure later via
or manually
DO NOT automatically generate:
- [INVALID] Detailed validation reports (.validation-report.md)
- [INVALID] Apps summary documents (APPS-SUMMARY.md)
- [INVALID] Extensive feature lists or comparisons
- [INVALID] Long "Next Steps" sections with multiple subsections
Only generate these when user explicitly requests:
- [VALID] "Create a validation report"
- [VALID] "Generate a summary document"
- [VALID] "Write detailed documentation"
- [VALID] "Compare the apps"
Keep post-generation output minimal and focused on immediate next steps.
Documentation Generation Rules
| Always create | Only if user asks |
|---|
| , , | , , , |
| and/or per template | , (not required for FDK) |
Default: mandatory files + short
only.
Installation, tests, product modules
Skill install commands: .
Structural tests: references/tests/refusal.json
,
references/tests/golden.json
(summarized in
references/skill-advanced-topics.md
).
Modules and locations (authoritative): rules/platform3-modules-locations.mdc
; short mapping in
references/skill-advanced-topics.md
.
Constraints (Enforced Automatically)
- Strict mode: Always reject Platform 2.x patterns
- No inference without source: If not in references, respond "Insufficient platform certainty"
- Terminal logs backend only: only in , not frontend
- Production-ready only: Generate complete, deployable apps
- Forbidden patterns: Listed in refusal tests
- Required patterns: Per SKILL.md validation tables and
rules/freshworks-platform3.mdc
Serverless events, requests, jobs
Events: references/events/event-reference.md
—
/
when required; product events in module
; schedules via
only.
(Freshdesk / Freshservice): references/events/onTicketUpdate-payload-contract.md
; samples
references/test-payloads/server/test_data/support_ticket/onTicketUpdate.json
,
.../service_ticket/onTicketUpdate.json
.
Request templates + OAuth: references/architecture/request-templates-latest.md
,
oauth-configuration-latest.md
,
references/api/request-method-docs.md
(FQDN host,
path,
,
).
API integration patterns: references/api-integration-examples.md
(pagination, rate limiting, error handling, auth patterns, real-world examples).
Jobs: references/runtime/jobs-docs.md
— declare under
; no
in job handlers.
Task → ordered reads (max ~5 files)
Use this sequence
instead of ad-hoc greps across
when the task type is clear:
| Task | Read in order |
|---|
| New hybrid + external HTTP | references/playbooks/README.md
references/architecture/request-templates-latest.md
|
| New OAuth + external API | references/playbooks/microsoft-graph-account-oauth.md
references/architecture/oauth-configuration-latest.md
references/architecture/request-templates-latest.md
|
| Ticket serverless events / filters | references/events/onTicketUpdate-payload-contract.md
references/test-payloads/README.md
freshdesk_support_ticket.md
freshservice_service_tickets.md
|
| Multi-module / placement | rules/platform3-modules-locations.mdc
references/skill-advanced-topics.md
|
| Lint / validate churn | rules/validation-workflow.mdc
rules/freshworks-platform3.mdc
|
If the task is still unclear after step 1, load
.
Summary
- SKILL.md — core enforcement, workflow, validation tables, gates.
- rules/ — always-on Platform 3.0, security, validation, SMI/events, templates, gates.
- references/ — 140+ files; load by topic as needed (including
references/skill-advanced-topics.md
- assets/templates/ — frontend, serverless, hybrid, OAuth skeletons (validate-ready file sets).
- references/playbooks/ — Slack webhook + Microsoft Graph golden paths.
When uncertain, load the specific
file before implementing.