Generate valid JSON import files for the FSAI applicant portal, custom forms, and email sequences. Use when asked to "generate content", "content generator", "portal json", "sequences json", "forms json", "fsai content", "brand onboarding content", or when working with FSAI brand onboarding.
How this skill is triggered — by the user, by Claude, or both
Slash command
/fsai-workflow-actions:content-generatorThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
This skill generates valid JSON import files for the FSAI applicant portal, custom forms, and email sequences. The output is consumed by the FSAI backend's content import endpoints.
This skill generates valid JSON import files for the FSAI applicant portal, custom forms, and email sequences. The output is consumed by the FSAI backend's content import endpoints.
Content generation follows a three-phase process. Each phase builds on the previous one because later phases reference content created in earlier phases.
output/forms.json)Why first: Custom forms must be imported into the platform before the portal can reference them. The portal's formName fields must match forms that actually exist.
Setup — If metadata/ and output/ directories don't exist in the current workspace, create them.
Metadata check — Look for a metadata/*.json file. If none found, tell the user:
"No metadata file found. Export one from the FSAI admin panel and place it in
metadata/. The file contains brand info, available forms, and uploaded assets needed to generate valid content."
Read metadata — Examine metadata.availableForms to understand what default forms already exist (fields with dataLocation are defaults, those without are custom). Identify gaps — what additional questions does this brand need that aren't covered by defaults?
Generate output/forms.json — Create custom forms following the Forms JSON Schema below. Use useExistingFields to pull default fields into custom form pages where it makes sense. Never set dataLocation on new fields. Skip this phase if the brand only needs the default forms.
Validate — Copy the validator and run it:
cp "${CLAUDE_PLUGIN_ROOT}/skills/content-generator/references/validate.ts" ./validate.ts
npx tsx validate.ts
Hand off to user — Present the forms.json and tell them:
"Import this forms.json via the super admin panel, then re-export the metadata so the next phase can reference the newly created forms by name."
Wait for the user to provide updated metadata before proceeding to Phase 2.
output/portal.json)Why second: The portal references forms by name. With the updated metadata (which now includes custom forms from Phase 1), all formName references will validate correctly.
Read updated metadata — The user should have placed a fresh metadata export in metadata/. Read it to see all available forms (defaults + newly imported custom forms), assets, and brand context.
Generate output/portal.json — Build the portal sections and steps following the Portal JSON Schema below. Reference both default and custom form names. Use real asset IDs from metadata for video/slide steps.
Validate — Run npx tsx validate.ts and fix any errors.
Present to user — Show the portal structure. They can import it via the super admin panel.
output/sequences.json)Why last: Sequences are independent of forms/portal but are typically generated in the same session.
Generate output/sequences.json — Create email sequences following the Sequences JSON Schema below. Use tracking link placeholders and merge tags.
Validate — Run npx tsx validate.ts and fix any errors.
Present to user — Show the sequences. They can import them via the super admin panel.
If the user only needs one file type (e.g., "just generate the portal"), skip the other phases. If they ask for everything at once and custom forms aren't needed, generate portal and sequences together. The phased workflow only matters when custom forms are involved, because forms must exist in the platform before the portal can reference them.
output/portal.json)interface ImportPortalJson {
/** Main title displayed at the top of the applicant portal */
title: string;
/** Subtitle displayed below the title */
subtitle: string;
/** Ordered list of portal sections */
sections: ImportPortalSectionJson[];
}
interface ImportPortalSectionJson {
/** Section heading */
title: string;
/** Optional section description */
subtitle?: string;
/** Optional emoji shown next to the section title */
emoji?: string;
/** Ordered list of steps within this section */
steps: ImportPortalStepJson[];
}
interface ImportPortalStepJson {
/** Step heading shown to the applicant */
title: string;
/** Step description / instructions */
subtitle: string;
/** The type of interaction this step presents */
action:
| 'video' // Embedded video player (requires assetId referencing a video asset)
| 'form' // Dynamic form (requires formName matching an available form)
| 'slides' // PDF/image slides viewer
| 'studio_slides' // Interactive slide deck from the studio (requires assetId referencing a slide asset)
| 'call' // Schedule a call (Calendly or similar)
| 'sign' // E-signature document
| 'document' // Downloadable document
| 'visit_link' // External link (requires url)
| 'upload' // File upload prompt
| 'invite_team'; // Invite team members step
/** Form name to bind to (required for action: 'form'). Must match a name from metadata availableForms. */
formName?: string | null;
/** Asset UUID to bind to (required for action: 'video' and 'studio_slides'). Must match an assetId from metadata assets. */
assetId?: string;
/** Whether completing this step creates a deal in the pipeline */
createsDeal?: boolean;
/** Whether this step is the FDD (Franchise Disclosure Document) step */
isFdd?: boolean;
/** Whether this step is hidden from the applicant by default */
hidden?: boolean;
/** URL for visit_link steps or fallback video URL */
url?: string | null;
/** Arbitrary JSON data attached to the step (rarely used) */
json?: unknown | null;
}
output/forms.json)interface ImportFormsJson {
/** List of custom forms to create */
forms: ImportFormJson[];
}
interface ImportFormJson {
/** Display name of the form */
name: string;
/** Optional description */
description?: string;
/** Which entity type this form collects data for */
appliesTo: 'user' | 'franchisee-org' | 'location';
/** Optional group name — creates or matches an existing form group */
groupName?: string;
/** Ordered list of pages in this form */
pages: ImportFormPageJson[];
}
interface ImportFormPageJson {
/** Page heading */
title: string;
/** Optional page description */
subtitle?: string;
/** New custom fields to create on this page */
fields: ImportFormFieldJson[];
/** Field names from default forms to move into this page */
useExistingFields?: string[];
}
interface ImportFormFieldJson {
/** Internal field name */
name: string;
/** Display text shown to the user */
question: string;
/** Additional help text */
description?: string;
/** Input placeholder text */
placeholder?: string;
/** Field input type */
type: 'short-text' | 'long-text' | 'currency' | 'number' | 'date' | 'url'
| 'email' | 'phone' | 'multiselect' | 'singleselect' | 'boolean' | 'dropdown';
/** Whether the field is required (default false) */
required?: boolean;
/** Options for multiselect, singleselect, and dropdown types */
options?: string[];
}
dataLocation — imported fields are always custom. Only default fields have dataLocation.useExistingFields to reference default fields from metadata by name rather than recreating them. This moves the field from its default form into your custom form.metadata.availableForms[].pages[].fields[] to see what questions are already collected. Don't duplicate them.dataLocation in metadata are default fields that map to database columns. Reference them via useExistingFields if you want them in a custom form.dataLocation are custom fields stored as JSON.appliesTo scoping — user for applicant/member data, franchisee-org for business entity data, location for location-specific data.output/sequences.json)interface ImportSequencesJson {
/** List of email sequences to create */
sequences: ImportSequenceJson[];
}
interface ImportSequenceJson {
/** Display name of the sequence (e.g., "Welcome Series", "FDD Follow-up") */
name: string;
/** Event trigger that starts this sequence (e.g., "welcome", "post_application", "fdd_followup") */
event: string;
/** Department that owns this sequence */
department: 'sales' | 'marketing' | 'operations';
/** Ordered list of emails in this sequence */
emails: ImportSequenceEmailJson[];
}
interface ImportSequenceEmailJson {
/** Internal name for this email template */
name: string;
/** Email subject line (supports {{firstName}} and other merge tags) */
subjectLine: string;
/** Email body in Markdown format. Supports basic formatting: headers, bold, italic, links, lists. */
bodyMarkdown: string;
/** Number of days to wait after the previous email (or after the trigger event for the first email). Must be >= 0. */
delayDays: number;
}
The metadata file (metadata/*.json) exported from the FSAI admin panel has this structure:
brand — name, website, portalDomain, apTitle, apSubtitleavailableForms[] — id, name, appliesTo, groupName, plus pages[] each with title and fields[]. Each field has: name, question, type, required, description, options, dataLocation. Use this to understand what data is already being collected and which fields can be referenced via useExistingFields.assets.portalSlides[] — assetId (UUID), name, createdAtassets.portalVideos[] — assetId (UUID), name, duration, createdAtassets.other[] — assetId (UUID), name, fileTypeexistingPortal — sectionCount, stepCount (what the brand already has)existingSequences — campaignCount (what the brand already has)sequenceEventExamples[] — Standard event names (e.g., "welcome", "post_application", "fdd_followup"). Non-standard events produce validator warnings but are allowed.trackingLinks — Pre-created tracking links for use in email content (or null if not yet created)
returnToPortal — slug, url (tracking URL), destination (final URL)portalSignUp — slug, url (tracking URL), destination (final URL)These rules are enforced by the validator and the backend import service.
studio_slides step MUST have an assetId that matches a UUID from metadata.assets.portalSlidesvideo step MUST have an assetId that matches a UUID from metadata.assets.portalVideosform step SHOULD have a formName that matches the name field of an entry in metadata.availableFormsstudio_slides steps must reference slide assets (from portalSlides), not video assetsvideo steps must reference video assets (from portalVideos), not slide assetsslides steps do not require an assetId (they use uploaded PDF/images, not studio assets)metadata.assets.other can be referenced but are not typically used in portal stepsvisit_link steps should include a url fieldvideo, form, slides, studio_slides, call, sign, document, visit_link, upload, invite_team
sales, marketing, operations
When generating email sequences, use tracking link placeholders instead of raw portal URLs. These are resolved to actual tracking URLs during import, enabling click analytics.
| Placeholder | Resolves To |
|---|---|
{{link:portal}} | Tracking URL for return to portal |
{{link:signup}} | Tracking URL for signup page |
Example:
[Return to your portal]({{link:portal}})
[Complete your application]({{link:signup}})
Also supported for backward compatibility:
{{trackingLinks.returnToPortal.url}}{{trackingLinks.portalSignUp.url}}If tracking links don't exist for the brand (e.g., portal domain not set), placeholders remain unchanged. The email editor will show the literal placeholder text, which can be manually replaced.
Merge tags allow you to personalize email content with recipient data. They are converted to interactive variable nodes in the email editor.
| Tag | Description |
|---|---|
{{first_name}} | Recipient's first name |
{{last_name}} | Recipient's last name |
{{email}} | Recipient's email address |
{{phone}} | Recipient's phone number |
Use fallback values for when recipient data is missing:
{{first_name,fallback=Friend}}
{{last_name,fallback=Valued Customer}}
The fallback value appears if the merge tag has no data for that recipient.
Merge tags can be used in:
"Welcome {{first_name}}!"**Hello {{first_name}}!** (bold text with merge tag){{first_name}}, [click here](url) to continue{
"name": "Welcome Email",
"subjectLine": "Welcome {{first_name}}!",
"bodyMarkdown": "# Hello {{first_name,fallback=there}}!\n\nThank you for your interest.\n\nWe'll send updates to **{{email}}**.\n\n[View your portal]({{link:portal}})\n\nBest,\nThe Team",
"delayDays": 0
}
Guides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.
npx claudepluginhub franchiseai/claude-code-plugins --plugin fsai-workflow-actions