SkillAgentSearch skills...

chatgpt-apps

Build, scaffold, refactor, and troubleshoot ChatGPT Apps SDK applications that combine an MCP server and widget UI

Install / Use

npx skills add openai/skills --skill chatgpt-apps

Installs into whichever agent you are using.

About this skill
📄

SKILL.md

Installable skill definition

Quality Score

89/100

Category

Automation

Supported Platforms

OpenAI Codex

Our assessment of chatgpt-apps

chatgpt-apps scores 89/100 on our quality scale, 1319th of 2,780 Automation skills we index (top 48%).

Its SKILL.md is 19 KB long, well organised into 24 sections and no code examples: a thorough specification that gives an agent plenty to work with.

With 27,599 GitHub stars, it is one of the more widely adopted skills in the catalogue.

Substance
30/30
Structure
13/20
Description
12/15
Adoption
19/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated about 2 months ago, so chatgpt-apps is actively maintained.
  • Our last check on 2026-10-31 found the source still online.
  • No license is declared. By default that means all rights are reserved: you can read it, but reusing or redistributing it is not clearly permitted. Ask the author before building on it commercially.
  • Its trust signals score 88/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.

Safety scan

No issues found

Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.

AI review by kimi-k2.7-code on 2026-09-26. Automated pattern scan on 2026-09-26. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.

chatgpt-apps compared with similar skills

All 4 of these similar skills score higher than chatgpt-apps; compare them before choosing.

SkillScoreStarsUpdatedFormat
chatgpt-apps (this skill)by openai8927.6k2mo agoSKILL.md
taste-skillby Leonxlnx100116.8k8d agoCLAUDE.md
Agent-Reachby Panniantong100112.3k9d agoCLAUDE.md
rufloby ruvnet10081.9ktodayCLAUDE.md
headroomby headroomlabs-ai10079.8ktodayCLAUDE.md

Frequently asked questions

How do I install chatgpt-apps?
Run npx skills add openai/skills --skill chatgpt-apps. The install tabs above show the steps for each supported agent.
Which AI agents does chatgpt-apps work with?
It is written for OpenAI Codex, as a SKILL.md file. Other agents that read the same format can often use it too.
Is chatgpt-apps safe to use?
Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It declares no license and scores 88/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is chatgpt-apps still maintained?
The repository was last updated about 2 months ago, so chatgpt-apps is actively maintained.

name: chatgpt-apps description: Build, scaffold, refactor, and troubleshoot ChatGPT Apps SDK applications that combine an MCP server and widget UI. Use when Codex needs to design tools, register UI resources, wire the MCP Apps bridge or ChatGPT compatibility APIs, apply Apps SDK metadata or CSP or domain settings, or produce a docs-aligned project scaffold. Prefer a docs-first workflow by invoking the openai-docs skill or OpenAI developer docs MCP tools before generating code.

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
  3. 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.
  4. 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
  5. Cite the docs URLs you used when explaining design choices or generated scaffolds.
  6. Prefer current docs guidance over older repo patterns when they differ, and call out compatibility aliases explicitly.
  7. 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

  • Some examples wrap the bridge with an app object (for example, @modelcontextprotocol/ext-apps/react) and expose helper names like app.sendMessage(), app.callServerTool(), app.openLink(), or host getter methods.
  • Treat those wrappers as implementation details or convenience layers, not the canonical public API to

Truncated for display — read the full file on GitHub.

Related Skills

View on GitHub
GitHub Stars27.6k
CategoryAutomation
Updated2mo ago
Forks1.9k

Languages

Python

Trust signals

88/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

1 medium