Widget Generator Skill

This skill guides creation of widget plugins for prompts.chat. Widgets are injected into prompt feeds to display promotional content, sponsor cards, or custom interactive components.

Overview

Widgets support two rendering modes:

1. Standard prompt widget - Uses default PromptCard styling (like coderabbit.ts)
2. Custom render widget - Full custom React component (like book.tsx)

Prerequisites

Before creating a widget, gather from the user:

Step 1: Gather Widget Configuration

Ask the user for the following configuration options:

Basic Info

- id: string (unique, kebab-case)
- name: string (display name)
- slug: string (URL-friendly identifier)
- title: string (card title)
- description: string (card description)

Content (for standard mode)

- content: string (prompt content, can be multi-line markdown)
- type: "TEXT" | "STRUCTURED"
- structuredFormat?: "json" | "yaml" (if type is STRUCTURED)

Categorization

- tags?: string[] (e.g., ["AI", "Development"])
- category?: string (e.g., "Development", "Writing")

Action Button

- actionUrl?: string (CTA link)
- actionLabel?: string (CTA button text)

Sponsor (optional)

- sponsor?: {
    name: string
    logo: string (path to light mode logo)
    logoDark?: string (path to dark mode logo)
    url: string (sponsor website)
  }

Positioning Strategy

- positioning: {
    position: number (0-indexed start position, default: 2)
    mode: "once" | "repeat" (default: "once")
    repeatEvery?: number (for repeat mode, e.g., 30)
    maxCount?: number (max occurrences, default: 1 for once, unlimited for repeat)
  }

Injection Logic

- shouldInject?: (context) => boolean
  Context contains:
  - filters.q: search query
  - filters.category: category name
  - filters.categorySlug: category slug
  - filters.tag: tag filter
  - filters.sort: sort option
  - itemCount: total items in feed

Step 2: Create Widget File

Standard Widget (TypeScript only)

Create file: src/lib/plugins/widgets/{widget-id}.ts

typescript
1import type { WidgetPlugin } from "./types";
2
3export const {widgetId}Widget: WidgetPlugin = {
4  id: "{widget-id}",
5  name: "{Widget Name}",
6  prompts: [
7    {
8      id: "{prompt-id}",
9      slug: "{prompt-slug}",
10      title: "{Title}",
11      description: "{Description}",
12      content: `{Multi-line content here}`,
13      type: "TEXT",
14      // Optional sponsor
15      sponsor: {
16        name: "{Sponsor Name}",
17        logo: "/sponsors/{sponsor}.svg",
18        logoDark: "/sponsors/{sponsor}-dark.svg",
19        url: "{sponsor-url}",
20      },
21      tags: ["{Tag1}", "{Tag2}"],
22      category: "{Category}",
23      actionUrl: "{action-url}",
24      actionLabel: "{Action Label}",
25      positioning: {
26        position: 2,
27        mode: "repeat",
28        repeatEvery: 50,
29        maxCount: 3,
30      },
31      shouldInject: (context) => {
32        const { filters } = context;
33        
34        // Always show when no filters active
35        if (!filters?.q && !filters?.category && !filters?.tag) {
36          return true;
37        }
38        
39        // Add custom filter logic here
40        return false;
41      },
42    },
43  ],
44};

Custom Render Widget (TSX with React)

Create file: src/lib/plugins/widgets/{widget-id}.tsx

tsx
1import Link from "next/link";
2import Image from "next/image";
3import { Button } from "@/components/ui/button";
4import type { WidgetPlugin } from "./types";
5
6function {WidgetName}Widget() {
7  return (
8    <div className="group border rounded-[var(--radius)] overflow-hidden hover:border-foreground/20 transition-colors bg-gradient-to-br from-primary/5 via-background to-primary/10 p-5">
9      {/* Custom widget content */}
10      <div className="flex flex-col items-center gap-4">
11        {/* Image/visual element */}
12        <div className="relative w-full aspect-video">
13          <Image
14            src="/path/to/image.jpg"
15            alt="{Alt text}"
16            fill
17            className="object-cover rounded-lg"
18          />
19        </div>
20        
21        {/* Content */}
22        <div className="w-full text-center">
23          <h3 className="font-semibold text-base mb-1.5">{Title}</h3>
24          <p className="text-xs text-muted-foreground mb-4">{Description}</p>
25          <Button asChild size="sm" className="w-full">
26            <Link href="{action-url}">{Action Label}</Link>
27          </Button>
28        </div>
29      </div>
30    </div>
31  );
32}
33
34export const {widgetId}Widget: WidgetPlugin = {
35  id: "{widget-id}",
36  name: "{Widget Name}",
37  prompts: [
38    {
39      id: "{prompt-id}",
40      slug: "{prompt-slug}",
41      title: "{Title}",
42      description: "{Description}",
43      content: "",
44      type: "TEXT",
45      tags: ["{Tag1}", "{Tag2}"],
46      category: "{Category}",
47      actionUrl: "{action-url}",
48      actionLabel: "{Action Label}",
49      positioning: {
50        position: 10,
51        mode: "repeat",
52        repeatEvery: 60,
53        maxCount: 4,
54      },
55      shouldInject: () => true,
56      render: () => <{WidgetName}Widget />,
57    },
58  ],
59};

Step 3: Register Widget

Edit src/lib/plugins/widgets/index.ts:

1. Add import at top:

typescript
1import { {widgetId}Widget } from "./{widget-id}";

2. Add to widgetPlugins array:

typescript
1const widgetPlugins: WidgetPlugin[] = [
2  coderabbitWidget,
3  bookWidget,
4  {widgetId}Widget, // Add new widget
5];

Step 4: Add Sponsor Assets (if applicable)

If the widget has a sponsor:

1. Add light logo: public/sponsors/{sponsor}.svg
2. Add dark logo (optional): public/sponsors/{sponsor}-dark.svg

Positioning Examples

Show once at position 5

typescript
1positioning: {
2  position: 5,
3  mode: "once",
4}

Repeat every 30 items, max 5 times

typescript
1positioning: {
2  position: 3,
3  mode: "repeat",
4  repeatEvery: 30,
5  maxCount: 5,
6}

Unlimited repeating

typescript
1positioning: {
2  position: 2,
3  mode: "repeat",
4  repeatEvery: 25,
5  // No maxCount = unlimited
6}

shouldInject Examples

Always show

typescript
1shouldInject: () => true,

Only when no filters active

typescript
1shouldInject: (context) => {
2  const { filters } = context;
3  return !filters?.q && !filters?.category && !filters?.tag;
4},

Show for specific categories

typescript
1shouldInject: (context) => {
2  const slug = context.filters?.categorySlug?.toLowerCase();
3  return slug?.includes("development") || slug?.includes("coding");
4},

Show when search matches keywords

typescript
1shouldInject: (context) => {
2  const query = context.filters?.q?.toLowerCase() || "";
3  return ["ai", "automation", "workflow"].some(kw => query.includes(kw));
4},

Show only when enough items

typescript
1shouldInject: (context) => {
2  return (context.itemCount ?? 0) >= 10;
3},

Custom Render Patterns

Card with gradient background

tsx
1<div className="border rounded-[var(--radius)] overflow-hidden bg-gradient-to-br from-primary/5 via-background to-primary/10 p-5">

Sponsor badge

tsx
1<div className="flex items-center gap-2 mb-2">
2  <span className="text-xs font-medium text-primary">Sponsored</span>
3</div>

Responsive image

tsx
1<div className="relative w-full aspect-video">
2  <Image src="/image.jpg" alt="..." fill className="object-cover" />
3</div>

CTA button

tsx
1<Button asChild size="sm" className="w-full">
2  <Link href="https://example.com">
3    Learn More
4    <ArrowRight className="ml-2 h-3.5 w-3.5" />
5  </Link>
6</Button>

Verification

1. Run type check:

   bash
   1npx tsc --noEmit

2. Start dev server:

   bash
   1npm run dev

3. Navigate to /discover or /feed to verify widget appears at configured positions

Type Reference

typescript
1interface WidgetPrompt {
2  id: string;
3  slug: string;
4  title: string;
5  description: string;
6  content: string;
7  type: "TEXT" | "STRUCTURED";
8  structuredFormat?: "json" | "yaml";
9  sponsor?: {
10    name: string;
11    logo: string;
12    logoDark?: string;
13    url: string;
14  };
15  tags?: string[];
16  category?: string;
17  actionUrl?: string;
18  actionLabel?: string;
19  positioning?: {
20    position?: number;      // Default: 2
21    mode?: "once" | "repeat"; // Default: "once"
22    repeatEvery?: number;   // For repeat mode
23    maxCount?: number;      // Max occurrences
24  };
25  shouldInject?: (context: WidgetContext) => boolean;
26  render?: () => ReactNode; // For custom rendering
27}
28
29interface WidgetPlugin {
30  id: string;
31  name: string;
32  prompts: WidgetPrompt[];
33}

Common Issues