Build skills | ChatGPT Learn
For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending
.md to the page URL.
ChatGPT
Start searching
API Dashboard
Try ChatGPT
Home
API
Overview
Get started with the OpenAI API
Models
Explore models and compare capabilities
Agents
Build persistent agents on hosted infrastructure
Tools
Connect models to tools and data
Audio & voice
Build speech and realtime voice experiences
Production
Deploy and scale your API integrations
API reference
Explore endpoints, parameters, and responses
ChatGPT
Sign in with ChatGPT
Apps powered by your user's ChatGPT plan
Plugins
Extend ChatGPT and Codex
Workspace Agents
Trigger published ChatGPT workspace agents
Commerce
Build commerce flows in ChatGPT
Ads
Publish and measure ads in ChatGPT
ChatGPT + Codex user docs
Guides and product docs for ChatGPT and Codex
Use cases
Example workflows and tasks teams can take on with ChatGPT or Codex
Docs
Use cases
Training
Resources
Resources
Showcase
Demo apps to get inspired
Blog
Learnings and experiences from developers
Cookbook
Notebook examples for building with OpenAI models
Learn
Docs, videos, and demo apps for building with OpenAI
Community
Programs, meetups, and support for builders
Overview      Features      Configuration      Developers      Security      Administration      Use Cases      Resources
Search the docs
Search docs
Suggested
responses createreasoning_effortrealtimeprompt caching
Primary navigation
API  ChatGPT  Docs  Use cases  Training  Resources  Resources
Search docs
Suggested
responses createreasoning_effortrealtimeprompt caching
Overview  Models  Agents  Tools  Audio & voice  Production  API reference
DocsOverview
Home
Get started
Quickstart
Using GPT-6
Key concepts
Core concepts
Responses API
Decisions API
Conversation state
Background mode
Streaming
WebSocket mode
Mid-turn steering
Multi-agent
Webhooks
File inputs
Compaction
Counting tokens
SDKs and CLI
OpenAI SDK
OpenAI CLI
Resources
Changelog
Deprecations
Supported countries
OpenAI Crawlers
Terms and policies
Legacy APIs
Agent Builder
Overview
Migration guide
Node reference
Safety in building agents
Evals
Getting started
Working with evals
Prompt optimizer
External models
Best practices
Graders
Fine-tuning
Optimization cycle
Supervised fine-tuning
Vision fine-tuning
Direct preference optimization
Reinforcement fine-tuning
RFT use cases
Best practices
Assistants API
Migration guide
Model catalog
Choose a model
Pricing
Model selection
Text and code
Text generation
Code generation
Structured output
Prompting
Overview
Prompt engineering
Citation formatting
Migration guide
Prompt generation
Frontend prompting
Reasoning
Reasoning models
Reasoning best practices
Images
Images and vision
Image input cost calculator
Image generation
Overview
Image prompting
Realtime and audio
Audio and speech
Getting started
Voice agents
Specialized models
Deep research
Embeddings
Moderation
Overview
Agents API
Overview
Quickstart
Architecture
Configuring Agents
Sessions
Run and continue sessions
Events and items
Manage sessions
Webhooks
Environments and sandboxes
OpenAI-hosted sandboxes
Self-hosted sandboxes
Sandbox lifecycle
Pre-warm sandboxes
Sandbox security
Files and artifacts
Tools and integrations
Web search
Computer use
Functions
MCP connections
Plugins
Vaults
Multi-agent
Observability and usage
Tracing
Errors and recovery
API reference
Bedrock Managed Agents
Agents SDK
Overview
Quickstart
Agent definitions
Models and providers
Running agents
Sandbox agents
Orchestration
Guardrails
Results and state
Integrations and observability
Evaluate agent workflows
ChatKit
Overview
Customize
Widgets
Actions
Advanced integrations
Overview
Function calling
Search and retrieval
Web search
File search
Retrieval
Connect tools and data
MCP servers
Secure MCP Tunnel
Build tool workflows
Skills
Tool search
Programmatic tool calling
Async tool calling
Computer and code
Shell
Computer use
Apply Patch
Local shell
Code interpreter
Media
Image generation
Overview
GPT-Live
Getting started
Prompting
Managing sessions
Delegation and tools
Migrate to GPT-Live
Partner integrations
Realtime API
Getting started
Prompting
Managing conversations
Voice activity detection
Tools and MCP
Build with voice
Voice agents
Connect voice to Decisions
Custom voices
Cost optimization
Connections
WebRTC
WebRTC with WARP
WebSockets
Telephony and SIP
Server-side controls
Audio processing
File transcription
Live transcription
Live translation
Text to speech
Audio in Chat Completions
Go live
Production best practices
Deployment checklist
Performance and quality
Fast mode
Ultrafast mode
Latency optimization
Predicted Outputs
Accuracy optimization
Cost and throughput
Cost optimization
Prompt caching
Prompt cache diagnostics
Batch
Flex processing
Safety and governance
Safety best practices
Red teaming
Daybreak
Safety checks
Safety classifiers
Cybersecurity checks
Misalignment monitoring
Enforcement notifications
Under-18 guidance
CSAM guidance
Content provenance
Your data
Private Safety Processing
Permissions
Infrastructure and access
Terraform provider
Overview
Projects and access
Service accounts
Rate limits and spend
Model, tool, and data controls
Import and reconciliation
Private Link
IP allowlist
Organization blocking
Mutual TLS
Workload identity federation
Federation rules
X.509 certificates
Kubernetes
AWS
Microsoft Azure
Google Cloud
Oracle Cloud Infrastructure
GitHub Actions
SPIFFE
IP egress ranges
Amazon Bedrock
Operations
Rate limits
Spend limits
Admin APIs
Error codes
Overview   Sign in with ChatGPT  Plugins  Workspace Agents  Commerce  Ads  ChatGPT + Codex user docs   Use cases
DocsOverview
Home
Quickstart
Request a client ID
Identity
On your website
In your ChatGPT plugin
ChatGPT plan usage
Overview
UI/UX guidelines
Registration and sign-in
Accounts and sessions
Models and inference
Codex app-server
Self-hosted VMs
Token reference
Errors and recovery
Preview limitations
Home
Quickstart
Core concepts
Plugin architecture
Skills
MCP server
Plan
Brainstorm use cases
Define tools
Build
Build an MCP server
Add UI to your MCP server (optional)
Add events to your MCP server (optional)
Extensions
Authenticate users
Build skills
Package your plugin
Examples
Test and publish
Connect and test your plugin
Submit and publish
Submission error reference
Conversion specs
Restaurant reservation spec
Get Quote spec
Product checkout spec
Guides
UI guidelines
Optimize Metadata
Submit a Claude Code plugin
Security & Privacy
Troubleshooting
Resources
Changelog
Plugin guidelines
MCP server review requirements
Plugin UI reference
Checkout API reference
Home
Get started
Trigger workspace agent runs
Authenticate with Workspace Agent access tokens
Home
Guides
Get started
Best practices
File Upload
Overview
Products
API
Overview
Feeds
Products
Promotions
Ads Overview
Measurement
Measurement Pixel
Multiple Pixels (Advanced)
Image Tag
Conversions API
Supported Events
Advertiser API
Overview
API Partner Setup
Campaign Management
Bidding & Budgets
Targeting
Product Feeds
Hotel Feeds (limited beta)
Conversion Tracking
Reporting
Troubleshooting
Account Management
API Reference
Authentication
Ad Account
Audit Logs
Campaigns
Ad Groups
Ads
Insights
Files
Conversion Setup
Overview  Features  Configuration  Developers  Security  Administration  Use Cases  Resources
DocsDevelopers
Home
Get started
Quickstart
Use ChatGPT
Get started with Work
Meet dots
Import from another agent
Foundations
Prompting
Model selection
Personalize ChatGPT
Skills & Plugins
Permissions
Explore
What's new
Models
Pricing
Glossary
Available on
ChatGPT desktop app
ChatGPT mobile app
ChatGPT on the web
Codex CLI
Codex IDE extension
Codex Cloud
Releases
Changelog
Feature Maturity
Open Source
Overview
Workflows
Projects and chats
Sites
Build plugins
Visualizations
Scheduled tasks
Long-running work
Notifications
Pets
Codex Micro
Capabilities
Browser
Computer use
Voice
Plugins
Sign in with ChatGPT
Web search
Image generation
Image inputs
Appshots
Browser extension
Work with files
dots
Meet dots
Getting started
Messaging
Tasks and memory
Computers and apps
Controls
ChatGPT Space
Overview
Getting started
Pages
Work with agents
Collaboration
Reference
Commands
Slash commands
Settings
Troubleshooting
Overview
Customization
Overview
Memories
Computer History
Config file
Config Basics
Advanced Config
Config Reference
Environment Variables
Sample Config
Agent configuration
AGENTS.md
Subagents
Speed
Rules
Extend ChatGPT and Codex
Record & Replay
MCP
Linux
Desktop app
Windows
Desktop app
Windows sandbox
WSL
Overview
Development workflows
Code review
Integrated terminal
Extend and automate
Build skills
Site tools (WebMCP)
Annotations Extensibility
Hooks
Environments
Modes
Local environments
Git worktrees
Codex Cloud
Cloud environments
Build with Codex
Codex SDK
App Server
GitHub Action
Non-interactive mode
Third-party integrations
GitHub
GitLab (Beta)
Slack
Linear
Reference
CLI customization
Developer commands
Developer settings
Overview
Permissions
Profiles
Sandboxing
Auto-review
Agent approvals & security
Codex Security
Overview
Codex Security plugin
Quickstart
Run a security scan
Run a deep scan
Review code changes
Use the Security workbench
Triage a backlog
Fix findings
Propose security hardening
Write vulnerability reports
Export and track findings
Changelog
Codex Security CLI
Quickstart
Run bulk scans
Run scans in CI
GitLab CI/CD
Reference
FAQ
TypeScript SDK
Codex Security Cloud
Setup
Security Review
Improving the threat model
FAQ
Cyber safety
Models & Trusted Access
Recommended configuration
Overview
Getting started
Admin rollout guide
Admin plugin
Feature setup
Dots
Space
Teams and Team Tasks
ChatGPT in Slack and Teams
Workspace connections
Local computer access for Work Cloud and dots
Sites
Identity and access
Authentication overview
Groups and provisioning
Dynamic groups
User lifecycle management
Roles and workspace permissions
Personal access tokens
Service accounts
Deployment and configuration
Windows app deployment
Manage app updates
Managed configuration
Remote connections
Workspace model availability
Amazon Bedrock
Bedrock GovCloud configuration
Connect to a gateway
Sign in with ChatGPT
Use API/provider credentials
Roll out a gateway
Gateway compatibility
Bedrock through LiteLLM
ChatGPT Work
Overview
Cloud security
Local security
Usage and cost
Admin FAQ
Collaboration and sharing
GPTs and sharing
Plugins and connections
Plugin controls
Plugin management
Skill controls
Migrate custom GPTs to plugins
Usage and analytics
Workspace analytics
Usage Insights
Analytics API
Security and compliance
Governance
Agent security
Prisma AIRS
HIPAA configuration
Compliance API and audit events
Explore use cases
Collections
Home
Videos
Showcase
OpenAI Academy
Online trainings
Community
Codex Ambassadors
Codex for Students
Codex for Open Source
Events
Blog
Company blog
Developer blog
Explore use cases
Collections
Home
Videos
Showcase
OpenAI Academy
Online trainings
Community
Codex Ambassadors
Codex for Students
Codex for Open Source
Events
Blog
Company blog
Developer blog
Showcase   Blog  Cookbook  Learn  Community
DocsSelect...
All posts
Recent
Bringing my LED display to life with GPT-Live-1 and Codex
Rethinking skills and prompts for GPT-6 Astra
Architectural visualization with Astra
Building games with Astra
Meet Rosalind Workbench: Empowering every scientist to be their own research team
Topics
General
API
Apps SDK
Audio
Codex
Life sciences
Home
Topics
Sign-in with ChatGPT
Agents
Evals
Multimodal
Text
Guardrails
Optimization
ChatGPT
Codex
gpt-oss
Contribute
Cookbook on GitHub
Home
OpenAI Developers plugin
Docs MCP
Categories
Demo apps
Videos
Topics
Agents
Audio & Voice
Computer Use
Codex
Evals
gpt-oss
Fine-tuning
Image generation
Scaling
Tools
Video generation
Community
Programs
Codex Ambassadors
Meet the ambassadors
Codex for Students
Codex for Open Source
OpenAI for Startups
Spaces
Events
Developer Forum
Discord
Reddit
X
API Dashboard
Try ChatGPT
Overview
Development workflows
Code review
Integrated terminal
Extend and automate
Build skills
Site tools (WebMCP)
Annotations Extensibility
Hooks
Environments
Modes
Local environments
Git worktrees
Codex Cloud
Cloud environments
Build with Codex
Codex SDK
App Server
GitHub Action
Non-interactive mode
Third-party integrations
GitHub
GitLab (Beta)
Slack
Linear
Reference
CLI customization
Developer commands
Developer settings
Copy Page
Build skills
Give ChatGPT and Codex new capabilities and expertise
Copy Page
Use agent skills to extend ChatGPT and Codex with task-specific capabilities. A
skill packages instructions, resources, and optional scripts so either product
can follow a workflow reliably. Skills build on the
open agent skills standard.
Skills are the authoring format for reusable workflows. Plugins distribute
reusable skills and connectors through the universal plugin directory shared
by ChatGPT and Codex. Plugins work in Chat and Work across ChatGPT on the web,
desktop, and mobile, in Codex in the ChatGPT desktop app, and through Codex
CLI. Use skills to design the workflow itself, then package it as a
plugin when you want
other people to install it.
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.
In the ChatGPT desktop app, open Skills in the sidebar to view and explore skills
created across your projects.
Atlas Control (macOS)Use the bundled CLI to control Atlas and inspect local browser data.Personal
Exec PlanCreate, maintain, and execute long-form execution plans ("ExecPlans") for complex work.Personal
GitHub Fix CIDebug failing GitHub Actions CIPersonal
LinearManage Linear issues in CodexPersonal
OpenAI DocsReference the official OpenAI Developer docsPersonal
YeetStage, commit, and open PRPersonal
Skill CreatorCreate or update a skillSystem
Skill InstallerInstall curated skills from openai/skills or other reposSystem
$
6 SolMedium
Skills use progressive disclosure to manage context efficiently. 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.
In Codex, the initial list also includes each skill’s file path. To avoid
crowding out the rest of the prompt, this list uses at most 2% of the model’s
context window, or 8,000 characters when the context window is unknown. If many
skills are installed, Codex shortens skill descriptions first. For large skill
sets, Codex may omit some skills from the initial list and show a warning.
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.
A skill is a directory with a SKILL.md file plus optional scripts and references. The SKILL.md file must include name and description.
my-skill/
SKILL.md    Required: instructions + metadata
scripts/    Optional: executable code
references/    Optional: documentation
assets/    Optional: templates, resources
agents/
openai.yaml    Optional: appearance and dependencies
How ChatGPT and Codex use skills
ChatGPT and Codex can activate skills in two ways:
Explicit invocation: Include the skill directly in your prompt. In
ChatGPT, type @ to select a skill. In Codex CLI or the IDE extension, run
/skills or type $ to mention a skill.
Implicit invocation: ChatGPT or Codex can choose a skill when your task
matches the skill description.
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.
Create a skill
If you already know the workflow and it’s easier to show than describe, use
Record & Replay. The recorder captures the
workflow, inspects the steps, and drafts a reusable skill from the
demonstration.
If you want to describe the skill instead, use the built-in creator. In ChatGPT
Work, invoke it as @skill-creator. In Codex, invoke it as:
$skill-creator
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.
You can also create a skill manually by creating a folder with a SKILL.md file:
---
name: skill-name
description: Explain exactly when this skill should and should not trigger.
---
Skill instructions for ChatGPT or Codex to follow.
Codex detects skill changes automatically. If an update doesn’t appear, restart Codex.
Where Codex loads local skills
Codex reads skills from repository, user, admin, and system locations. For repositories, Codex scans .agents/skills in every directory from your current working directory up to the repository root. If two skills share the same name, Codex doesn’t merge them; both can appear in skill selectors.
Skill Scope
Location
Suggested use
REPO
$CWD/.agents/skills
Current working directory: where you launch Codex.
If you’re in a repository or code environment, teams can check in skills relevant to a working folder. For example, skills only relevant to a microservice or a module.
REPO
$CWD/../.agents/skills
A folder above CWD when you launch Codex inside a Git repository.
If you’re in a repository with nested folders, organizations can check in skills relevant to a shared area in a parent folder.
REPO
$REPO_ROOT/.agents/skills
The topmost root folder when you launch Codex inside a Git repository.
If you’re in a repository with nested folders, organizations can check in skills relevant to everyone using the repository. These serve as root skills available to any subfolder in the repository.
USER
$HOME/.agents/skills
Any skills checked into the user’s personal folder.
Use to curate skills relevant to a user that apply to any repository the user may work in.
ADMIN
/etc/codex/skills
Any skills checked into the machine or container in a shared, system location.
Use for SDK scripts, automation, and for checking in default admin skills available to each user on the machine.
SYSTEM
Bundled with Codex by OpenAI.
Useful skills relevant to a broad audience such as the skill-creator and plan skills. Available to everyone when they start Codex.
Codex supports symlinked skill folders and follows the symlink target when scanning these locations.
These locations are for authoring and local discovery. When you want to
distribute reusable skills beyond a single repo, or optionally bundle them with
connectors, use plugins.
Distribute skills with plugins
Direct skill folders are best for local authoring and repo-scoped workflows. If
you want to distribute a reusable skill, bundle two or more skills together, or
ship a skill alongside a connector, package them as a
plugin.
Plugins can include one or more skills. They can also optionally bundle
registered MCP server connections, bundled MCP server configuration, and
presentation assets in a single package.
Install curated skills for local use
To add curated skills beyond the built-ins for your own local Codex setup, use $skill-installer. For example, to install the $linear skill:
$skill-installer linear
You can also prompt the installer to download skills from other repositories.
Codex detects newly installed skills automatically; if one doesn’t appear,
restart Codex.
Use this for local setup and experimentation. For reusable distribution of your
own skills, prefer plugins.
Enable or disable local Codex skills
Use [[skills.config]] entries in ~/.codex/config.toml to disable a skill without deleting it:
[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false
Restart Codex after changing ~/.codex/config.toml.
Optional metadata
Add agents/openai.yaml to configure UI metadata in the ChatGPT desktop app, to set invocation policy, and to declare tool dependencies for a more seamless experience with using the skill.
interface:
display_name: "Optional user-facing name"
short_description: "Optional user-facing description"
icon_small: "./assets/small-logo.svg"
icon_large: "./assets/large-logo.png"
brand_color: "#3B82F6"
default_prompt: "Optional surrounding prompt to use the skill with"
policy:
allow_implicit_invocation: false
dependencies:
tools:
- type: "mcp"
value: "openaiDeveloperDocs"
description: "OpenAI Docs MCP server"
transport: "streamable_http"
url: "https://developers.openai.com/mcp"
allow_implicit_invocation (default: true): When false, Codex won’t implicitly invoke the skill based on user prompt; explicit $skill invocation still works.
Best practices
Keep each skill focused on one job.
Prefer instructions over scripts unless you need deterministic behavior or external tooling.
Write imperative steps with explicit inputs and outputs.
Test prompts against the skill description to confirm the right trigger behavior.
For more examples, see
GitHub CI repair,
PDF,
Linear,
openai/skills, and the
agent skills specification. For
installable distribution, prefer plugins.
Next
Site tools (WebMCP)
Ask AI
Docs agent
Loading docs agent...