›_ Codex Issues
Codex Issues / #40458

Windows Desktop App does not discover repository-local skills from $REPO_ROOT/.agents/skills

Open 💬 0 comments Opened Aug 24, 2026 by bernardotb

What version of the Codex App are you using (From “About Codex” dialog)?

26.818.2441.0

What subscription do you have?

ChatGPT Plus

What platform is your computer?

Microsoft Windows NT 10.0.26200.0 x64

What issue are you seeing?

The Codex Desktop App for Windows is not discovering repository-local skills stored in the documented:

$REPO_ROOT/.agents/skills

The repository-local skill directory exists, is readable, the project root is correct and trusted, and all seven SKILL.md files have valid frontmatter with name and description.

However, the native Available skills list contains USER, SYSTEM, and plugin skills, but no REPO-local skills.

Observed skill roots/types:

  • USER: loaded
  • SYSTEM: loaded
  • Plugins: loaded
  • REPO: not loaded / not exposed

The USER skill root is observed under:

%USERPROFILE%\.agents\skills

but there is no corresponding REPO skill root loaded for:

<REPO_ROOT>\.agents\skills

Result:

expected repo-local skills: 7
discovered repo-local skills: 0

No error message is shown. The issue is that the repository-local skill root is silently absent from native skill discovery.

What steps can reproduce the bug?

  1. Open a Git repository in Codex Desktop App for Windows.
  2. Confirm the Desktop App workspace root and current working directory are the Git repository root.
  3. Ensure the project is trusted.
  4. Create:
<REPO_ROOT>/.agents/skills/example-skill/SKILL.md
  1. Add a structurally valid skill:
---
name: example-skill
description: Example repository-local skill used to test Codex skill discovery.
---

# Example Skill

Use this skill when testing repository-local skill discovery.
  1. Restart the Codex Desktop App and open a new session for the repository.
  2. Inspect the native available skills.

Observed result:

example-skill is absent.

USER, SYSTEM, and plugin skills load normally, but the REPO-local skill does not.

In my actual repository, seven valid repository-local skills were tested and 0/7 were discovered.

The runtime CWD and Git root are the same directory, and the project is trusted.

What is the expected behavior?

According to the Codex skills documentation, repository-local skills under:

$REPO_ROOT/.agents/skills

should be discovered by Codex.

A valid repository-local skill should appear in the native available skills after restarting/opening a new Codex session for the repository.

USER, REPO, SYSTEM, and plugin skill roots should all be incorporated when applicable.

Additional information

Validation already performed:

Project root
  • Runtime CWD equals the Git root.
  • The Desktop App workspace root is the expected checkout.
  • .git at the repository root is a real directory.
  • No alternate .git exists between the runtime CWD and that root.
Repository skill directory

<REPO_ROOT>/.agents/skills

  • exists;
  • is a real directory, not a symlink;
  • is readable;
  • contains seven skill directories;
  • contains seven accessible SKILL.md files.
SKILL.md structure

All seven files:

  • are valid UTF-8;
  • have no BOM;
  • begin with YAML frontmatter on line 1;
  • include name;
  • include description;
  • have a folder name matching name;
  • have a Markdown body;
  • passed structural validation.
Configuration

The effective Codex configuration was inspected only for relevant settings.

Observed:

  • repository has trust_level = "trusted";
  • no custom project_root_markers;
  • no [[skills.config]] disabling these skills;
  • no enabled = false entry for them;
  • no path/name override involving these skills.
Restart

The validation was repeated from a new Codex session after the skills were created and corrected.

The repository-local skills were still absent.

Additional observation

There is a separate parent Git repository above this repository in the filesystem.

However:

  • runtime CWD is the inner repository root;
  • git rev-parse --show-toplevel returns the inner repository root;
  • Desktop App workspace points to the inner repository;
  • .agents/skills is directly inside that same CWD.

Therefore this does not appear to explain why the CWD-level .agents/skills directory is skipped.

CLI comparison

An independent Codex CLI installation was not available for comparison.

The only codex executable found was associated with the Desktop App, and direct execution for --help / --version was denied by Windows.

Suspected issue

The repository-local (REPO) skills root appears not to be incorporated by the skill loader in this Codex Desktop App session, while USER, SYSTEM, and plugin roots are loaded normally.

No workaround has been applied.

The skills remain in the documented repository-local location:

$REPO_ROOT/.agents/skills

because copying repository-specific skills into %USERPROFILE%\.agents\skills would make them globally available to unrelated projects.

View original on GitHub ↗