Where Claude and Codex Skills Are Stored: Install, Verify, and Fix Them

Claude Code stores personal skills under ~/.claude/skills/<skill-name>/SKILL.md and project skills under .claude/skills/<skill-name>/SKILL.md. Codex stores repository skills under .agents/skills/<skill-name>/SKILL.md, user skills under ~/.agents/skills/<skill-name>/SKILL.md, and admin skills under /etc/codex/skills/<skill-name>/SKILL.md. In both tools, a skill is a filesystem package with a SKILL.md entrypoint, not a magic prompt hidden somewhere in the app.

If a skill does not show up, start with the path and folder shape before changing the prompt. Most failures are boring: the file is one directory too high, the frontmatter is malformed, the agent was launched from the wrong working directory, or the current session has not picked up the new folder yet.

The path map

The important detail is the named directory. This is valid:

.agents/
  skills/
    release-check/
      SKILL.md
      scripts/
      references/

This is not a valid skill package:

.agents/
  skills/
    SKILL.md

The agent needs a skill folder first, then the SKILL.md file inside it.

What a valid skill folder looks like

Claude and Codex both use SKILL.md as the entrypoint, but their metadata expectations differ slightly.

For Claude Code, the practical minimum is a SKILL.md file with YAML frontmatter and concise instructions. Claude recommends a description because it uses that text to decide when the skill should load automatically. The directory name becomes the command you type, such as /release-check.

---
description: Checks whether a pull request is ready to release. Use when asked to review release risk, deployment readiness, or rollout notes.
---

Review the current diff, test status, migration changes, and deployment notes.
Return blockers first, then follow-up checks.

For Codex, SKILL.md must include both name and description. Codex starts with each skill's name, description, and file path, then loads the full SKILL.md only when it chooses or is asked to use that skill.

---
name: release-check
description: Review release readiness for a pull request, including tests, migrations, environment changes, and deployment notes.
---

Inspect the diff and summarize:
- release blockers
- risky files
- checks already run
- checks still needed

Supporting files are optional. Use scripts/ when a deterministic command is safer than prose, references/ for longer docs, and assets/ for templates or examples. Keep the main SKILL.md short enough that the agent can understand when to use it without reading a manual.

How Claude decides whether to use a skill

Claude Code can use a skill in two ways: you invoke it directly with /skill-name, or Claude chooses it because the current request matches the skill description. That means the description is not decoration. It is routing metadata.

Good descriptions include the job, the trigger language, and the boundary:

description: Creates a focused frontend QA checklist after UI changes. Use when the user asks to verify layout, accessibility, responsive behavior, screenshots, or visual regressions.

Weak descriptions sound like labels:

description: Frontend helper.

When the description is vague, Claude may never load the skill automatically. When the description is too broad, it may trigger during unrelated work. Treat the description like a compact function signature: specific enough to route, short enough to scan.

Claude watches existing skill directories for file changes. If you edit SKILL.md inside an already watched ~/.claude/skills/ or .claude/skills/ tree, the change can take effect in the current session. If you created the top-level skills directory after launching Claude Code, restart the session so the new directory is watched.

How Codex discovers and invokes skills

Codex discovers skills from repository, user, admin, and system locations. For repository skills, it scans .agents/skills from the current working directory up to the repository root. That makes the launch directory matter:

# Good: launched inside the repo
cd ~/work/my-app
codex

# Risky: launched outside the repo, then asked about files elsewhere
cd ~
codex

Codex can use a skill explicitly when you mention it with $skill-name or select it from the skill UI. It can also invoke a skill implicitly when the task matches the description. If many skills are installed, Codex may shorten descriptions in the initial skill list, so front-load the most important trigger words.

Use the built-in creator for a first pass:

$skill-creator

For curated local skills, Codex also provides:

$skill-installer linear

Codex detects newly installed skills automatically. If a skill still does not appear, restart Codex before rewriting the skill.

Why your skill is not showing up

Use this order. It catches the real failures faster than asking the model to "try harder."

1. Check the exact path.

# Claude Code personal skill
ls ~/.claude/skills/<skill-name>/SKILL.md

# Claude Code project skill
ls .claude/skills/<skill-name>/SKILL.md

# Codex repository skill
ls .agents/skills/<skill-name>/SKILL.md

# Codex user skill
ls ~/.agents/skills/<skill-name>/SKILL.md

1. Check that the manifest is inside a named folder.

The path should end with <skill-name>/SKILL.md, not skills/SKILL.md.

1. Check the frontmatter.

For Codex, verify both name and description exist:

head -n 8 .agents/skills/<skill-name>/SKILL.md

For Claude, make sure the YAML fence is valid and the description says when to use the skill.

1. Check the working directory.

For Codex repository skills, run from inside the repository and confirm the repo root is what you think it is. A skill under another project tree will not be discovered because it exists somewhere on disk.

1. Restart only after the filesystem checks pass.

Claude may need a restart when the top-level skills directory was created after the session began. Codex usually detects new skills, but the official docs still recommend restarting if a newly installed skill does not appear.

Test with a tiny sample skill

Create the smallest possible skill before debugging a full workflow.

For Claude Code:

mkdir -p .claude/skills/hello-skill
cat > .claude/skills/hello-skill/SKILL.md <<'EOF'
---
description: Replies with the exact phrase HELLO_SKILL_OK. Use when testing whether project skills load.
---

Reply with exactly: HELLO_SKILL_OK
EOF

Then ask:

/hello-skill

For Codex:

mkdir -p .agents/skills/hello-skill
cat > .agents/skills/hello-skill/SKILL.md <<'EOF'
---
name: hello-skill
description: Replies with the exact phrase HELLO_SKILL_OK. Use when testing whether repository skills load.
---

Reply with exactly: HELLO_SKILL_OK
EOF

Then ask:

$hello-skill

If the tiny skill works, the skill system is fine and the original skill has a packaging or description problem. If the tiny skill does not work, the issue is discovery: path, launch directory, session refresh, or disabled configuration.

Project-level or personal?

Use project skills when the workflow belongs to the repository:

The mental model: project skills are executable team documentation. Personal skills are your operator shortcuts.

Security note for third-party skills

Read third-party skills before enabling them. A skill can include instructions that ask the agent to run commands, inspect files, call scripts, or use bundled references. Supporting scripts are useful when they make a workflow deterministic, but they are still code entering your agent's operating loop.

Before installing a skill from another repository, check:

• Does SKILL.md ask the agent to read or exfiltrate secrets?
• Do scripts write outside the current project?
• Are network calls documented and necessary?
• Does the skill request broad tool permissions when a narrow workflow would do?
• Is the description scoped, or can it trigger during unrelated tasks?

Treat a shared skill like a small dependency. Review it, pin it if needed, and keep team-owned skills in version control.

Final verification checklist

• The skill path ends in <skill-name>/SKILL.md.
• Claude project skills are under .claude/skills/; Codex project skills are under .agents/skills/.
• Codex SKILL.md frontmatter includes name and description.
• Claude description is specific enough for automatic routing.
• The agent was launched from the repository or working directory that can discover the skill.
• A tiny hello-skill works before you debug the full workflow.
• You restarted the session if the top-level skills directory or Codex config changed.
• Third-party scripts and references were reviewed before use.