Write a reusable skill

If a GPT’s instructions are its heart, the skill is the heart of a plugin. It’s the format you use to write a reusable workflow: instructions, resources, and scripts if needed. OpenAI skills follow an open standard called “agent skills” (agentskills.io), which means a well-written skill isn’t locked into a single tool. This lesson teaches you how to write one.

The anatomy of a skill

A skill is a folder containing one required file, SKILL.md, and optional elements.

synthese-document/
├── SKILL.md          ← required: instructions + metadata
├── scripts/          ← optional: executable code
├── references/       ← optional: documentation
├── assets/           ← optional: templates, resources
└── agents/
    └── openai.yaml   ← optional: appearance and dependencies

The SKILL.md file must include a name and a description. Here’s a minimal example:

---
name: synthese-document
description: Summarizes a provided document into three parts (overview, key points, open questions). Use when the user requests a summary or report of an attached document.
---

# Document Summary

1. Read the entire document before writing.
2. Write three sections: Overview (3 sentences), Key Points (max 5 bullets), Open Questions.
3. Rely only on the document; if information is missing, write "not provided."
4. Use the template in `assets/modele.md` for formatting.

The description is the centerpiece

ChatGPT and Codex activate a skill in two ways. Either you call it explicitly—by typing @ in ChatGPT, or /skills and $ in Codex—or the tool selects it automatically when your request matches its description. That’s why the documentation emphasizes this field: you need a concise description that starts with the primary use case and trigger words, and clearly states its limits.

A specific mechanism drives this requirement: progressive disclosure. Initially, ChatGPT and Codex read only the name and description of each installed skill; they load the full instructions from SKILL.md only when they actually use the skill. This lets you install many skills without clogging the context, but it also means a vague description leads to a skill that either never gets chosen at the right time—or gets chosen at the wrong time.

Optional settings

The agents/openai.yaml file lets you polish the display in the desktop app (name, short description, icons, color, default prompt), declare tools the skill depends on—an MCP server, for example—and set an invocation policy. Setting allow_implicit_invocation: false prevents ChatGPT from choosing the skill on its own: useful for sensitive workflows you want to trigger only on demand.

Where skills live, and how to share them

A standalone skill works in the ChatGPT desktop app, in Codex via the command line, and in its editor extension; in Codex, project skills go in the .agents/skills folder of the repository. To make a skill available to others, OpenAI recommends packaging it into a plugin: a plugin can bundle multiple skills and add connections to MCP servers or presentation elements. Skills included in a plugin then become available in Chat and Work modes in ChatGPT, on the web, desktop, and mobile. In ChatGPT on the web, the Skills tab in the plugin directory also lets you create a skill via conversation (using the built-in skill-creator skill), with an editor, or by import, and share it within your workspace; this tab is reserved for eligible Business, Enterprise, Healthcare, and Edu plans.

Your turn

From GPT to skill. Take the instructions from the GPT you built in lessons 4 through 7. Transform them into a SKILL.md: a short name, a description that says when to use it and when not to, numbered steps, and your knowledge files stored in references/. Then test the skill twice: once by calling it with @, and once with a regular request that should trigger it.

Official sources: Build skills (ChatGPT documentation: SKILL.md, description, locations) · Skills in ChatGPT (OpenAI Help Center: Skills tab, plans, sharing)

Key takeaways

• A skill is a folder with a SKILL.md (required name + description) and optional resources; it follows the open agent skills standard
• The description decides when the skill is chosen: lead with the use case, trigger words, and limits
• Progressive disclosure: only the name and description are read first; instructions load at usage time
• To share a skill, package it into a plugin

Test your knowledge

From GPTs to plugins: validate the full journey.

1. Custom Instructions, Memory, GPT: what's the difference?

Answer: Custom Instructions tint all your conversations; Memory retains facts about you over time; a GPT is a packaged assistant—instructions, knowledge, tools—shareable with others.

2. What does a good GPT system instruction contain?

Answer: The role, scope (what it does and doesn’t do), tone, response format, and handling of edge cases—written like a job description, not a wish list.

3. What is the Knowledge base for?

Answer: To provide the GPT with reference documents it consults to answer—your guides, catalogs, or procedures, rather than relying solely on its training memory.

4. What happens to a GPT's actions when migrating to a plugin?

Answer: They aren’t transferred: you must check if an app already exists in the plugin directory, otherwise rebuild the integration, for example with an MCP server. The instructions become a skill, and the knowledge base becomes reference files.

5. Before sharing a GPT or plugin, what do you check?

Answer: Tests on real cases and edge cases, compliance with usage policies, clarity of the description, a privacy policy for any public action, and that no sensitive data lurks in the instructions or files.

A shared tool commits its creator: test as if your users were already there, and migrate your GPTs before December 11, 2026.