hermesonehq/hermes-registry/chatgpt-apps

ChatGPT Apps

Overview

Scaffold ChatGPT Apps SDK implementations with a docs-first, example-first workflow, then generate code that follows current Apps SDK and MCP Apps bridge patterns.

Use this skill to produce:

• A primary app-archetype classification and repo-shape decision
• A tool plan (names, schemas, annotations, outputs)
• An upstream starting-point recommendation (official example, ext-apps example, or local fallback scaffold)
• An MCP server scaffold (resource registration, tool handlers, metadata)
• A widget scaffold (MCP Apps bridge first, window.openai compatibility/extensions second)
• A reusable Node + @modelcontextprotocol/ext-apps starter scaffold for low-dependency fallbacks
• A validation report against the minimum working repo contract
• Local dev and connector setup steps
• A short stakeholder summary of what the app does (when requested)

Mandatory Docs-First Workflow

Use $openai-docs first whenever building or changing a ChatGPT Apps SDK app.

1. Invoke $openai-docs (preferred) or call the OpenAI docs MCP server directly.
2. Fetch current Apps SDK docs before writing code, especially (baseline pages):

• apps-sdk/build/mcp-server
• apps-sdk/build/chatgpt-ui
• apps-sdk/build/examples
• apps-sdk/plan/tools
• apps-sdk/reference

1. Fetch apps-sdk/quickstart when scaffolding a new app or generating a first-pass implementation, and check the official examples repo/page before inventing a scaffold from scratch.
2. Fetch deployment/submission docs when the task includes local ChatGPT testing, hosting, or public launch:

• apps-sdk/deploy
• apps-sdk/deploy/submission
• apps-sdk/app-submission-guidelines

1. Cite the docs URLs you used when explaining design choices or generated scaffolds.
2. Prefer current docs guidance over older repo patterns when they differ, and call out compatibility aliases explicitly.
3. If doc search times out or returns poor matches, fetch the canonical Apps SDK pages directly by URL and continue; do not let search failure block scaffolding.

If $openai-docs is unavailable, use:

• mcp__openaiDeveloperDocs__search_openai_docs
• mcp__openaiDeveloperDocs__fetch_openai_doc

Read references/apps-sdk-docs-workflow.md for suggested doc queries and a compact checklist. Read references/app-archetypes.md to classify the request into a small number of supported app shapes before choosing examples or scaffolds. Read references/repo-contract-and-validation.md when generating or reviewing a repo so the output stays inside a stable “working app” contract. Read references/search-fetch-standard.md when the app is connector-like, data-only, sync-oriented, or meant to work well with company knowledge or deep research. Read references/upstream-example-workflow.md when starting a greenfield app or when deciding whether to adapt an upstream example or use the local fallback scaffold. Read references/window-openai-patterns.md when the task needs ChatGPT-specific widget behavior or when translating repo examples that use wrapper-specific app.* helpers.

Prompt Guidance

Use prompts that explicitly pair this skill with $openai-docs so the resulting scaffold is grounded in current docs.

Preferred prompt patterns:

• Use $chatgpt-apps with $openai-docs to scaffold a ChatGPT app for <use case> with a <TS/Python> MCP server and <React/vanilla> widget.
• Use $chatgpt-apps with $openai-docs to adapt the closest official Apps SDK example into a ChatGPT app for <use case>.
• Use $chatgpt-apps and $openai-docs to refactor this Apps SDK demo into a production-ready structure with tool annotations, CSP, and URI versioning.
• Use $chatgpt-apps with $openai-docs to plan tools first, then generate the MCP server and widget code.

When responding, ask for or infer these inputs before coding:

• Use case and primary user flows
• Read-only vs mutating tools
• Demo vs production target
• Private/internal use vs public directory submission
• Backend language and UI stack
• Auth requirements
• External API domains for CSP allowlists
• Hosting target and local dev approach
• Org ownership/verification readiness (for submission tasks)

Classify The App Before Choosing Code

Before choosing examples, repo shape, or scaffolds, classify the request into one primary archetype and state it.

• tool-only
• vanilla-widget
• react-widget
• interactive-decoupled
• submission-ready

Infer the archetype unless a missing detail is truly blocking. Use the archetype to choose:

• whether a UI is needed at all
• whether to preserve a split server/ + web/ layout
• whether to prefer official OpenAI examples, ext-apps examples, or the local fallback scaffold
• which validation checks matter most
• whether search and fetch should be the default read-only tool surface

Read references/app-archetypes.md for the decision rubric.

Default Starting-Point Order

For greenfield apps, prefer these starting points in order:

1. Official OpenAI examples when a close example already matches the requested stack or interaction pattern.
2. Version-matched `@modelcontextprotocol/ext-apps` examples when the user needs a lower-level or more portable MCP Apps baseline.
3. `scripts/scaffold_node_ext_apps.mjs` only when no close example fits, the user wants a tiny Node + vanilla starter, or network access/example retrieval is undesirable.

Do not generate a large custom scaffold from scratch if a close upstream example already exists. Copy the smallest matching example, remove unrelated demo code, then patch it to the current docs and the user request.

Build Workflow

0. Classify The App Archetype

Pick one primary archetype before planning tools or choosing a starting point.

• Prefer a single primary archetype instead of mixing several.
• If the request is broad, infer the smallest archetype that can still satisfy it.
• Escalate to submission-ready only when the user asks for public launch, directory submission, or review-ready deployment.
• Call out the chosen archetype in your response so the user can correct it early if needed.

1. Plan Tools Before Code

Define the tool surface area from user intents.

• Use one job per tool.
• Write tool descriptions that start with "Use this when..." behavior cues.
• Make inputs explicit and machine-friendly (enums, required fields, bounds).
• Decide whether each tool is data-only, render-only, or both.
• Set annotations accurately (readOnlyHint, destructiveHint, openWorldHint; add idempotentHint when true).
• If the app is connector-like, data-only, sync-oriented, or intended for company knowledge or deep research, default to the standard search and fetch tools instead of inventing custom read-only equivalents.
• For educational/demo apps, prefer one concept per tool so the model can pick the right example cleanly.
• Group demo tools by learning objective: data into the widget, widget actions back into the conversation or tools, host/layout environment signals, and lifecycle/streaming behavior.

Read references/search-fetch-standard.md when search and fetch may be relevant.

2. Choose an App Architecture

Choose the simplest structure that fits the goal.

• Use a minimal demo pattern for quick prototypes, workshops, or proofs of concept.
• Use a decoupled data/render pattern for production UX so the widget does not re-render on every tool call.

Prefer the decoupled pattern for non-trivial apps:

• Data tools return reusable structuredContent.
• Render tools attach _meta.ui.resourceUri and optional _meta["openai/outputTemplate"].
• Render tool descriptions state prerequisites (for example, "Call search first").

2a. Start From An Upstream Example When One Fits

Default to upstream examples for greenfield work when they are close to the requested app.

• Check the official OpenAI examples first for ChatGPT-facing apps, polished UI patterns, React components, file upload flows, modal flows, or apps that resemble the docs examples.
• Use @modelcontextprotocol/ext-apps examples when the request is closer to raw MCP Apps bridge/server wiring, or when version-matched package patterns matter more than ChatGPT-specific polish.
• Pick the smallest matching example and copy only the relevant files; do not transplant an entire showcase app unchanged.
• After copying, reconcile the example with the current docs you fetched: tool names/descriptions, annotations, _meta.ui.*, CSP, URI versioning, and local run instructions.
• State which example you chose and why in one sentence.

Read references/upstream-example-workflow.md for the selection and adaptation rubric.

2b. Use the Starter Script When a Low-Dependency Fallback Helps

Use scripts/scaffold_node_ext_apps.mjs only when the user wants a quick, greenfield Node starter and a vanilla HTML widget is acceptable, and no upstream example is a better starting point.

• Run it only after fetching current docs, then reconcile the generated files with the docs you fetched.
• If you choose the script instead of an upstream example, say why the fallback is better for that request.
• Skip it when a close official example exists, when the user already has an existing app structure, when they need a non-Node stack, when they explicitly want React first, or when they only want a plan/review instead of code.
• The script generates a minimal @modelcontextprotocol/ext-apps server plus a vanilla HTML widget that uses the MCP Apps bridge by default.
• The generated widget keeps follow-up messaging on the standard ui/message bridge and only uses window.openai for optional host signals/extensions.
• After running it, patch the generated output to match the current docs and the user request: adjust tool names/descriptions, annotations, resource metadata, URI versioning, and README/run instructions.

3. Scaffold the MCP Server

Generate a server that:

• Registers a widget resource/template with the MCP Apps UI MIME type (text/html;profile=mcp-app) or the SDK constant (RESOURCE_MIME_TYPE) when using @modelcontextprotocol/ext-apps/server
• Registers tools with clear names, schemas, titles, and descriptions
• Returns structuredContent (model + widget), content (model narration), and _meta (widget-only data) intentionally
• Keeps handlers idempotent or documents non-idempotent behavior explicitly
• Includes tool status strings (openai/toolInvocation/*) when helpful in ChatGPT

Keep structuredContent concise. Move large or sensitive widget-only payloads to _meta.

4. Scaffold the Widget UI

Use the MCP Apps bridge first for portability, then add ChatGPT-specific window.openai APIs when they materially improve UX.

• Listen for ui/notifications/tool-result (JSON-RPC over postMessage)
• Render from structuredContent
• Use tools/call for component-initiated tool calls
• Use ui/update-model-context only when UI state should change what the model sees

Use window.openai for compatibility and extensions (file upload, modal, display mode, etc.), not as the only integration path for new apps.

API Surface Guardrails