Preface¶

Applications in ChatGPT are no longer just “slipping a block of text into a conversation”. With the Apps SDK, you can provide both MCP (Model Context Protocol) tools and an embedded Widget at the same time: the model is responsible for calling tools and narrating results, while the Widget renders an interactive interface in the conversation via an iframe. For developers, the real challenge is rarely writing a few lines of HTML, but aligning with the entire workflow of resource registration, tool metadata, MCP Apps bridge, CSP, and local tunnel debugging covered in the current documentation.

OpenAI provides the curated Skill chatgpt-apps in the official Skills repository, which specifically teaches Agents how to scaffold, modify, and troubleshoot such applications in a documentation-first manner. This article is based on the Skill’s SKILL.md and OpenAI developer documentation to explain what it is, what it can do, and how to install and enable it.

What It Is¶

chatgpt-apps is an Agent Skill maintained by OpenAI (located at skills/.curated/chatgpt-apps in the openai/skills repository). It is tailored for “ChatGPT Apps SDK applications”: it bundles an MCP Server and a Widget UI for designing tools, registering UI resources, connecting to the MCP Apps bridge or ChatGPT-compatible APIs, completing Apps SDK metadata, CSP, and domain configuration, and generating a project skeleton consistent with the official documentation.

The positioning of this Skill can be summarized in one sentence: Before writing code, pull the latest Apps SDK documentation, then classify the application form via a fixed workflow, select upstream examples, set up the server and Widget, and finally perform validation based on the “minimum runnable repository contract”.

Its dependent documentation capabilities are also listed in agents/openai.yaml: it defaults to associating with the OpenAI Developer Docs MCP (https://developers.openai.com/mcp) and encourages use alongside $openai-docs.

Core Features and Highlights¶

According to the official SKILL.md, this Skill will guide the Agent to produce or complete the following tasks:

Application Prototype Classification: Define a primary form before writing code, such as tool-only, vanilla-widget, react-widget, interactive-decoupled, submission-ready, then select examples and focus on validation points accordingly.
Tool Planning First: Plan tool names, schemas, annotations (such as readOnlyHint, destructiveHint) and outputs; prioritize standard search + fetch for connector/read-only scenarios instead of inventing read-only tools arbitrarily.
Upstream Example Priority: The greenfield onboarding order is official OpenAI examples → version-matching @modelcontextprotocol/ext-apps examples → local fallback script scripts/scaffold_node_ext_apps.mjs. Reuse adjacent examples instead of building a full scaffold from scratch whenever possible.
MCP Server Scaffolding: Register Widget resources with the MIME type text/html;profile=mcp-app (or use the SDK constant RESOURCE_MIME_TYPE), register tools, and intentionally return structuredContent, content, and _meta.
Widget Scaffolding: Prioritize using the MCP Apps bridge (JSON-RPC over postMessage) by default, for example, listening to ui/notifications/tool-result and initiating calls with tools/call; window.openai is only used as a ChatGPT compatibility layer and extension capability (files, modals, display modes, etc.).
Security and Submission Metadata: Configure _meta.ui.csp, _meta.ui.domain, and other fields; go through deployment and submission documentation when publishing to the public directory.
Local Debugging Steps: Local /mcp endpoint, HTTPS tunnel, create a remote MCP application in ChatGPT Developer Mode, and refresh the application after modifying tools to reload the descriptor.

Compared to “just asking an Agent to write a random MCP demo”, its main value lies in standardizing the workflow: documentation-first, example-first, and contract validation, reducing back-and-forth with outdated repository patterns or incorrect API surfaces.

Installation and Enablement¶

This Skill follows the universal SKILL.md format and can be used in tools that support the Agent Skills standard. The installation directory varies by host platform, please refer to their official documentation for details.

Codex CLI / Codex in ChatGPT Desktop App¶

According to OpenAI documentation, you can use the built-in $skill-installer to install curated Skills. For example:

$skill-installer chatgpt-apps

After installation, the Skill will appear in $CODEX_HOME/skills/ (default: ~/.codex/skills). Codex will automatically detect changes; if the list does not update, restart Codex.

You can also explicitly invoke it in your prompts, for example, mentioning the Skill with $, or selecting it via /skills.

To temporarily disable it without deleting it, you can configure it in ~/.codex/config.toml:

[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false

Restart Codex after making changes.

Cursor¶

Cursor automatically loads Skills from the following directories (project-level or user-level):
- .agents/skills/, .cursor/skills/
- ~/.agents/skills/, ~/.cursor/skills/
- Compatible directories: .claude/skills/, .codex/skills/ and their corresponding user-level paths

For manual installation, place the official directory in, for example:

.cursor/skills/chatgpt-apps/SKILL.md

You can also copy the entire directory including references/, scripts/, and agents/ while preserving relative references. You can explicitly invoke it in Agent chats with /chatgpt-apps, or rely on the description field for implicit matching.

Cursor documentation also supports importing Skills from a GitHub repository via Remote Rule; the repository address can use:

https://github.com/openai/skills

The specific path is skills/.curated/chatgpt-apps.

Directly Fetch from GitHub¶

Without relying on the installer, you can view or clone the source files from the following address:

https://github.com/openai/skills/tree/main/skills/.curated/chatgpt-apps

The directory roughly contains:

chatgpt-apps/
├── SKILL.md
├── LICENSE.txt
├── agents/
│   └── openai.yaml
├── references/          # Prototype classification, documentation workflow, repository contracts, etc.
└── scripts/
    └── scaffold_node_ext_apps.mjs

Typical Usage Examples¶

The recommended prompt pattern given in the Skill documentation is to use $chatgpt-apps in pair with $openai-docs to avoid the scaffold falling behind the current documentation.

Scaffold a ChatGPT app with an MCP server and Widget:

Use $chatgpt-apps with $openai-docs to scaffold a ChatGPT app for <use-case> with a MCP server and widget.

Adapt the closest official example into a ChatGPT app for your use case:

Use $chatgpt-apps with $openai-docs to adapt the closest official Apps SDK example into a ChatGPT app for <use-case>.

Refactor a demo project into a production-ready structure:

Use $chatgpt-apps and $openai-docs to refactor this Apps SDK demo into a production-ready structure with tool annotations, CSP, and URI versioning.

Plan tools first, then generate code:

Use $chatgpt-apps with $openai-docs to plan tools first, then generate the MCP server and widget code.

Before coding, the Skill will ask the Agent to supplement or infer as much as possible: use cases and main workflows, read-only or data-modifying, demo or production, whether to submit to the public directory, backend language and UI stack, authentication, CSP external domains, hosting and local development methods, etc.

When debugging locally with ChatGPT, the general steps agreed upon by the Skill are:
1. Start the MCP server locally, with a path like http://localhost:<port>/mcp
2. Use tools like ngrok to expose it as a public HTTPS endpoint, append /mcp to the tunnel URL, and fill it into ChatGPT
3. In ChatGPT, open Settings → Apps & Connectors → Advanced settings and enable Developer Mode
4. Create a new remote MCP application and paste the public MCP URL
5. Refresh the application after modifying tools or metadata to allow ChatGPT to reload the descriptor

The UI conventions on the Apps SDK side are consistent with the official documentation: new applications prioritize _meta.ui.resourceUri and ui/* bridge; ChatGPT still supports _meta["openai/outputTemplate"] and window.openai extensions. Please refer to Build your MCP server and Build your ChatGPT UI for the exact API specifications.

Applicable Scenarios and Notes¶

It is suitable for these situations:
- Building a ChatGPT App (MCP tools + embedded Widget) from scratch
- Having an existing demo repository and needing to supplement annotations, CSP, URI versioning, and decoupled data/render tools according to the current documentation
- Troubleshooting debugging: descriptor mismatches, Widget not rendering, bridge / window.openai misuse
- Preparing structure and checklists before submitting to the public directory (only go through the submission process if you explicitly plan to publish)

Please note when using it:
- Documentation first, then code: The Skill enforces documentation-first practices; without $openai-docs, use the search/fetch capabilities of the Developer Docs MCP, or directly open the canonical Apps SDK page, do not stop working and write blindly due to failed searches.
- Do not default to building a full scaffold from scratch: When there are close official or ext-apps examples, copy the minimal relevant files first and then modify them.
- Do not teach incorrect API surfaces: Wrappers like app.sendMessage() in repository examples are convenience layers; external explanations should return to the bridge or window.openai.* from the documentation.
- Public submission is an optional path: Internal/private applications can continue to use Developer Mode, do not generate full submission materials by default.
- Factual details are subject to first-hand documentation: Apps SDK and MCP Apps are still evolving, and the Skill itself requires that “if there is a conflict between the documentation and old repository patterns, the current documentation shall prevail”.

Summary¶

chatgpt-apps packages ChatGPT App development into a reusable Agent workflow: classifying forms, planning tools, selecting upstream examples, setting up MCP and Widget, validating against contracts, and providing Developer Mode debugging steps. If you are using Codex, Cursor, or other tools that support Agent Skills for Apps SDK projects, using it alongside $openai-docs will make it far less likely to deviate from official patterns than relying on generic prompts alone.

Official links:
- Skill source code: https://github.com/openai/skills/tree/main/skills/.curated/chatgpt-apps
- Codex Skills documentation: https://developers.openai.com/codex/skills
- Apps SDK documentation can be accessed from https://developers.openai.com/apps-sdk/ (including MCP server, ChatGPT UI, reference materials, etc.)

Build ChatGPT Apps with chatgpt-apps Skill: MCP Server + Widget UI