Install and use Codex skills: from folder location to first use

Put a skill for your own use across projects in ~/.agents/skills and one shared with your team in the repository's .agents/skills. The tilde means your account's home folder. For example, a personal meeting-note skill would be ~/.agents/skills/meeting-notes/SKILL.md.

Codex checks .agents/skills from the current working folder within a repository up to its root. For a skill needed only in a subservice, place it there and start work from that location. This describes local folder placement; plugin-installed skill files need not be moved there.

You can invoke Codex's built-in $skill-installer to ask about available skills or skills in a repository. This example requests a list before choosing anything to install.

$skill-installer Show me available skills related to organizing documents. Explain what each does and what tools it needs. Do not install anything yet.

For a folder you received directly, check that SKILL.md and reference files are present, then place it in the path for the intended scope. If it needs scripts or external connections, check the publisher's prerequisites. A recognized folder and a ready execution environment are separate checks.

Create a meeting-notes folder and save the following as SKILL.md. This practice example organizes text without running code. In the frontmatter, name identifies the skill and description says when it is useful.

---
name: meeting-notes
description: Use when organizing decisions and follow-up work from meeting notes. Do not use for general document summaries.
---

# Organize meeting notes
1. Read only the provided notes and separate decisions from follow-up work.
2. Include owners and deadlines only when stated in the notes.
3. Mark missing owners or deadlines as undecided.
4. Answer in the order: decisions, action items, questions to check.
5. Compare with the notes to ensure no unsupported conclusions were added.

You can also start by asking Codex: ‘Use $skill-creator to create a personal meeting-note skill.’ Begin with instructions alone; add scripts if repeated calculation or file processing becomes necessary.

In Codex CLI and the IDE extension, use /skills to view the list or type $ to select a skill. Naming it explicitly makes the intended skill clear. Automatic selection depends on the description and request, so start by invoking it explicitly.

$meeting-notes Organize these notes. - Minsu will revise the launch introduction by Wednesday. - The design-review owner is not decided. - The next meeting date was not discussed.

Check that Minsu and Wednesday appear and that the design-review owner and next meeting date were not invented. Preserving the input facts matters more than format alone. Run it again with a different note.

Check the file path, SKILL.md name and the name and description at the top. Codex detects skill changes automatically; if they do not appear, try restarting. Skills with the same name in multiple places are not merged and may appear together in the selection list.

If listed but not automatically selected, name the actual task early in the description. ‘Organize decisions and follow-up work from meeting notes’ communicates scope better than ‘A skill that helps with work.’ If many skills are installed, also look for a list-truncation warning.

Local skills can be disabled in a [[skills.config]] entry in ~/.codex/config.toml. Replace path below with the skill's actual absolute path. If a config file exists, add or edit the entry rather than overwriting the entire file.

[[skills.config]] path = "/Users/my-account/.agents/skills/meeting-notes/SKILL.md" enabled = false

Restart Codex after changing config.toml. To use it again, enable the entry and check the list. For a plugin-bundled skill, also check the plugin management screen.