Skill discovery

Codex scans .agents/skills in every directory from where you launch it up to the repository root, plus ~/.agents/skills (user), /etc/codex/skills (admin), bundled system skills, skills shipped in installed plugins, and the older ~/.codex/skills and project .codex/skills folders. Ordinary host roots discover skill directories up to 6 levels below the root; user/repo/admin roots follow directory symlinks and skip hidden subdirectories. AgentPlugin-format plugin roots accept only direct child skill folders; legacy plugin roots remain recursive. It does not read .claude/skills; the /import command can copy Claude Code skills into .agents/skills.

~/.codex/skills ($CODEX_HOME/skills) still loads but is marked deprecated in favour of ~/.agents/skills.

At 0.162.1 the bundled system skills are imagegen, openai-docs, review-agent, skill-creator and skill-installer; the docs' mention of a plan system skill is out of date.

As of 0.163.0, system roots ignore directory symlinks. Host scans continue below SKILL.md and cap each root at 2,000 directories / 20,000 entries. Executor and cloud skill providers have their own limits.

Claude Code loads <name>/SKILL.md folders from ~/.claude/skills/ (personal), .claude/skills/ in the start directory and every parent up to the repo root (project), nested <subdir>/.claude/skills/ once Claude touches files there, --add-dir directories, enabled plugins' skills/ folders, and an enterprise managed-settings directory; signed-in claude.ai accounts also sync their skills into ~/.claude/skills/synced/. Older .claude/commands/*.md files still work as skills. Other harnesses' folders such as .agents/skills/ are not among its documented locations.

Cowork and cloud sessions (including routines) do not read ~/.claude/skills/; they use skills enabled on your claude.ai account, plus committed project skills in cloud sessions.

Bundled skills ship with Claude Code; turn them off with disableBundledSkills.

Project skills load from .cursor/skills/ and .agents/skills/, user skills from ~/.cursor/skills/ and ~/.agents/skills/, and for compatibility it also reads .claude/skills/, .codex/skills/, ~/.claude/skills/ and ~/.codex/skills/; skills from installed plugins (/plugin, --plugin-dir) load too. Each skill is a folder with a SKILL.md; roots are walked recursively, and .cursor/skills/ or .agents/skills/ folders inside subdirectories of the repo are picked up and scoped to that subdirectory. In CLI 2026.10.12 the scan also reads .grok/skills/, follows symlinks, goes at most 10 levels deep, skips hidden folders plus node_modules, __pycache__, dist and build, and ignores Codex's own system skills (skill-creator, skill-installer, imagegen, openai-docs, plugin-creator) under .codex/skills/.

Built-in Cursor skills (/create-skill, /review, /loop and others) live in ~/.cursor/skills-cursor/ and are managed by Cursor.

Only ~/.cursor/skills/ syncs to Cloud Agents; ~/.agents/skills/ and project skills stay local.

In CLI 2026.10.12, the .claude and .codex folders load only while third-party configuration support is on, which is the default.

OpenCode reads ~/.config/opencode/skills, ~/.claude/skills, ~/.agents/skills, and the project's .opencode/skills, .claude/skills and .agents/skills at every ancestor directory. Each folder can hold <id>/SKILL.md at any depth or flat <id>.md files at its top level. Add more local folders or HTTP catalogs with the skills array in opencode.json. Plugins can register skills too.

The docs say the project walk stops at the project root, but 2.0.28 keeps going up to the filesystem root.

There is no switch to turn off the .claude or .agents folders. The 1.x OPENCODE_DISABLE_*_SKILLS variables are gone.

User skills come from ~/.pi/agent/skills/ and ~/.agents/skills/. Project skills come from .pi/skills/ and from .agents/skills/ in the working directory and each parent up to the git root, and load only after you trust the project. Pi also loads skills from Pi packages, the skills array in settings.json, --skill <path> and extensions. It does not read .claude/skills.

Discovery is recursive and stops at a directory containing SKILL.md. It skips dot-directories and node_modules, and it respects .gitignore, .ignore and .fdignore.

Loose .md files count as skills only at the top level of ~/.pi/agent/skills/, .pi/skills/ and package skills/ directories. In .agents/skills/ they count only inside subfolders. Either way, the file needs a description.

Ordinary host roots scan recursively: a skill folder can be up to 6 directory levels below the root (root = 0). They skip hidden subdirectories and continue below a folder containing SKILL.md. User/repo/admin roots follow directory symlinks; system roots ignore them.

Checked in Codex 0.163.0 source. Each root is capped at 2,000 directories and 20,000 entries, so large trees can be incomplete before reaching the depth limit.

AgentPlugin-format plugin roots accept only <root>/<skill>/SKILL.md; legacy plugin roots scan recursively. The executor root-loader includes hidden directories; cloud and custom providers have separate discovery paths.

Partly

Only skill folders directly inside a skills directory are found (as of 2.1.302). Nested skills are skipped, whether they sit in a plain category folder or under another skill's SKILL.md. Whether hidden folders and symlinks are scanned is unknown.

This applies to both user and project .claude/skills folders: a nested skill appears as soon as its folder is moved up to sit directly inside one.

Plugin skill folders and additional directories may scan differently; that is unknown.

CLI 2026.10.12-d47ca18 scans recursively through skill directories at depth 10 (root = 0). It skips hidden folders, node_modules, __pycache__, dist and build. Directory symlinks are followed, with canonical directory identities deduplicated. Finding SKILL.md does not stop descent.

This describes the CLI; the Cursor editor may behave differently.

Partly

The built-in config skill scanner in v2.1.1 discovers nested SKILL.md files through directory depth 6 (root = 0), accepts loose .md files only at the root, skips hidden and ignored directories, and stops descending when a directory contains SKILL.md. It stats symlinks to classify files/directories. These bounds apply to this filesystem scanner, not arbitrary plugin-provided skills.

OpenCode 1.x scan rules don't carry over to 2.x.

At v2.1.1 the built-in config skill scanner starts at depth 0 and descends through depth 6, skips hidden/ignored directories, and stops below a directory containing SKILL.md. This is the built-in filesystem source, not a bound on every plugin-provided skill.

Scans recursively, but stops descending as soon as it finds an eligible SKILL.md, even if the skill then fails validation. It skips dot entries and node_modules, follows symlinks, and applies .gitignore, .ignore and .fdignore rules.

There is no depth limit on the recursive scan. How symlink cycles are handled is unknown.

No, for recursive host roots. Finding SKILL.md does not stop discovery of nested skills, subject to depth and traversal limits.

Codex 0.163.0 source. AgentPlugin-format roots accept direct child skills only; deeper skills are excluded by that layout rule, regardless of whether a parent manifest exists. Cloud/custom providers are outside this finding.

Partly

Nested skills are never found, even without a parent SKILL.md, so a parent manifest is not what stops discovery.

This applies to both user and project .claude/skills folders: a nested skill appears as soon as its folder is moved up to sit directly inside one.

Plugin skill folders and additional directories may scan differently; that is unknown.

No. The recursive CLI scanner continues into subdirectories after finding SKILL.md, subject to its depth limit and folder exclusions.

This describes Cursor CLI 2026.10.12; the editor may behave differently.

Not documented

Yes for the built-in config filesystem scanner in v2.1.1: once SKILL.md is found in a directory, it records that file and does not descend beneath that directory. Other plugin-provided skill sources are separate.

Whether the scan continues below a folder that is already a skill is unknown.

Yes. An eligible SKILL.md makes the scanner return from that directory, so skills nested beneath it are not independently discovered. This happens even if the parent skill fails validation.

A parent skill can still tell the agent to read nested files; being discovered as a skill and being readable are separate.

The model gets a ## Skills block listing each skill's name, description and SKILL.md path (shortened using a skill-roots table), followed by instructions on when and how to use skills. By default the list may use 2% of the model's context window, or 8,000 characters if the window size is unknown; set skills.max_context_tokens to change this, up to 10,000 tokens.

The budget covers only this initial list. A skill's full SKILL.md is read separately when it is used.

skills.include_instructions = false removes the whole list from the model's context.

Every turn Claude sees a listing of each skill's name plus its description and when_to_use text; the full SKILL.md body is not loaded until the skill is invoked. The listing is capped at 1% of the model's context window (skillListingBudgetFraction, default 0.01, or a fixed character count via SLASH_COMMAND_TOOL_CHAR_BUDGET), and each entry's text is capped at 1,536 characters (skillListingMaxDescChars).

Skills with disable-model-invocation: true or a skillOverrides value of user-invocable-only or off are left out of the listing; name-only lists just the name.

/context shows the listing's size after the budget is applied, and /doctor estimates its cost and biggest contributors.

2.1.301 fixed skill listings disappearing after /rewind.

2.1.304: compaction resends the skill list; /reload-skills sends only new/changed skills, and resumed/cloud plugin reloads avoid repeatedly resending the entire list.

At startup the agent is given the list of available skills with each skill's description and the path to its SKILL.md, and decides from the description when one is relevant. Skills with paths globs, or skills in a nested subdirectory, are listed only while the agent works with matching files. In CLI 2026.10.12 each description is cut to 1,536 characters before it is sent, there is no cap on the number of skills, and the list is ordered built-in, user, project, then plugin skills.

description is required unless the skill sets disable-model-invocation: true; a skill without one is reported as a parse error.

At each model step, OpenCode adds an <available_skills> instruction block listing each skill's id, display name and description, sorted by ID. Paths and bodies are not included. Skills with no description, with opencode/autoinvoke: false or disable-model-invocation: true, or denied by a skill permission rule are left out. No size budget is applied.

Pi adds an <available_skills> block to the system prompt. Each skill gets its name, its full description and its location, which is the absolute path to SKILL.md. The block also tells the model to load a matching skill's file with read (or bash) and to resolve relative paths against the skill directory. There is no size budget for this list.

If neither read nor bash is enabled, the skills block is left out.

Skills with disable-model-invocation: true are left out of the list.

Descriptions longer than 1,024 characters are cut to 1,021 characters plus .... If the list is still over budget, Codex shortens all descriptions evenly; if names and paths alone don't fit, it removes every description and drops skills from the end of the list (system, then admin, then repo, then user skills, alphabetical within each), warning Exceeded skills context budget. All skill descriptions were removed and N additional skills were not included in the model-visible skills list.

No warning is shown when descriptions are only shortened; it appears only when skills are dropped.

A skill dropped from the list can still be invoked by name with $.

Each skill's combined description + when_to_use is cut at 1,536 characters. If the whole listing exceeds its budget, every skill name stays listed but descriptions are dropped starting with the skills you invoke least, and a warning goes to the debug log (claude --debug). Raise skillListingBudgetFraction, set low-priority skills to name-only in skillOverrides, or run /skill-doctor to find unused skills worth turning off.

A skill whose description was dropped can still be invoked by name, but Claude is less likely to pick it on its own.

Partly

Skills are not dropped for being numerous or long, but /skills shows a yellow warning count for skills that break the Agent Skills limits: a name over 64 characters or not lowercase-hyphen, a name that doesn't match the folder, a description over 1,024 characters, or a body over about 5,000 tokens. In CLI 2026.10.12 descriptions sent to the model are silently cut at 1,536 characters, and the / menu skips a SKILL.md larger than 1 MB.

Use paths or nested skill folders to keep file-specific skills out of the list for unrelated work.

Nothing is truncated or dropped. All eligible skills are listed with their full descriptions, and V2 enforces no limit on ID length or description length. When the set changes during a session, only additions and removals are sent, and the full list is resent whenever a skill's name or description changes.

Partly

Pi has no limit on the number of skills and does not truncate descriptions: every skill is listed with its full description. A description over 1024 characters, or a name that breaks the naming rules (more than 64 characters, or anything other than lowercase letters, digits and hyphens), only triggers a startup warning, and the skill still loads. A SKILL.md that has no description or cannot be parsed is not loaded.

Skills with the same name are not merged or overridden; Codex keeps both and both appear in the $ picker and the model's list. A bare $name that matches more than one enabled skill is not auto-loaded, so pick the entry you want from the $ picker, which binds the mention to that skill's path. Plugin skills are prefixed with the plugin name (plugin:skill), so they don't collide with your own skills.

Only exact duplicates of the same SKILL.md path are deduplicated.

A bare $name is also skipped if it matches the slug of a connected app.

Enterprise beats personal, and personal beats project, so with deploy in both ~/.claude/skills/ and .claude/skills/, /deploy runs the personal one. A skill beats a .claude/commands/ file of the same name, and your skill replaces a bundled skill or built-in command of that name (but not its aliases). Plugin skills never collide because they are namespaced as /plugin-name:skill-name; a nested skill that clashes with a root skill stays reachable as /apps/web:deploy, and a synced claude.ai skill that loses its short name runs as /anthropic-skills:<name>.

Partly

The docs require name to match the folder, and a skill's identity is its folder name, not any category folder above it; there is no documented collision rule. In CLI 2026.10.12 the / menu is keyed by folder name: two same-named folders under one root get path-based names (for example shipping-land-it), and across roots the later one wins, so a user-level skill replaces a project skill with the same folder name. The model's list keeps both copies and only drops exact duplicates of the same file (such as the same skill reached through a symlink).

Skills are keyed by an ID taken from the path (the folder name for SKILL.md, the file name for flat .md), not by frontmatter name. The source registered later wins: built-ins, then .claude/skills, then .agents/skills (each global first, then farthest ancestor to nearest), then ~/.config/opencode/skills, then project .opencode/skills, then skills config entries. No warning is shown.

Inside one folder, foo/SKILL.md replaces foo.md because files are processed in sorted order.

Two skills can share a display name if their IDs differ.

The first skill discovered with a name is kept, and Pi shows a collision warning naming the winning and losing paths. Precedence is project settings entries, then project auto-discovered skills (.pi/skills before .agents/skills), then user settings entries, then user auto-discovered skills (~/.pi/agent/skills before ~/.agents/skills), then package skills. If the same file is reached twice through a symlink, it loads once without a warning.

Skill paths passed with --skill are added after the discovered skills, so a discovered skill with the same name wins.

Codex watches the skill folders and picks up new, edited or removed skills automatically, usually within about 10 seconds, so they apply on later turns without a restart. If a change doesn't show up, restart Codex. Edits to ~/.codex/config.toml (such as [[skills.config]]) need a restart.

Skill folders on remote environments are not watched.

Yes. Claude Code watches ~/.claude/skills/, the project .claude/skills/, and .claude/skills/ in --add-dir directories, so added, edited, or removed skills apply in the current session without a restart. If you create a top-level skills directory that didn't exist at startup, run /reload-skills; plugin skills need /reload-plugins or a restart.

File watching is off in bare mode.

A skill already invoked stays in the conversation as it was rendered; Claude Code does not re-read the file on later turns.

2.1.304: compaction resends the skill list; /reload-skills sends only new/changed skills, and resumed/cloud plugin reloads avoid repeatedly resending the entire list.

Partly

Skills are discovered when Cursor starts, so restart cursor-agent (or --resume the chat) to make the agent aware of new or renamed skills. /add-dir and reloading a plugin refresh the / skill menu immediately, but the changelog says to restart when you want the agent to discover new skills automatically; in CLI 2026.10.12 the CLI does not watch skill folders for changes.

Yes. Skill folders are watched, and about 100 ms after an edit settles the skills are rescanned. Config changes also trigger a rescan. On the next model step, the model is told about added or removed skills, or gets a fresh list if a name or description changed. No restart is needed.

v2.1.1 serializes config-skill refreshes, deduplicates directory/file watches and debounces changes by 100 ms before reloading.

Pi does not watch skill files. After you add or edit a skill during a session, run /reload, which reloads skills, extensions, prompt templates, themes and context files without a restart.

To disable a skill, add [[skills.config]] with path = "/path/to/SKILL.md" (or name = "skill-name") and enabled = false to ~/.codex/config.toml, or use /skills then Enable/Disable Skills. A disabled skill is hidden from the model and can't be invoked with $. To hide a skill from the model but keep $ invocation, set policy.allow_implicit_invocation: false in the skill's agents/openai.yaml.

[[skills.config]] is read from your user config and -c overrides, not from a project's .codex/config.toml.

skills.bundled.enabled = false turns off all bundled system skills.

Add disable-model-invocation: true to a skill's frontmatter to remove it from Claude's listing while keeping /name, or user-invocable: false to hide it from the / menu. Without editing the file, set skillOverrides in settings to "name-only", "user-invocable-only", or "off" (the /skills menu writes these to .claude/settings.local.json), or deny the Skill tool or Skill(name) in permissions.

skillOverrides does not affect plugin skills; disable those through /plugin.

disableBundledSkills turns off all bundled skills, and --disable-slash-commands disables all skills for a run.

Set disable-model-invocation: true to keep a skill out of the model's automatic choices so it only runs when you type /skill-name, or user-invocable: false to hide it from / autocomplete and typed /skill-name while the model can still use it. paths globs limit when a skill is surfaced at all; to remove a skill entirely, delete or move its folder or uninstall its plugin.

In CLI 2026.10.12 a skill whose metadata.surfaces list is set but doesn't include cli is hidden from the CLI.

Partly

Set metadata: { opencode/autoinvoke: false } or disable-model-invocation: true to keep a skill out of the model's list; if both are set, opencode/autoinvoke wins. A permissions rule { "action": "skill", "resource": "<id>", "effect": "deny" } hides the skill and blocks the skill tool, globally or under agents.<id>.permissions. None of these stop you from loading it with @id.

Set disable-model-invocation: true in a skill's frontmatter to hide it from the model while keeping /skill:name available. To turn a skill off completely, toggle it in pi config or add an exclusion to the skills setting (!pattern or -path). --no-skills turns off all discovered and configured skills for one run.

enableSkillCommands: false only removes /skill: entries from autocomplete. It does not hide skills from the model or block a typed /skill:name.