Chatgpt Apps

SKILL.md

---
name: chatgpt-apps
description: Complete ChatGPT Apps builder - Create, design, implement, test, and deploy ChatGPT Apps with MCP servers, widgets, auth, database integration, and automated deployment
homepage: https://github.com/hollaugo/prompt-circle-claude-plugins
user-invocable: true
---

# ChatGPT Apps Builder

Complete workflow for building, testing, and deploying ChatGPT Apps from concept to production.

## Commands

- `/chatgpt-apps new` - Create a new ChatGPT App
- `/chatgpt-apps add-tool` - Add an MCP tool to your app
- `/chatgpt-apps add-widget` - Add a widget to your app
- `/chatgpt-apps add-auth` - Configure authentication
- `/chatgpt-apps add-database` - Set up database
- `/chatgpt-apps validate` - Validate your app
- `/chatgpt-apps test` - Run tests
- `/chatgpt-apps deploy` - Deploy to production
- `/chatgpt-apps resume` - Resume working on an app

---

## Table of Contents

1. [Create New App](#1-create-new-app)
2. [Add MCP Tool](#2-add-mcp-tool)
3. [Add Widget](#3-add-widget)
4. [Add Authentication](#4-add-authentication)
5. [Add Database](#5-add-database)
6. [Generate Golden Prompts](#6-generate-golden-prompts)
7. [Validate App](#7-validate-app)
8. [Test App](#8-test-app)
9. [Deploy App](#9-deploy-app)
10. [Resume App](#10-resume-app)

---

## 1. Create New App

**Purpose:** Create a new ChatGPT App from concept to working code.

### Workflow

#### Phase 1: Conceptualization

1. **Ask for the app idea**
   "What ChatGPT App would you like to build? Describe what it does and the problem it solves."

2. **Analyze against UX Principles**
   - **Conversational Leverage**: What can users accomplish through natural language?
   - **Native Fit**: How does this integrate with ChatGPT's conversational flow?
   - **Composability**: Can tools work independently and combine with other apps?

3. **Check for Anti-Patterns**
   - Static website content display
   - Complex multi-step workflows requiring external tabs
   - Duplicating ChatGPT's native capabilities
   - Ads or upsells

4. **Define Use Cases**
   Create 3-5 primary use cases with user stories.

#### Phase 2: Design

1. **Tool Topology**
   - Query tools (readOnlyHint: true)
   - Mutation tools (destructiveHint: false)
   - Destructive tools (destructiveHint: true)
   - Widget tools (return UI with _meta)
   - External API tools (openWorldHint: true)

2. **Widget Design**
   For each widget:
   - `id` - unique identifier (kebab-case)
   - `name` - display name
   - `description` - what it shows
   - `mockData` - sample data for preview

3. **Data Model**
   Design entities and relationships.

4. **Auth Requirements**
   - Single-user (no auth needed)
   - Multi-user (Auth0 or Supabase Auth)

#### Phase 3: Implementation

Generate complete application with this structure:

```
{app-name}/
├── package.json
├── tsconfig.server.json
├── setup.sh
├── START.sh
├── .env.example
├── .gitignore
└── server/
    └── index.ts
```

**Critical Requirements:**
- `Server` class from `@modelcontextprotocol/sdk/server/index.js`
- `StreamableHTTPServerTransport` for session management
- Widget URIs: `ui://widget/{widget-id}.html`
- Widget MIME type: `text/html+skybridge`
- `structuredContent` in tool responses
- `_meta` with `openai/outputTemplate` on tools

#### Phase 4: Testing
- Run setup: `./setup.sh`
- Start dev: `./START.sh --dev`
- Preview widgets: `http://localhost:3000/preview`
- Test MCP connection

#### Phase 5: Deployment
- Generate Dockerfile and render.yaml
- Deploy to Render
- Configure ChatGPT connector

---

## 2. Add MCP Tool

**Purpose:** Add a new MCP tool to your ChatGPT App.

### Workflow

1. **Gather Information**
   - What does this tool do?
   - What inputs does it need?
   - What does it return?

2. **Classify Tool Type**
   - **Query** (readOnlyHint: true) - Fetches data
   - **Mutation** (destructiveHint: false) - Creates/updates data
   - **Destructive** (destructiveHint: true) - Deletes data
   - **Widget** - Returns UI content
   - **External** (openWorldHint: true) - Calls external APIs

3. **Design Input Schema**
   Create Zod schema with appropriate types and descriptions.

4. **Generate Tool Handler**
   Use `chatgpt-mcp-generator` agent to create:
   - Tool handler in `server/tools/`
   - Zod schema export
   - Type exports
   - Database queries (if needed)

5. **Register Tool**
   Update `server/index.ts` with metadata:
   ```typescript
   {
     name: "my-tool",
     _meta: {
       "openai/toolInvocation/invoking": "Loading...",
       "openai/toolInvocation/invoked": "Done",
       "openai/outputTemplate": "ui://widget/my-widget.html", // if widget
     }
   }
   ```

6. **Update State**
   Add tool to `.chatgpt-app/state.json`.

### Tool Naming
Use kebab-case: `list-items`, `create-task`, `show-recipe-detail`

### Annotations Guide

| Scenario | readOnlyHint | destructiveHint | openWorldHint |
|----------|--------------|-----------------|---------------|
| List/Get | true | false | false |
| Create/Update | false | false | false |
| Delete | false | true | false |
| External API | varies | varies | true |

---

## 3. Add Widget

**Purpose:** Add inline HTML widgets with HTML/CSS/JS and Apps SDK integration.

### 5 Widget Patterns

1. **Card Grid** - Multiple items in grid
2. **Stats Dashboard** - Key metrics display
3. **Table** - Tabular data
4. **Bar Chart** - Simple visualizations
5. **Detail Widget** - Single item details

### Workflow

1. **Gather Information**
   - Widget purpose and data
   - Visual design (cards, table, chart, etc.)
   - Interactivity needs

2. **Define Data Shape**
   Document expected structure with TypeScript interface.

3. **Add Widget Config**
   ```typescript
   const widgets: WidgetConfig[] = [
     {
       id: "my-widget",
       name: "My Widget",
       description: "Displays data",
       templateUri: "ui://widget/my-widget.html",
       invoking: "Loading...",
       invoked: "Ready",
       mockData: { /* sample */ },
     },
   ];
   ```

4. **Add Widget HTML**
   Generate HTML with:
   - Preview mode support (`window.PREVIEW_DATA`)
   - OpenAI Apps SDK integration (`window.openai.toolOutput`)
   - Event listeners (`openai:set_globals`)
   - Polling fallback (100ms, 10s timeout)

5. **Create/Update Tool**
   Link tool to widget via `widgetId`.

6. **Test Widget**
   Preview at `/preview/{widget-id}` with mock data.

### Widget HTML Structure

```javascript
(function() {
  let rendered = false;

  function render(data) {
    if (rendered || !data) return;
    rendered = true;
    // Render logic
  }

  function tryRender() {
    if (window.PREVIEW_DATA) { render(window.PREVIEW_DATA); return; }
    if (window.openai?.toolOutput) { render(window.openai.toolOutput); }
  }

  window.addEventListener('openai:set_globals', tryRender);

  const poll = setInterval(() => {
    if (window.openai?.toolOutput || window.PREVIEW_DATA) {
      tryRender();
      clearInterval(poll);
    }
  }, 100);
  setTimeout(() => clearInterval(poll), 10000);

  tryRender();
})();
```

---

## 4. Add Authentication

**Purpose:** Configure authentication using Auth0 or Supabase Auth.

### When to Add
- Multiple users
- Persistent private data per user
- User-specific API credentials

### Providers

**Auth0:**
- Enterprise-grade
- OAuth 2.1, PKCE flow
- Social logins (Google, GitHub, etc.)

**Supabase Auth:**
- Simpler setup
- Email/password default
- Integrates with Supabase database

### Workflow

1. **Choose Provider**
   Ask user preference based on needs.

2. **Guide Setup**
   - **Auth0:** Create application, configure callback URLs, get credentials
   - **Supabase:** Already configured with database setup

3. **Generate Auth Code**
   Use `chatgpt-auth-generator` agent to create:
   - Session management middleware
   - User subject extraction
   - Token validation

4. **Update Server**
   Add auth middleware to protect routes.

5. **Update Environment**
   ```bash
   # Auth0
   AUTH0_DOMAIN=your-tenant.auth0.com
   AUTH0_CLIENT_ID=...
   AUTH0_CLIENT_SECRET=...
   
   # Supabase (from database setup)
   SUPABASE_URL=...
   SUPABASE_ANON_KEY=...
   ```

6. **Test**
   Verify login flow and user isolation.

---

## 5. Add Database

**Purpose:** Configure PostgreSQL database using Supabase.

### When to Add
- Persistent user data
- Multi-entity relationships
- Query/filter capabilities

### Workflow

1. **Check Supabase Setup**
   Verify account and project exist.

2. **Gather Credentials**
   - Project URL
   - Anon key (public)
   - Service role key (server-side)

3. **Define Entities**
   For each entity, specify:
   - Fields and types
   - Relationships
   - Indexes

4. **Generate Schema**
   Use `chatgpt-database-generator` agent to create SQL with:
   - `id` (UUID primary key)
   - `user_subject` (varchar, indexed)
   - `created_at` (timestamptz)
   - `updated_at` (timestamptz)
   - RLS policies for user isolation

5. **Setup Connection Pool**
   ```typescript
   import { createClient } from '@supabase/supabase-js';
   
   const supabase = createClient(
     process.env.SUPABASE_URL!,
     process.env.SUPABASE_SERVICE_ROLE_KEY!
   );
   ```

6. **Apply Migrations**
   Run SQL in Supabase dashboard or via migration tool.

### Query Pattern

Always filter by `user_subject`:

```typescript
const { data } = await supabase
  .from('tasks')
  .select('*')
  .eq('user_subject', userSubject);
```

---

## 6. Generate Golden Prompts

**Purpose:** Generate test prompts to validate ChatGPT correctly invokes tools.

### Why Important
- Measure precision/recall
- Enable iteration
- Post-launch monitoring

### 3 Categories

1. **Direct Prompts** - Explicit tool invocation
   - "Show me my task list"
   - "Create a new task called..."

2. **Indirect Prompts** - Outcome-based, ChatGPT should infer tool
   - "What do I need to do today?"
   - "Help me organize my work"

3. **Negative Prompts** - Should NOT trigger tool
   - "What is a task?"
   - "Tell me about project management"

### Workflow

1. **Analyze Tools**
   Review each tool's purpose and inputs.

2. **Generate Prompts**
   For each tool, create:
   - 5+ direct prompts
   - 5+ indirect prompts
   - 3+ negative prompts
   - 2+ edge case prompts

3. **Best Practices**
   - Tool descriptions start with "Use this when..."
   - State limitations clearly
   - Include examples in descriptions

4. **Save Output**
   Write to `.chatgpt-app/golden-prompts.json`:
   ```json
   {
     "toolName": {
       "direct": ["prompt1", "prompt2"],
       "indirect": ["prompt1", "prompt2"],
       "negative": ["prompt1", "prompt2"],
       "edge": ["prompt1", "prompt2"]
     }
   }
   ```

---

## 7. Validate App

**Purpose:** Validation suite before deployment.

### 10 Validation Checks

1. **Required Files**
   - package.json
   - tsconfig.server.json
   - setup.sh (executable)
   - START.sh (executable)
   - server/index.ts
   - .env.example

2. **Server Implementation**
   - Uses `Server` from MCP SDK
   - Has `StreamableHTTPServerTransport`
   - Session management with Map
   - Correct request handlers

3. **Widget Configuration**
   - `widgets` array exists
   - Each has id, name, description, templateUri, mockData
   - URIs match pattern `ui://widget/{id}.html`

4. **Tool Response Format**
   - Returns `structuredContent` (not just `content`)
   - Widget tools have `_meta` with `openai/outputTemplate`

5. **Resource Handler Format**
   - MIME type: `text/html+skybridge`
   - Returns `_meta` with serialization and CSP

6. **Widget HTML Structure**
   - Preview mode support
   - Event listeners for Apps SDK
   - Polling fallback
   - Render guard

7. **Endpoint Existence**
   - `/health` - Health check
   - `/preview` - Widget index
   - `/preview/:widgetId` - Widget preview
   - `/mcp` - MCP endpoint

8. **Package.json Scripts**
   - Has `build:server`
   - Has `start` with HTTP_MODE=true
   - Has `dev` with watch mode
   - NO web build scripts (web/, ui/, client/)

9. **Annotation Validation**
   - readOnlyHint set correctly
   - destructiveHint for delete operations
   - openWorldHint for external APIs

10. **Database Validation** (if enabled)
    - Tables have required fields
    - user_subject indexed
    - RLS policies enabled

### Common Errors

| Error | Fix |
|-------|-----|
| Missing structuredContent | Add to tool response |
| Wrong widget URI | Use ui://widget/{id}.html |
| No session management | Add Map<string, Transport> |
| Missing _meta | Add to tool definition and response |
| Wrong MIME type | Use text/html+skybridge |

**Critical:** Check file existence FIRST before other validations!

---

## 8. Test App

**Purpose:** Run automated tests using MCP Inspector and golden prompts.

### 4 Test Categories

1. **MCP Protocol**
   - Server starts without errors
   - Handles initialize
   - Lists tools correctly
   - Lists resources correctly

2. **Schema Validation**
   - Tool schemas are valid Zod
   - Required fields marked
   - Types match implementation

3. **Widget Tests**
   - All widgets render in preview mode
   - Mock data loads correctly
   - No console errors

4. **Golden Prompt Tests**
   - Direct prompts trigger correct tools
   - Indirect prompts work as expected
   - Negative prompts don't trigger tools

### Workflow

1. **Start Server in Test Mode**
   ```bash
   HTTP_MODE=true NODE_ENV=test npm run dev
   ```

2. **Run MCP Inspector**
   Test protocol compliance:
   - Initialize connection
   - List tools
   - Call each tool with valid inputs
   - Check responses

3. **Schema Validation**
   Verify schemas compile and match implementation.

4. **Golden Prompt Tests**
   Use ChatGPT to test prompts:
   - Record which tool was called
   - Compare to expected tool
   - Calculate precision/recall

5. **Generate Report**
   ```json
   {
     "passed": 42,
     "failed": 3,
     "categories": {
       "mcp": "✅",
       "schema": "✅",
       "widgets": "✅",
       "prompts": "⚠️ 3 failures"
     },
     "timing": "2.3s"
   }
   ```

### Fixing Failures

For each failure, explain:
- What failed
- Why it failed
- How to fix (with code example)

---

## 9. Deploy App

**Purpose:** Deploy ChatGPT App to Render with PostgreSQL and health checks.

### Prerequisites

- ✅ Validation passed
- ✅ Tests passed
- ✅ Git repository clean
- ✅ Environment variables ready

### Workflow

1. **Pre-flight Check**
   - Run validation
   - Run tests
   - Check database connection (if enabled)

2. **Generate render.yaml**
   ```yaml
   services:
     - type: web
       name: {app-name}
       runtime: docker
       plan: free
       healthCheckPath: /health
       envVars:
         - key: PORT
           value: 3000
         - key: HTTP_MODE
           value: true
         - key: NODE_ENV
           value: production
         - key: WIDGET_DOMAIN
           generateValue: true
         # Add auth/database vars if needed
   ```

3. **Generate Dockerfile**
   ```dockerfile
   FROM node:20-slim
   WORKDIR /app
   COPY package*.json ./
   RUN npm ci --only=production
   COPY dist ./dist
   EXPOSE 3000
   CMD ["node", "dist/server/index.js"]
   ```

4. **Deploy**
   **Option A: Automated (if Render MCP available)**
   Use Render MCP agent to deploy.
   
   **Option B: Manual**
   - Push to GitHub
   - Connect repo in Render dashboard
   - Set environment variables
   - Deploy

5. **Verify Deployment**
   - Health check: `https://{app}.onrender.com/health`
   - MCP endpoint: `https://{app}.onrender.com/mcp`
   - Tool discovery works
   - Widgets render

6. **Configure ChatGPT Connector**
   - URL: `https://{app}.onrender.com/mcp`
   - Test in ChatGPT

---

## 10. Resume App

**Purpose:** Resume building an in-progress ChatGPT App.

### Workflow

1. **Load State**
   Read `.chatgpt-app/state.json`:
   ```json
   {
     "appName": "My Task Manager",
     "phase": "Implementation",
     "tools": ["list-tasks", "create-task"],
     "widgets": ["task-list"],
     "auth": false,
     "database": true,
     "validated": false,
     "deployed": false
   }
   ```

2. **Display Progress**
   Show current status:
   - App name
   - Current phase
   - Completed items (tools, widgets)
   - Pending items (auth, validation, deployment)

3. **Offer Next Steps**
   Based on phase:
   
   **Concept Phase:**
   - "Let's design the tools and widgets"
   - "Shall we start implementation?"
   
   **Implementation Phase:**
   - "Add another tool?"
   - "Add a widget?"
   - "Set up authentication?"
   - "Set up database?"
   
   **Testing Phase:**
   - "Generate golden prompts?"
   - "Run validation?"
   - "Run tests?"
   
   **Deployment Phase:**
   - "Deploy to Render?"
   - "Configure ChatGPT connector?"

4. **Continue Work**
   Based on user's choice, invoke the appropriate workflow section.

---

## Best Practices

1. **Always save state** after each major step
2. **Validate before moving forward** (especially before deployment)
3. **Use agents for code generation** (chatgpt-mcp-generator, chatgpt-auth-generator, etc.)
4. **Test at every phase** (preview widgets, test tools, run golden prompts)
5. **Keep it conversational** - guide the user naturally through the workflow
6. **Explain trade-offs** when offering choices (Auth0 vs Supabase, etc.)
7. **Show examples** when introducing new concepts

---

## State Management

The `.chatgpt-app/state.json` file tracks progress:

```json
{
  "appName": "string",
  "description": "string",
  "phase": "Concept" | "Implementation" | "Testing" | "Deployment",
  "tools": ["tool-name"],
  "widgets": ["widget-id"],
  "auth": {
    "enabled": boolean,
    "provider": "auth0" | "supabase" | null
  },
  "database": {
    "enabled": boolean,
    "entities": ["entity-name"]
  },
  "validated": boolean,
  "tested": boolean,
  "deployed": boolean,
  "deploymentUrl": "string | null",
  "goldenPromptsGenerated": boolean,
  "lastUpdated": "ISO timestamp"
}
```

---

## Command Reference

```bash
# Setup
./setup.sh

# Development
./START.sh --dev          # Dev mode with watch
./START.sh --preview      # Open preview in browser
./START.sh --stdio        # STDIO mode (testing)
./START.sh                # Production mode

# Testing
npm run validate          # Type checking
curl http://localhost:3000/health

# Deployment
git push origin main      # Trigger Render deploy
```

---

## Getting Started

When the user invokes any chatgpt-app command:

1. Check if `.chatgpt-app/state.json` exists
2. If yes → use **Resume App** workflow
3. If no → use **Create New App** workflow

Always guide users through the natural progression:
**Concept → Implementation → Testing → Deployment**