Ads Visual Fs

ads-visual-fs

AI-powered ad creative generation plugin for Funding Societies. Create ads from briefs, reimagine existing creatives, refine elements, resize for platforms, generate full campaign sets, and run A/B variants — all with FS brand compliance and automated quality review built in.

Sample Output

/create — SME Business Loan MY

Feed (4:3)	Story (9:16)

/competitor-reference — Alliance Bank MY

Direct Adaptation	Creative Riff

Style Presets

4 predefined visual styles for /create and /campaign. Each defines required elements, composition, and mood — colors stay flexible from the FS brand palette.

Warm Showcase	Bold Professional

Tech Forward	Aspirational Shadow

Architecture

Plugin Structure

ads-visual-fs/
│
├── .claude-plugin/
│   └── plugin.json (v0.9.1)
│
├── CLAUDE.md                          Agent persona, workflow guide, error handling
│
├── commands/                          ┌─────────────────────────────┐
│   ├── create.md ─────────────────────┤  All commands reference:    │
│   ├── reimagine.md ──────────────────┤  • ask-user-protocol skill  │
│   ├── competitor-reference.md ───────┤  • brand-compliance skill   │
│   ├── refine.md ─────────────────────┤  • quality-review skill     │
│   ├── resize.md ─────────────────────┤  • generate-image.ts script │
│   └── campaign.md ──────────────────┤                             │
│                                      └─────────────────────────────┘
├── skills/
│   ├── ask-user-protocol/             Shared UX protocol
│   │   └── SKILL.md                   (conversational 4-section format)
│   │       ├── Pattern A: Platform Selection (two-step)
│   │       ├── Pattern B: Visual Element Presets
│   │       ├── Pattern C: Concept Selection (w/ previews)
│   │       └── Pattern D: Next Action
│   │
│   ├── brand-compliance/
│   │   ├── SKILL.md                   Colors, fonts, tone, don'ts
│   │   └── references/
│   │       ├── fs-brand-guidelines.md
│   │       └── platform-rules.md      Referenced by Pattern A & B
│   │
│   ├── concept-generation/
│   │   ├── SKILL.md                   3 levels: SAFE/BOLD/EXPERIMENTAL
│   │   └── references/               Strength: 0.85-0.95 / 0.55-0.70 / 0.20-0.40
│   │       └── concept-levels.md
│   │
│   ├── composition-analysis/
│   │   ├── SKILL.md                   Element mapping for /refine, /resize
│   │   └── references/
│   │       └── element-schema.md
│   │
│   ├── marketing-analysis/
│   │   ├── SKILL.md                   Marketing inference for /reimagine
│   │   └── references/
│   │       └── analysis-schema.md
│   │
│   ├── competitor-analysis/
│   │   ├── SKILL.md                   8-dimension analysis for /competitor-ref
│   │   └── references/
│   │       └── analysis-dimensions.md
│   │
│   ├── quality-review/
│   │   └── SKILL.md                   Post-generation QA (brand compliance check)
│   │
│   └── style-presets/
│       ├── SKILL.md                   4 visual style presets for /create and /campaign
│       └── references/
│           ├── style-directory.md     Full style definitions + prompt fragments
│           ├── style-1-warm-showcase.jpg
│           ├── style-2-bold-professional.png
│           ├── style-3-tech-forward.png
│           └── style-4-aspirational-shadow.png
│
├── scripts/
│   ├── generate-image.ts              Gemini API caller + JSONL logging (bun)
│   ├── generate-image.test.ts         Basic tests (bun:test)
│   └── preflight.sh                   Environment check
│
├── assets/
│   └── fs-logo.png                    Bundled FS logo
│
└── ads-output/                        Generated images land here
    ├── generation-log.jsonl           Generation history (auto-created)
    ├── create/
    ├── reimagine/
    ├── refine/
    ├── resize/
    ├── campaign/     └── competitor-reference/

Data Flow

User Input
    │
    ▼
┌──────────┐     ┌───────────────────┐     ┌──────────────────┐
│ Command  │────▶│ ask-user-protocol │────▶│ AskUserQuestion  │
│ (.md)    │     │ (4-section format)│     │ (structured UI)  │
└──────────┘     └───────────────────┘     └──────────────────┘
    │                                              │
    │  reads domain skills:                        │ user picks
    │  • brand-compliance                          ▼
    │  • concept-generation              ┌──────────────────┐
    │  • marketing-analysis              │ Concept prompts  │
    │  • competitor-analysis             │ generated by LLM │
    │  • composition-analysis            └────────┬─────────┘
    │                                             │
    ▼                                             ▼
┌──────────────────┐                   ┌──────────────────┐
│ platform-rules   │──── constraints ─▶│ generate-image.ts│
│ brand-guidelines │──── brand inject ▶│ (Gemini API)     │
└──────────────────┘                   └────────┬─────────┘
                                                │
                                                ▼
                                       ┌──────────────────┐
                                       │ quality-review   │
                                       │ (brand QA check) │
                                       └────────┬─────────┘
                                                │
                                                ▼
                                       ┌──────────────────┐
                                       │ ads-output/*.png  │
                                       │ generation-log    │
                                       └──────────────────┘

Skill Usage Matrix

                brand    concept   composition  marketing  competitor  ask-user  quality  style
                comply   gen       analysis     analysis   analysis    protocol  review   presets
─────────────── ──────── ───────── ──────────── ────────── ────────── ───────── ──────── ───────
/create           ✓        ✓                                             ✓        ✓       ✓
/reimagine        ✓        ✓                       ✓                     ✓        ✓
/competitor-ref   ✓        ✓                                  ✓          ✓        ✓
/refine           ✓                    ✓                                 ✓        ✓
/resize           ✓                    ✓                                 ✓        ✓
/campaign         ✓        ✓                                             ✓        ✓       ✓

Components

Commands (6)

Command	Description
/reimagine <image> [--variants N]	Reimagine an ad with 3 concept variations (SAFE/BOLD/EXPERIMENTAL)
/refine <image> [changes]	Refine specific elements while preserving the rest
/resize <image> [platforms]	Adapt for different platform formats
/create [--variants N]	Create a new ad from a marketing brief
/campaign [--variants N]	Generate a full campaign set across multiple platforms from a single brief
/competitor-reference <image> [--variants N]	Analyze a competitor ad and generate FS-branded ads inspired by its creative strategies

Workflow Skills (5)

Auto-trigger on natural language — same orchestration as commands.

Skill	Triggers On
reimagine	"reimagine this ad", "create variations", "remix this creative"
refine	"change the headline", "adjust the CTA", "tweak this ad"
resize	"resize for Instagram", "make platform versions", "adapt for social"
create	"create an ad for", "design a new ad", "make marketing visuals"
competitor-reference	"analyze this competitor ad", "do something like this competitor ad", "inspired by this ad"

Shared Skills (7)

Context-activated domain expertise — auto-activates during workflows.

Skill	Activation Context	Used By
marketing-analysis	Marketing inference on ad images	Reimagine
composition-analysis	Visual element/layout analysis	Refine, Resize
concept-generation	Creative concept variations	Reimagine, Create, Campaign, Competitor Reference
competitor-analysis	Creative strategy extraction from competitor ads	Competitor Reference
brand-compliance	Any FS ad creative work	All 6
quality-review	Post-generation brand QA check	All 6
style-presets	Visual style selection (4 presets + custom)	Create, Campaign

Image Generation Script

scripts/generate-image.ts — Calls the Gemini API directly via Bash. No MCP server needed.

# Text-to-image
bun scripts/generate-image.ts --prompt "A professional ad..." --image out.png --ar 1:1

# Image-to-image (with reference)
bun scripts/generate-image.ts --prompt "Adapt this ad..." --image out.png --ref source.png --ar 9:16

# With strength control
bun scripts/generate-image.ts --prompt "..." --image out.png --ref source.png --strength 0.7

Setup

1. Get a Gemini API Key

1. Go to Google AI Studio
2. Create an API key
3. Set the environment variable:

export GEMINI_API_KEY="your-api-key-here"

2. Install Bun (if not already installed)

curl -fsSL https://bun.sh/install | bash

Or the script will fall back to npx -y bun if bun is not installed.

3. Install the Plugin

Install from GitHub: jeffrey94/jeffrey-skills → ads-visual-fs

4. Preflight Check

Run the preflight script to verify everything is set up correctly:

bash scripts/preflight.sh

This checks: Bun installation, API key validity, script accessibility, input folder, and CLAUDE.md presence.

Getting the Best Results

The plugin works out of the box with slash commands, but you'll get significantly better output by setting up your project with the right context.

Recommended Project Structure

your-project/
├── CLAUDE.md              # Agent role, behavior, brand context
├── .env                   # GEMINI_API_KEY=your-key (never commit this)
├── input/                 # Source materials
│   ├── branding-guide.pdf # Brand guidelines, visual identity
│   ├── target-segment.pdf # Audience personas, segments
│   ├── style-ref.jpg      # Visual style references
│   └── brief.pdf          # Campaign brief (optional)
└── ads-output/            # Generated images (auto-created)

Setting Up CLAUDE.md

The plugin includes a CLAUDE.md that frames Claude as a marketing executive who asks strategic questions (objective, audience, market, channels) before producing visuals. It's loaded automatically when the plugin is active.

To customize it for your project, copy it to your project root and edit:

cp "$(claude plugin path ads-visual-fs)/CLAUDE.md" ./CLAUDE.md

Input Materials That Improve Output

Material	Why It Helps	Format
Branding guide	Enforces correct colors, fonts, logo usage, tone	PDF, image
Target segment doc	Sharpens messaging for the right audience	PDF, text
Style references	Gives visual direction beyond brand guidelines	JPG, PNG
Campaign brief	Provides objective, offer, channels, constraints	PDF, text
Existing ads	Source material for /reimagine, /refine, /resize	JPG, PNG
Competitor examples	Context for differentiation and positioning	JPG, PNG

The more context you provide in ./input/, the less back-and-forth is needed and the more on-brand the output will be.

Tips

• Strategy before visuals — Start by discussing the campaign objective and audience. Use /create only after the brief is clear.
• Right command for the job — /campaign for multi-platform sets, /create for single-platform exploration, /reimagine for fresh concepts from an existing ad, /refine for surgical edits, /resize for platform adaptation.
• Iterate in sequence — A typical flow: /create → pick the best → /refine to polish → /resize for all platforms. Or: /campaign to do it all in one go.
• A/B test with variants — Add --variants 3 to generate variations with different CTAs, colorways, or headline emphasis. Great for testing what resonates.
• Provide style references — A single reference image can dramatically improve visual consistency across generated ads.
• Review the analysis step — Each command presents its analysis for confirmation. Correct any misinterpretations before generation.

Usage

Commands

/create
/create --variants 3
/campaign
/campaign --variants 2
/reimagine ./path/to/ad.png
/reimagine ./path/to/ad.png --variants 3
/refine ./path/to/ad.png make CTA more urgent
/resize ./path/to/ad.png instagram linkedin tiktok
/competitor-reference ./path/to/competitor-ad.png

Natural Language

"Create an ad for our SME loan targeting Singapore"
"Create a full campaign for SME loans across Instagram, LinkedIn, and TikTok"
"Reimagine this ad with fresh variations" (attach image)
"Give me 3 A/B variants of this ad" (attach image)
"Change the headline to '48-Hour Funding'" (attach image)
"Resize this for Instagram and LinkedIn" (attach image)
"I love this competitor ad, can we do something similar for FS?" (attach competitor image)

Output

Generated images are saved to ./ads-output/ organized by workflow:

ads-output/
├── generation-log.jsonl                              Generation history
├── create/<campaign-name>/<level>.png
├── campaign/<campaign-slug>/<platform>.png
├── reimagine/<concept-title>.png
├── refine/<description>-v{1,2,3}.png
├── resize/<platform>.png
└── competitor-reference/<competitor-slug>/<concept-title>.png

Brand Guidelines (FSMY, May 2025)

Color	Hex	Role
Light Gray	#F1F1F2	Backgrounds
Yellow	#FFDE0F	Accent, highlights
Purple	#5203EA	Primary brand
Teal	#27E4CD	Secondary accents
Blue	#2C50FF	Links, interactive

• Fonts: Poppins SemiBold/Light (headings), Inter Regular/Bold (body)
• Strapline: "Stronger SMEs, Stronger Societies"
• Tone: Professional, trustworthy, empowering
• Regulatory: Market-appropriate disclaimers auto-included