For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Primary navigation

Suggested
API Dashboard
Try ChatGPT

Build skills

Add repeatable workflows around your plugin's MCP tools.

A skill complements your MCP server by teaching ChatGPT and Codex how to use its tools in a repeatable workflow. Use the server for live data, authentication, authorization, and controlled actions. Use the skill for tool sequences, decision points, output requirements, examples, templates, and other reusable guidance.

A plugin can contain one skill or a group of related skills. Keep every skill focused on a recognizable user goal from your use-case inventory. A skill can also work without an MCP server when the workflow needs only packaged instructions and resources.

Create a skill

The fastest way to start is with the built-in skill creator. Describe the user goal and the MCP tools that support it:

@skill-creator Create a skill named tabletop-dice that understands dice
notation such as 3d6, calls roll_dice once for each die, and reports every
roll and the total.

In Codex, invoke the same creator as $skill-creator.

You can also create the files manually. Each skill lives in its own directory and requires a SKILL.md file:

  • skills
    • tabletop-dice
      • SKILL.md Required instructions and metadata
      • references Optional documentation
      • scripts Optional executable code
      • assets Optional templates and resources

Write SKILL.md

Start the file with a name and a description, followed by the instructions:

---
name: tabletop-dice
description: Roll one or more dice for tabletop games and report each result and the total.
---

Use this skill when the user asks to roll dice.

1. Parse requests written as `NdS` as N dice with S sides. For example, `3d6`
   means three six-sided dice.
2. Call `roll_dice` once for each requested die and pass S as `sides`.
3. Report each tool result in order.
4. When the user requests multiple dice, add the results and report the total.

Do not invent, replace, or reroll a result unless the user asks you to.

The description determines when the model considers the skill. State the workflow and the conditions that should trigger it. Put detailed procedure, format, and safety instructions in the body.

Define the workflow boundary

Connect every skill to one or more use cases. The instructions should make the following clear:

  • What input the workflow expects.
  • Which steps the model should follow.
  • What output the user should receive.
  • Which facts the model must not infer.
  • When the workflow should ask a question, stop, or decline.
  • Which supporting files the model should consult.

Prefer one focused skill over a large collection of loosely related instructions. Split workflows when they have different triggers, inputs, or success criteria.

Add supporting resources

Keep SKILL.md concise and place detailed material next to it:

  • Use references/ for policies, schemas, examples, and background material.
  • Use assets/ for templates or files the workflow should copy or transform.
  • Use scripts/ when the workflow needs deterministic computation or file processing.

Reference supporting files from SKILL.md and explain when to load or run them. Do not add a script when instructions and existing tools can complete the task reliably.

Connect skills to MCP tools

A skill can guide the model through tools exposed by the plugin’s MCP server. Use the skill for workflow instructions and the server for live data, authorization, and controlled actions.

If a skill requires an MCP server, declare the dependency in agents/openai.yaml:

dependencies:
  tools:
    - type: "mcp"
      value: "dice-roller"
      description: "Roll an N-sided die"
      transport: "streamable_http"
      url: "https://tinymcp.dev/api/moldy-aloof-zettabyte/mcp"

A dependency makes the required tool available; it does not replace clear workflow instructions. Tell the model which tools to use, in what order, and how to handle missing or ambiguous results.

Import a skill from MCP

You can upload a packaged skill during submission or import it from the plugin’s MCP server. The MCP option keeps the skill’s instructions and supporting files with the server deployment.

OpenAI imports skills from MCP when you select Scan Tools in the plugin submission portal. The imported files become a snapshot in the draft; ChatGPT and Codex do not fetch them from your MCP server at runtime. After changing the skill, deploy the server and scan it again before submitting a new plugin version.

For the capability declaration, discovery methods, resource manifest, and import limits, see Import skills from the MCP server.

Test the skill

Test with representative requests from the use-case inventory:

  1. Direct requests that should activate the skill.
  2. Indirect requests that express the same goal.
  3. Incomplete inputs that should trigger a follow-up question.
  4. Requests that should not activate the skill.
  5. Edge cases where the skill must avoid inventing information or taking an unsupported action.

Review both activation and output quality. Refine the description when the skill activates at the wrong time. Refine the instructions when it chooses the right workflow but produces an inconsistent result.

Package the skill

Point the plugin manifest at the skills directory:

{
  "name": "dice-roller",
  "version": "1.0.0",
  "description": "Roll dice for tabletop games",
  "skills": "./skills/",
  "apps": "./.app.json"
}

See Package your plugin for the complete manifest, MCP server mapping, local testing, and distribution flow.