Menu
WHEN building ChatGPT apps using the OpenAI Apps SDK and MCP; create conversational, composable experiences with proper UX, UI, state management, and server patterns.
WHEN scraping iOS/macOS App Store data (apps, reviews, ratings, search); NOT for installing or testing apps; retrieves structured JSON data using iTunes/App Store APIs with curl and jq formatting
Comprehensive guide for implementing on-device AI models on iOS using Foundation Models and MLX Swift frameworks. Use WHEN building iOS apps with (1) Local LLM inference, (2) Vision Language Models (VLMs), (3) Text embeddings, (4) Image generation, (5) Tool/function calling, (6) Multi-turn conversations, (7) Custom model integration, or (8) Structured generation.
WHEN building SwiftUI views, managing state, setting up shared services, or making architectural decisions; NOT for UIKit or legacy patterns; provides pure SwiftUI data flow without ViewModels using @State, @Binding, @Observable, and @Environment.
WHEN building design systems or component libraries with Tailwind CSS; covers design tokens, CVA patterns and dark mode.
WHEN building React components/pages/apps; enforces scalable architecture, state management, API layer, performance patterns.
Evidence-based goal achievement framework using Goal, Plan, and System methodology. Use when users want to set goals, create actionable plans, build execution systems, or diagnose why they're struggling to make progress on existing goals. Triggers include requests to "set a goal", "help me achieve", "create a plan", "why am I not making progress", or similar goal-setting and achievement queries.
| name | chatgpt-app-sdk |
| description | WHEN building ChatGPT apps using the OpenAI Apps SDK and MCP; create conversational, composable experiences with proper UX, UI, state management, and server patterns. |
Build ChatGPT apps using the OpenAI Apps SDK, Model Context Protocol (MCP), and component-based UI patterns.
| Topic | Guide |
|---|---|
| Display modes, visual design, accessibility | ui-guidelines.md |
| MCP architecture, tools, and server patterns | mcp-server.md |
| React patterns and window.openai API | ui-components.md |
| React hooks (useOpenAiGlobal, useWidgetState) | react-integration.md |
| Three-tier state architecture and best practice | state-management.md |
| Issue | Prevention |
|---|---|
| CORS blocking | Enable https://chatgpt.com origin on endpoints |
| Widget 404s | Use ui://widget/ prefix format for widget resources |
| Plain text display | Set MIME type to text/html+skybridge for widgets |
| Tool not suggested | Use action-oriented descriptions in tool definitions |
| Missing widget data | Pass initial data via _meta.initialData field |
| CSP script blocking | Reference external scripts from allowed CDN origins |
Is this a multi-step workflow or deep exploration?
├── Yes → Fullscreen
└── No → Is this a parallel activity (game, live session)?
├── Yes → Picture-in-Picture (PiP)
└── No → Inline
├── Single item with quick action → Inline Card
└── 3-8 similar items → Inline Carousel
Is this data from your API/database?
├── Yes → MCP Server (Business Data)
│ Return in structuredContent from tool calls
└── No → Is it user preference/cross-session data?
├── Yes → Backend Storage (via OAuth)
└── No → Widget State (UI-scoped)
Use window.openai.widgetState / useWidgetState
Is this action:
- Atomic and standalone?
- Invokable by the model via natural language?
- Returning structured data?
├── Yes → Create public tool (model-accessible)
└── No → Is it only for widget interactions?
├── Yes → Use private tool ("openai/visibility": "private")
└── No → Handle within existing tool logic
Does the model need this data to:
- Understand results?
- Generate follow-ups?
- Reason about next steps?
├── Yes → structuredContent (concise, model-readable)
└── No → _meta (large datasets, widget-only data)
Does this require:
- User input beyond text?
- Structured data visualization?
- Interactive selection/filtering?
├── Yes → Custom UI component
└── No → Return plain text/markdown in content