chatgpt-app-builder

What this skill does

# ChatGPT App Builder

Build production-ready ChatGPT Apps from concept to App Store submission.

## Quick Start

```
New app?           → Start at Phase 1 (Fit Evaluation)
Have app-spec.md?  → Start at Phase 3 (Implementation)
App built?         → Start at Phase 4 (Testing)
Ready to ship?     → Start at Phase 5 (Deployment)
```

---

## Phase 1: Fit Evaluation

**Goal**: Determine if a ChatGPT App is right for this product.

### Step 1: Gather Context
Ask the user:
1. What does your product do?
2. Who are your users?
3. What API/data does it expose?
4. What actions can users take?

### Step 2: Apply Know/Do/Show Framework
Evaluate against three value pillars (see [fit_evaluation.md](references/fit_evaluation.md)):

| Pillar | Question | Strong Signal |
|--------|----------|---------------|
| **Know** | Does it provide data ChatGPT lacks? | Live prices, user-specific data, internal metrics |
| **Do** | Can it take real actions? | Create, update, delete, send, schedule |
| **Show** | Can it display better than text? | Lists, charts, maps, media galleries |

**Minimum requirement**: At least one pillar must be strong.

### Step 3: Check Blockers
Review [fit_evaluation.md](references/fit_evaluation.md) for:
- Prohibited categories (gambling, adult, crypto speculation)
- Data restrictions (no PCI, PHI, SSN, API keys)
- Age requirements (13+ audience)

### Step 4: Create Golden Prompt Set
Draft prompts for discovery testing:
- **5 direct prompts**: Explicitly name your product ("Show my TaskFlow tasks")
- **5 indirect prompts**: Describe intent without naming ("What should I work on?")
- **3 negative prompts**: Similar but shouldn't trigger ("Create a reminder")

### Step 5: Write app-spec.md
Create the specification file:

```markdown
# [Product Name] ChatGPT App Spec

## Product Context
- Name: [Product name]
- API Base: [API URL]
- Auth: [Bearer token / OAuth / None]

## Value Proposition
- Know: [What data does it provide?]
- Do: [What actions can it take?]
- Show: [What UI is needed?]

## Golden Prompts
### Direct (should trigger)
1. ...

### Indirect (should trigger)
1. ...

### Negative (should NOT trigger)
1. ...
```

**Output**: `app-spec.md` in project directory

---

## Phase 2: App Design

**Goal**: Define complete technical specification.

### Step 1: Define Tools (2-5)
Follow one-job-per-tool principle. See [chatgpt_app_best_practices.md](references/chatgpt_app_best_practices.md).

For each tool, specify:
```yaml
name: service_verb_noun  # e.g., taskflow_get_tasks
title: Human Readable Name
description: Use this when the user wants to... [be specific]
annotations:
  readOnlyHint: true/false
  destructiveHint: true/false
  openWorldHint: true/false
inputSchema:
  param1: type (required/optional)
  param2: enum["a", "b", "c"]
outputStructure:
  content: [text summary for model]
  structuredContent: {machine-readable data}
  _meta: {widget-only data}
```

### Step 2: Decide Widget Needs
Does the app need custom UI?

| Use Case | Widget Needed? | Component Type |
|----------|----------------|----------------|
| Task list with checkboxes | Yes | List with actions |
| Data display only | Maybe | Could use text |
| Maps, charts, media | Yes | Specialized |
| Multi-step workflow | Yes | Stateful widget |

See [widget_development.md](references/widget_development.md) for patterns.

### Step 3: Plan Authentication
If accessing user-specific data or write operations, auth is required.

See [oauth_integration.md](references/oauth_integration.md) for:
- Well-known endpoint setup
- Provider-specific guides (Auth0, Stytch)
- Tool-level securitySchemes

### Step 4: Update app-spec.md
Add technical specification:

```markdown
## Tools

### 1. service_get_items
- **Annotations**: readOnlyHint: true
- **Input**: { status?: "active" | "completed", limit?: number }
- **Output**:
  - content: "Found N items"
  - structuredContent: { items: [...] }
  - _meta: { fullData: [...] }

### 2. service_create_item
- **Annotations**: openWorldHint: true
- **Input**: { title: string, description?: string }
- **Output**: { id, title, created_at }

## Widget
- Type: List with action buttons
- Display modes: inline, fullscreen
- State: { selectedId, filter }

## Authentication
- Required: Yes
- Provider: Auth0
- Scopes: read:items, write:items
```

**Output**: Updated `app-spec.md` with full technical spec

---

## Phase 3: Implementation

**Goal**: Generate complete working project.

### Step 1: Initialize Project
Copy from assets and customize:

```bash
# Project structure
myapp-chatgpt/
├── package.json
├── tsconfig.json
├── src/
│   ├── index.ts          # MCP server entry
│   ├── tools/            # Tool handlers
│   ├── widget/           # Widget source
│   └── types/            # TypeScript types
└── scripts/
    └── build-widget.ts   # Widget bundler
```

See [node_chatgpt_app.md](references/node_chatgpt_app.md) for complete patterns.

### Step 2: Implement MCP Server
Key components (from assets/server/):

1. **HTTP server with SSE transport** (required for ChatGPT Apps):
```typescript
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";

// GET /mcp - SSE stream connection
// POST /mcp/messages - Message handling
```

2. **Tool definitions with JSON Schema**:
```typescript
const tools: Tool[] = [{
  name: "service_get_items",
  title: "Get Items",
  description: "Use this when the user wants to see items...",
  inputSchema: { type: "object", properties: {...} },
  _meta: {
    "openai/outputTemplate": "ui://widget/app.html",
    "openai/widgetAccessible": true
  },
  annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false }
}];
```

3. **Handler registration**:
```typescript
server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;
  // Handle tool calls...
  return {
    content: [{ type: "text", text: `Found ${items.length} items` }],
    structuredContent: { items: items.slice(0, 10) },
    _meta: { fullItems: items }
  };
});
```

### Step 3: Implement Widget
Key patterns (from assets/widget/):

```typescript
// Access data
const output = window.openai.toolOutput;
const meta = window.openai.toolResponseMetadata;

// Invoke tools
await window.openai.callTool("service_action", { id: "123" });

// Persist state
window.openai.setWidgetState({ selectedId: "123" });

// Layout control
window.openai.notifyIntrinsicHeight(400);
await window.openai.requestDisplayMode({ mode: "fullscreen" });
```

See [widget_development.md](references/widget_development.md) for React hooks and patterns.

### Step 4: Build
```bash
npm install
npm run build  # Compiles server + bundles widget
```

### Step 5: Implementation Checklist

Before moving to testing, verify:

#### Widget Requirements
- [ ] Uses Apps SDK UI design tokens (see [apps_sdk_ui_tokens.md](references/apps_sdk_ui_tokens.md))
- [ ] Implements dark mode with CSS variable architecture
- [ ] Uses LoadingDots pattern for loading states (see [widget_ui_patterns.md](references/widget_ui_patterns.md))
- [ ] Calls `notifyIntrinsicHeight()` after all DOM changes
- [ ] Includes copy button feedback for copyable content
- [ ] Has show more/less for long lists (>3 items)
- [ ] Works on mobile (test at 375px width)
- [ ] Loading UI guards against re-initialization (see [widget_loading_patterns.md](references/widget_loading_patterns.md))
- [ ] SVG animations use `.style` property, not `setAttribute()` (see [widget_development.md](references/widget_development.md#common-widget-gotchas))

#### Security Requirements
- [ ] All user input is validated (see [security_patterns.md](references/security_patterns.md))
- [ ] HTML output uses safe DOM methods (textContent, createElement)
- [ ] External image URLs are proxied with domain whitelist and size limits (200KB)
- [ ] Rate limiting is imple