AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

chatgpt-apps

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.

Original source
openai
License
Apache-2.0
Pinned revision
49f948faa9258a0c61caceaf225e179651397431

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read openai--chatgpt-apps at revision 49f948faa9258a0c61caceaf225e179651397431, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 9

references/repo-contract-and-validation.md

Repo Contract And Validation

Load this reference when scaffolding or reviewing a generated ChatGPT app repo.

The goal is not “files were created.” The goal is “the repo is plausibly runnable and follows a stable working-app contract.”

Minimum Working Repo Contract

Every generated repo should satisfy the relevant parts of this contract.

1. Shape

  • The repo shape matches the chosen archetype.
  • The repo structure is simple enough that a user can identify where the server and widget live.

2. Server

  • There is a clear MCP server entry point.
  • The server exposes /mcp.
  • The server registers tools intentionally.
  • If a UI exists, the server registers a resource/template with the MCP Apps UI MIME type.

3. Tools

  • Each tool maps to one user intent.
  • Descriptions help the model choose the tool.
  • Required annotations are present and accurate.
  • UI-linked tools use _meta.ui.resourceUri.
  • _meta["openai/outputTemplate"] is treated as optional compatibility, not the primary contract.
  • When the app is connector-like, data-only, sync-oriented, or intended for company knowledge or deep research, it implements standard search and fetch tools instead of custom substitutes.

4. Widget

  • The widget initializes the MCP Apps bridge when needed.
  • The widget can receive ui/notifications/tool-result.
  • The widget renders from structuredContent.
  • Interactive widgets use tools/call.
  • Baseline follow-up messaging uses ui/message.
  • window.openai is optional and additive.

5. Local Developer Experience

  • There is a clear way to start the app locally.
  • There is at least one low-cost check command when the stack supports it.
  • The response explains how to connect the app in ChatGPT Developer Mode when relevant.

Validation Ladder

Run the highest level you can without overfitting to a single stack.

Level 0: Static contract review

Check for:

  • chosen archetype is sensible
  • repo shape matches archetype
  • /mcp route is present
  • tool/resource/widget responsibilities are coherent
  • if the app is connector-like or sync-oriented, search and fetch are present with the expected standard shape

Level 1: Syntax or compile checks

Use the stack-appropriate cheapest check available, for example:

  • Python syntax check
  • TypeScript compile check
  • framework-specific lint or build sanity check if already installed

Level 2: Local runtime sanity

If feasible:

  • start the server
  • confirm the health route or /mcp endpoint responds

Level 3: Host loop validation

If feasible:

  • inspect with MCP Inspector
  • test through ChatGPT Developer Mode
  • confirm widget updates after tool results

Reporting Rule

Always say which validation level was reached and what was not run.

That makes the skill more reliable because it separates:

  • “repo shape looks right”
  • “syntax is valid”
  • “server starts”
  • “host integration was actually exercised”