How do you create a skill in ChatGPT? SKILL.md, @skill-creator and Record & Replay

The quickest way to create a skill in OpenAI's ChatGPT is to ask for one: type @skill-creator in ChatGPT Work and answer the questions it asks. A skill is only a folder with a SKILL.md file in it, so you can also write one by hand in about a minute, and on a Mac you can demonstrate the task and let ChatGPT draft the skill from the recording. Use the creator for most workflows, write the file by hand when the folder belongs in a repository, and record when the job is easier to show than to describe.

#What is a skill in ChatGPT?

OpenAI's build-skills page describes a skill as something that "packages instructions, resources, and optional scripts so either product can follow a workflow reliably", where the two products are ChatGPT and Codex. The same page says skills "build on the open agent skills standard", the cross-vendor SKILL.md format published at agentskills.io. If you have not met that format before, our post on what a SKILL.md actually is covers the shape, and the Agent Skills hub tracks which other agents read it.

The mechanism that makes skills cheap to have around is progressive disclosure. OpenAI puts it this way: "ChatGPT and Codex start with each skill's name and description, then load the full SKILL.md instructions when they decide to use that skill." Nothing in the body of your skill costs anything until the skill is chosen.

Two sentences from the documentation are worth pinning up before you start, because they decide where your skill will and will not appear:

Standalone skills are available in the ChatGPT desktop app, Codex CLI, and IDE extension. Skills bundled in plugins are also available in Chat and Work across ChatGPT on the web, desktop, and mobile.

So a loose skill folder is a desktop and terminal thing. Getting the same skill onto the web or a phone means packaging it as a plugin, which is the last section of this guide. The ChatGPT platform hub has the wider picture of how Chat, Work and Codex fit together.

#Which of the three ways should you use?

All three end at the same artefact, a folder with a SKILL.md in it, so the choice is about how you would rather spend the first ten minutes, not about what you end up with.

#How do you create a skill with @skill-creator?

OpenAI's build-skills page gives the invocation twice, once per product: "In ChatGPT Work, invoke it as @skill-creator. In Codex, invoke it as $skill-creator." The separate Skills & Plugins page says only "In ChatGPT, start with @skill-creator", without naming Work. Where the two differ we follow the dedicated build-skills page, so plan on being in Work.

What happens next is a short interview. In OpenAI's words, "the creator asks what the skill does, when it should trigger, and whether it should stay instruction-only or include scripts. Instruction-only is the default." Leaving that default alone is usually right: OpenAI's own best-practice list says to "prefer instructions over scripts unless you need deterministic behavior or external tooling."

The Skills & Plugins page sets out the four steps around that interview, and step three is the one people skip:

1. Choose one focused task, noting "what you normally start with, such as files, links, or notes, and what a finished result should look like."
2. Describe the workflow to the creator, including "the expected format, and anything the skill should always include or avoid."
3. "Review and try the draft" against a realistic request, and refine it if the result misses a step.
4. Install and reuse it, or select it explicitly.

#How do you write a SKILL.md by hand?

Make a directory, put a SKILL.md in it, and give that file YAML frontmatter with two keys. This is the whole minimum, quoted from OpenAI's page:

---
name: skill-name
description: Explain exactly when this skill should and should not trigger.
---
Skill instructions for ChatGPT or Codex to follow.

The directory can grow from there. OpenAI and the Agent Skills specification share the same three optional folders, and OpenAI adds one of its own that the specification does not define:

my-skill/
  SKILL.md        (required)
  scripts/        (optional: executable code)
  references/     (optional: documentation the agent reads on demand)
  assets/         (optional: templates and other resources)
  agents/
    openai.yaml   (optional: OpenAI-specific metadata)

OpenAI's page states the two required fields but not their limits. The specification does, and it is the document to check before you pick a name:

The specification also asks you to "keep your main SKILL.md under 500 lines" and to move detailed reference material into separate files, because the agent loads the entire body once it activates the skill.

#Where do the skill files go?

OpenAI documents the load locations under a heading that names one product: "Where Codex loads local skills". Codex scans .agents/skills in every directory from your current working directory up to the repository root, plus three more scopes:

Two details from the same page save an afternoon later. "If two skills share the same name, Codex doesn't merge them; both can appear in skill selectors", so a duplicated name is a confusing picker rather than an error. And "Codex supports symlinked skill folders and follows the symlink target when scanning these locations", which is how you keep one canonical copy in a dotfiles repository.

For the ChatGPT desktop app itself, the four OpenAI pages we read for this guide (build-skills, Skills & Plugins, Plugins and Record & Replay) name no folder that the app scans. What they do say is where to look inside the app: "In the ChatGPT desktop app, open Skills in the sidebar to view and explore skills created across your projects." Treat the absence of a documented desktop path as a gap in the documentation we checked rather than as proof that no such folder exists.

Once the files are in place, Codex "detects skill changes automatically. If an update doesn't appear, restart Codex."

#How do you invoke a skill once it exists?

OpenAI names two routes. The explicit one differs by surface:

• In ChatGPT, "type @ to select a skill."
• "In Codex CLI or the IDE extension, run /skills or type $ to mention a skill."

The implicit one is the same everywhere: "ChatGPT or Codex can choose a skill when your task matches the skill description."

#Why does the description decide whether your skill ever runs?

Because the description is the only part of your skill the model sees before it chooses. OpenAI is direct about the consequence: "Because implicit matching depends on description, write concise descriptions with clear scope and boundaries. Front-load the key use case and trigger words so a host can still match the skill if descriptions are shortened."

That last clause points at a real budget. In the paragraph covering Codex, OpenAI writes that the initial skills list "uses at most 2% of the model's context window, or 8,000 characters when the context window is unknown", that "if many skills are installed, Codex shortens skill descriptions first", and that "for large skill sets, Codex may omit some skills from the initial list and show a warning". The 8,000 figure is the fallback for an unknown context window, not a flat cap, and OpenAI adds that "this budget applies only to the initial skills list. When Codex selects a skill, it still reads the full SKILL.md instructions for that skill."

Practically: a description that opens with the trigger words survives being shortened. One that opens with "This skill helps you" does not.

#How do you record a skill instead of writing one?

Record & Replay turns a demonstration into a skill, and it has a hard platform requirement. OpenAI states it in the first line of the page: "Record & Replay is available on macOS. Computer Use must also be available and enabled."

The documented sequence is seven steps:

1. In the ChatGPT desktop app, select ChatGPT and turn on Work in the switcher, or select Codex, then open Plugins.
2. Open the + menu.
3. Select Record a skill.
4. Review the suggested prompt, add any helpful context, and submit it.
5. Approve the permission request when you are ready to demonstrate the workflow.
6. Perform the workflow on your Mac.
7. Stop recording "from the menu bar or overlay, or tell the chat that you are done."

Afterwards, "ChatGPT or Codex inspects the captured workflow and drafts a skill. The skill explains when to use the workflow, what inputs it needs, what steps to follow, and how to verify the result." The page does not name a file format for the recording and does not say where the drafted skill is saved, so budget a few minutes to find it in the Skills sidebar rather than expecting a path.

One warning from OpenAI's own tips is worth repeating, because a recording captures whatever is on screen: "use realistic inputs, but avoid secrets and sensitive data."

If the feature is missing entirely, the page names the reason: "If your organization manages Codex with requirements.toml, the [features].computer_use requirement controls Record & Replay too. Setting computer_use = false makes both features unavailable."

#What does agents/openai.yaml add?

It is optional, and it exists to make the skill look right in the desktop app and to control when the skill fires. OpenAI's example sets a display name, a short description, two icons, a brand colour and a default prompt under interface, and one key under policy:

policy:
  allow_implicit_invocation: false

The documented behaviour of that key: allow_implicit_invocation defaults to true, and "when false, Codex won't implicitly invoke the skill based on user prompt; explicit $skill invocation still works." Reach for it when a skill is destructive or expensive and you want it fired only on request.

The same file can declare tool dependencies, including an MCP server, under a dependencies.tools list.

#When should you package the skill as a plugin?

When anyone other than you needs it. OpenAI's line is that "direct skill folders are best for local authoring and repo-scoped workflows", and that you should package a plugin "if you want to distribute a reusable skill, bundle two or more skills together, or ship a skill alongside a connector."

A plugin is a folder with a plugin.json manifest at its root. OpenAI's developer guide gives a manifest example and marks no field in it as required, and the prose it does carry describes the manifest as a whole rather than any single key: "The portable manifest identifies the plugin", and "The root plugin.json is the portable entry point." So treat only the file itself as obligatory, and version as something you will want rather than something the format demands. The guide's own example also sets author, homepage, repository, license and keywords; the four keys below are the subset you need to start:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "my-plugin",
  "version": "0.1.0",
  "description": "Bundle reusable skills and MCP servers."
}

Skills go in a skills/ directory beside that manifest, one folder per skill. The guide's own instruction is to "Keep plugin.json, mcp.json, skills/, and assets/ at the plugin root."

Packaging changes which surfaces the skill reaches, in both directions:

That last row is the one that surprises people: a skill you want in the IDE extension has to stay a plain folder. One more timing note from the plugins page: "bundled skills become available when you start a new chat or CLI session after installation."

#How do you turn a skill off without deleting it?

For local Codex skills, OpenAI documents a config entry rather than a delete:

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

Restart Codex after changing ~/.codex/config.toml.

#What should you check before installing someone else's skill?

OpenAI documents $skill-installer for pulling curated skills into a local Codex setup, for example $skill-installer linear, and notes that "you can also prompt the installer to download skills from other repositories." A skill is instructions that an agent will follow, and optionally scripts it will run, so anything you did not write deserves the same reading you would give a shell script from a stranger. Work through our SKILL.md audit checklist before you install one. ClawDocx does not vet, endorse or certify any third-party skill, plugin or MCP server named on this page.

If you would rather see the same steps for a different agent, our guide to building a custom skill from a SKILL.md walks through the OpenClaw version of the same folder.