YouTip

Agent Skills is Codex's task extension mechanism, which packages instructions, resources, and optional scripts into standardized skill packages, enabling Codex to reliably execute specific workflows. Agent Skills are essentially a folder that must contain a **SKILL.md** file. This file requires at least filling in metadata such as name and description, along with instructions telling the intelligent agent how to complete specific tasks. Skill packages can also integrate scripts, reference materials, templates, and various other resources. my-skill/├── SKILL.md # Required file: metadata + execution instructions├── scripts/ # Optional: executable scripts├── references/ # Optional: reference documents├── assets/ # Optional: templates, various resource files└── ... # Other additional files and directories ### Terminology * **AI agents**: AI intelligent agents (industry standard translation) * **Agent Skills**: Agent Skills (specific concept, keep fixed terminology) * **metadata**: metadata * **workflows**: workflow/execution process * * * ## What are Agent Skills Skills is a reusable workflow authoring format. Each Skill is essentially a directory containing a SKILL.md file, from which Codex reads instructions and executes them step by step. You can think of Skill as a "standard operating procedure" written for Codex—clearly define what to do, when to do it, and how to do it. Codex can then automatically activate it at the appropriate time, or execute it when you explicitly invoke it. > Skills is the "authoring format", while Plugins is the "distribution format". First design the workflow itself using Skills, then package it as a Plugin when you need to distribute it to other developers. Skills can be used in Codex CLI, IDE extensions, and Codex App. You can view or create Skills in the plugin: !(https://example.com/wp-content/uploads/2026/06/tutorial_1780801946031.png) Codex comes with (https://example.com/skills/skills-skill-creator.html). Clicking "Create skill" in the image above will jump to the Skill creation window. We can directly tell it what Skill to create: !(https://example.com/wp-content/uploads/2026/06/tutorial_1780802883227.png) View installed Skills: !(https://example.com/wp-content/uploads/2026/06/xx-tutorial-23sdfjo43r.png) * * * ## How Skills Work Codex uses a Progressive Disclosure mechanism to manage the context window, avoiding loading all skill content at once which would crowd out the prompt space. ### Progressive Loading Process When Codex starts, it only loads each skill's name, description, and file path as an initial list. Only when Codex decides to use a specific skill will it load the complete SKILL.md instruction content. To avoid crowding out the prompt space, the initial skill list is limited to approximately 2% of the model's context window characters, or 8,000 characters when the context window is unknown. If too many skills are installed, Codex will first shorten the description text; if it still exceeds the limit, some skills may not appear in the initial list, and Codex will display a warning. > This budget limit only applies to the initial skill list. After Codex selects a skill, it still reads the complete SKILL.md file for that skill. ### Two Trigger Methods Codex supports two skill activation methods:  #### Explicit Invocation Directly reference the skill in the prompt. In CLI or IDE, use the /skills command or input the $ symbol to specify a skill. When explicitly invoked, Codex doesn't need to do any matching judgment; it directly loads the complete SKILL.md and executes it. #### Implicit Matching When your task description matches a skill's description field, Codex will automatically select that skill. The accuracy of implicit matching depends entirely on the quality of the description field. > When writing the description, place core use cases and trigger keywords at the front. This way, even if the description is shortened, Codex can still match correctly. * * * ## Skill Directory Structure A Skill is a directory containing a SKILL.md file, and can include optional scripts, reference documents, resource files, and metadata configuration. my-skill/├── SKILL.md # Required: usage instructions + metadata├── scripts/ # Optional: executable code├── references/ # Optional: reference documents├── assets/ # Optional: templates, various resources└── agents/ └── openai.yaml The responsibilities of each file/directory are as follows: | File/Directory | Required | Description | | --- | --- | --- | | SKILL.md | Required | The core instruction file for the skill, must contain name and description fields | | scripts/ | Optional | Stores executable code, used for scenarios requiring deterministic behavior or calling external tools | | references/ | Optional | Stores additional reference documents for Codex to consult when executing the skill | | assets/ | Optional | Stores static resource files such as templates and images | | agents/openai.yaml | Optional | Configures UI metadata, invocation strategy, and tool dependency declarations | * * * ## Quick Start: Create Your First Skill It is recommended to use the built-in skill creator to quickly generate a skill framework. ### Using skill-creator Enter the following command in Codex to start the interactive creation process: ## Example # Start the skill creator $skill-creator The creator will ask the following questions in sequence: | Step | Question | Description | | --- | --- | --- | | 1 | What does this skill do? | Define the task the skill will complete | | 2 | When to trigger? | Decide whether to trigger via explicit invocation or implicit matching | | 3 | Pure instructions or includes scripts? | Default recommendation is pure instruction mode, which is concise and easy to maintain | ### Manual Creation You can also manually create the skill directory and SKILL.md file: ## Example --- name: my-skill description: Explain when this skill should and should not be triggered.