What Is the Difference Between ~/.codex/skills and Project .codex/skills in Codex

When organizing Codex skills, people most often get stuck on two questions:

What is the difference between ~/.codex/skills and project/.codex/skills?
Why does a skill exist in the directory but not appear in the current session?

Here is the short version.

The Difference

The simplest way to remember it:

~/.codex/skills is your global skill library
project/.codex/skills is the local skill library for that repository

`~/.codex/skills`

Use it for:

skills you personally reuse across projects
general workflows that are not tied to a specific repository
workflows that clearly belong to your own habits

For example:

post-rewrite
post-translate
git-commit-push
hugo-rsync-deploy
bilibili-speech-transcriber

The key trait of this kind of skill is: it still makes sense outside the current project.

`project/.codex/skills`

Use it for:

workflows that only apply to this repository
rules tightly coupled to the current project structure, scripts, or templates
skills that should be shared by the team

For example:

a publishing workflow specific to this repository
a generation template that only works in this project
automation steps tightly bound to private project scripts

The key trait of this kind of skill is: it stops being meaningful once it leaves this repository.

When to Use Global and When to Use Project Skills

This rule of thumb is enough:

If it is about your personal habits, put it in ~/.codex/skills
If it is about repository rules, put it in project/.codex/skills
If it can be reused across projects, prefer global
If it should be shared by multiple people and evolve with the repository, prefer project-level

The Current Repository

Based on the current state:

your machine has ~/.codex/skills
this repository does not have .codex/skills

So right now, you mainly rely on global skills.

That means workflows such as post-rewrite, post-translate, and git-commit-push are currently more like part of your personal workflow, not something explicitly bundled with this repository.

Why a Skill Exists on Disk but May Not Appear in the Current Session

There are two different things here:

Existing on disk: the skill file exists in a local directory
Exposed to the session: the current session registered it into the available skill list

These are not the same thing.

So this can happen:

a skill already exists under ~/.codex/skills
but it does not appear in the list after /

This usually does not mean the skill is broken. More often, it means: the current session has not re-indexed it.

How to Make a Skill Available in the Current Session

The practical checklist is short.

1. Put It in the Right Directory

Global:

1

~/.codex/skills/<skill-name>/SKILL.md

Project-level:

1

project/.codex/skills/<skill-name>/SKILL.md

2. Make the `SKILL.md` Header Recognizable

At minimum, it needs:

1
2
3
4


---
name: your-skill-name
description: What this skill does
---

3. Open a New Session After Creating or Editing It

In many cases, a skill does not appear because the current session already fixed its available skill list when it started.

So if you create a skill in the middle of a session, it may already exist on disk, but this session may not recognize it.

The most reliable workflow is:

Put the skill in place
End the current session
Re-enter the project
Open a new session
Check whether it appears under /

4. Put Project Skills in Place Before Starting

If you want project/.codex/skills to be recognized more reliably, put those skills into the project before entering the repository and starting the session.

One Last Line

The shortest conclusion is:

~/.codex/skills is your personal skill library
project/.codex/skills is the repository’s local rule library
a skill existing in the directory does not mean the current session will always show it
the most common fix is to put it in the right directory, write a valid SKILL.md, and then start a new session