Agent skill

widget-generator

Generate customizable widget plugins for the prompts.chat feed system

View SKILL.md on GitHub Repository
Stars 159,339
Forks 20,869

Install this agent skill to your Project

npx add-skill https://github.com/f/prompts.chat/tree/main/.windsurf/skills/widget-generator

SKILL.md

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:

Parameter Required Description
Widget ID ✅ Unique identifier (kebab-case, e.g., my-sponsor)
Widget Name ✅ Display name for the plugin
Rendering Mode ✅ standard or custom
Sponsor Info ❌ Name, logo, logoDark, URL (for sponsored widgets)

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
import type { WidgetPlugin } from "./types";

export const {widgetId}Widget: WidgetPlugin = {
  id: "{widget-id}",
  name: "{Widget Name}",
  prompts: [
    {
      id: "{prompt-id}",
      slug: "{prompt-slug}",
      title: "{Title}",
      description: "{Description}",
      content: `{Multi-line content here}`,
      type: "TEXT",
      // Optional sponsor
      sponsor: {
        name: "{Sponsor Name}",
        logo: "/sponsors/{sponsor}.svg",
        logoDark: "/sponsors/{sponsor}-dark.svg",
        url: "{sponsor-url}",
      },
      tags: ["{Tag1}", "{Tag2}"],
      category: "{Category}",
      actionUrl: "{action-url}",
      actionLabel: "{Action Label}",
      positioning: {
        position: 2,
        mode: "repeat",
        repeatEvery: 50,
        maxCount: 3,
      },
      shouldInject: (context) => {
        const { filters } = context;
        
        // Always show when no filters active
        if (!filters?.q && !filters?.category && !filters?.tag) {
          return true;
        }
        
        // Add custom filter logic here
        return false;
      },
    },
  ],
};

Custom Render Widget (TSX with React)

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

tsx
import Link from "next/link";
import Image from "next/image";
import { Button } from "@/components/ui/button";
import type { WidgetPlugin } from "./types";

function {WidgetName}Widget() {
  return (
    <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">
      {/* Custom widget content */}
      <div className="flex flex-col items-center gap-4">
        {/* Image/visual element */}
        <div className="relative w-full aspect-video">
          <Image
            src="/path/to/image.jpg"
            alt="{Alt text}"
            fill
            className="object-cover rounded-lg"
          />
        </div>
        
        {/* Content */}
        <div className="w-full text-center">
          <h3 className="font-semibold text-base mb-1.5">{Title}</h3>
          <p className="text-xs text-muted-foreground mb-4">{Description}</p>
          <Button asChild size="sm" className="w-full">
            <Link href="{action-url}">{Action Label}</Link>
          </Button>
        </div>
      </div>
    </div>
  );
}

export const {widgetId}Widget: WidgetPlugin = {
  id: "{widget-id}",
  name: "{Widget Name}",
  prompts: [
    {
      id: "{prompt-id}",
      slug: "{prompt-slug}",
      title: "{Title}",
      description: "{Description}",
      content: "",
      type: "TEXT",
      tags: ["{Tag1}", "{Tag2}"],
      category: "{Category}",
      actionUrl: "{action-url}",
      actionLabel: "{Action Label}",
      positioning: {
        position: 10,
        mode: "repeat",
        repeatEvery: 60,
        maxCount: 4,
      },
      shouldInject: () => true,
      render: () => <{WidgetName}Widget />,
    },
  ],
};

Step 3: Register Widget

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

  1. Add import at top:
typescript
import { {widgetId}Widget } from "./{widget-id}";
  1. Add to widgetPlugins array:
typescript
const widgetPlugins: WidgetPlugin[] = [
  coderabbitWidget,
  bookWidget,
  {widgetId}Widget, // Add new widget
];

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
positioning: {
  position: 5,
  mode: "once",
}

Repeat every 30 items, max 5 times

typescript
positioning: {
  position: 3,
  mode: "repeat",
  repeatEvery: 30,
  maxCount: 5,
}

Unlimited repeating

typescript
positioning: {
  position: 2,
  mode: "repeat",
  repeatEvery: 25,
  // No maxCount = unlimited
}

shouldInject Examples

Always show

typescript
shouldInject: () => true,

Only when no filters active

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

Show for specific categories

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

Show when search matches keywords

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

Show only when enough items

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

Custom Render Patterns

Card with gradient background

tsx
<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
<div className="flex items-center gap-2 mb-2">
  <span className="text-xs font-medium text-primary">Sponsored</span>
</div>

Responsive image

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

CTA button

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

Verification

  1. Run type check:

    bash
    npx tsc --noEmit

  2. Start dev server:

    bash
    npm run dev

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

Type Reference

typescript
interface WidgetPrompt {
  id: string;
  slug: string;
  title: string;
  description: string;
  content: string;
  type: "TEXT" | "STRUCTURED";
  structuredFormat?: "json" | "yaml";
  sponsor?: {
    name: string;
    logo: string;
    logoDark?: string;
    url: string;
  };
  tags?: string[];
  category?: string;
  actionUrl?: string;
  actionLabel?: string;
  positioning?: {
    position?: number;      // Default: 2
    mode?: "once" | "repeat"; // Default: "once"
    repeatEvery?: number;   // For repeat mode
    maxCount?: number;      // Max occurrences
  };
  shouldInject?: (context: WidgetContext) => boolean;
  render?: () => ReactNode; // For custom rendering
}

interface WidgetPlugin {
  id: string;
  name: string;
  prompts: WidgetPrompt[];
}

Common Issues

Issue Solution
Widget not showing Check shouldInject logic, verify registration in index.ts
TypeScript errors Ensure imports from ./types, check sponsor object shape
Styling issues Use Tailwind classes, match existing widget patterns
Position wrong Remember positions are 0-indexed, check repeatEvery value

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

f/prompts.chat

book-translation

Translate "The Interactive Book of Prompting" chapters and UI strings to a new language

159,339 20,869
Explore
f/prompts.chat

skill-lookup

Search, retrieve, and install Agent Skills from the prompts.chat registry using MCP tools. Use when the user asks to find skills, browse skill catalogs, install a skill for Claude, or extend Claude's capabilities with reusable AI agent components.

159,339 20,869
Explore
f/prompts.chat

prompt-lookup

Activates when the user asks about AI prompts, needs prompt templates, wants to search for prompts, or mentions prompts.chat. Use for discovering, retrieving, and improving prompts.

159,339 20,869
Explore
davila7/claude-code-templates

verl-rl-training

Provides guidance for training LLMs with reinforcement learning using verl (Volcano Engine RL). Use when implementing RLHF, GRPO, PPO, or other RL algorithms for LLM post-training at scale with flexible infrastructure backends.

23,776 2,298
Explore
davila7/claude-code-templates

openrlhf-training

High-performance RLHF framework with Ray+vLLM acceleration. Use for PPO, GRPO, RLOO, DPO training of large models (7B-70B+). Built on Ray, vLLM, ZeRO-3. 2× faster than DeepSpeedChat with distributed architecture and GPU resource sharing.

23,776 2,298
Explore
davila7/claude-code-templates

gguf-quantization

GGUF format and llama.cpp quantization for efficient CPU/GPU inference. Use when deploying models on consumer hardware, Apple Silicon, or when needing flexible quantization from 2-8 bit without GPU requirements.

23,776 2,298
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results