Where Does skill.md Live? Install Paths for Claude Code, Codex, Cursor, and More

A lot of skill.md confusion comes from one bad assumption: people think there is one path. There is not.

Depending on what you mean by "where does skill.md live?", you might be asking about three different things:

1. where the file is served on your docs site
2. where the agent discovers it
3. where the agent installs it locally

Those are not the same path, and mixing them together is why so many skill.md explainers feel vague.

This post is the practical answer. If you want examples of what to put in the file, read skill.md Examples. If you want the broader overview of the standard, read our main skill.md guide.

The Short Answer

If you publish a hosted skill.md file, the important locations usually look like this:

1Docs site discovery manifest: /.well-known/skills/index.json
2Docs site skill file:        /.well-known/skills/SKILL.md
3Optional convenience alias:  /skill.md

Then, after an agent installs the skill, it usually ends up in an agent-specific local directory such as:

1Claude Code  -> ~/.claude/skills/<name>/SKILL.md
2Cursor       -> ~/.cursor/skills/<name>/SKILL.md
3Codex        -> ~/.codex/skills/<name>/SKILL.md
4OpenCode     -> ~/.config/opencode/skills/<name>/SKILL.md

That is the basic shape.

Path 1: Where the Skill Lives on Your Docs Site

If you are publishing a hosted skill, the canonical place is the .well-known path:

1/.well-known/skills/index.json
2/.well-known/skills/SKILL.md

The first file is the discovery manifest. The second file is the actual skill content.

This distinction matters because agents and CLIs typically do not start by blindly requesting /skill.md. They start from the manifest, then fetch the referenced file.

A minimal discovery flow looks like this:

11. GET /.well-known/skills/index.json
22. Read the manifest
33. Fetch /.well-known/skills/SKILL.md
44. Install it into a local agent-specific directory

Some sites also expose a convenience alias at /skill.md. That is fine, and it is nice for humans, but it is not the important part of discovery.

If you only remember one thing from this post, remember this: the hosted path that matters is usually the .well-known path, not the friendly alias.

Path 2: Where the Agent Installs It Locally

After discovery, the file usually gets installed into a local skill directory.

That is the second place people mean when they ask where skill.md lives.

Typical local install paths:

1Claude Code  -> ~/.claude/skills/<name>/SKILL.md
2Cursor       -> ~/.cursor/skills/<name>/SKILL.md
3Codex        -> ~/.codex/skills/<name>/SKILL.md
4OpenCode     -> ~/.config/opencode/skills/<name>/SKILL.md

This is the important thing to understand:

• your docs site does not need to serve those local paths
• those directories are created on the user's machine
• the installed file is usually a copy of the hosted skill, not a live mount

That means when someone says "where is the skill.md file for Cursor?" they may not be asking about your docs site at all. They may be asking where the installer dropped it on disk.

Path 3: Repo-Local Skill Directories

There is a third kind of path that shows up in searches: repo-local skill directories.

These are things like:

1.claude/skills/
2.cursor/skills/
3.codex/skills/
4.agents/skills/

This is where things get messy.

Some tools support local, project-scoped skills in addition to user-level installed skills. Some communities also use their own conventions that look similar but are not part of one standard discovery mechanism.

So if you see a query like:

• skill.md location or path
• codex skill.md directory layout
• opencode skills documentation skill.md

the user might be asking about:

• hosted discovery
• installed user-level skills
• repo-local project skills

Those are adjacent concepts, but they are not interchangeable.

When you write docs about skill.md, it helps to separate them explicitly instead of pretending there is one universal answer.

The Discovery Path vs the Install Path

This is the distinction most posts skip.

The discovery path is where the agent finds the skill:

1https://docs.example.com/.well-known/skills/index.json
2https://docs.example.com/.well-known/skills/SKILL.md

The install path is where the agent stores it locally:

1~/.claude/skills/example/SKILL.md
2~/.codex/skills/example/SKILL.md

These do not need to look similar.

In fact, if you are debugging installs, you should usually think in this order:

1. can the agent fetch the .well-known manifest?
2. can it fetch the referenced SKILL.md file?
3. did it write the file into the expected local directory?

If you skip step 1 and jump straight to local filesystem debugging, you can waste a lot of time.

What the Manifest Usually Looks Like

A minimal discovery manifest typically looks something like this:

1{
2  "skills": [
3    {
4      "name": "acme-docs",
5      "description": "Acme documentation for authentication, webhooks, and SDK setup.",
6      "files": ["SKILL.md"]
7    }
8  ]
9}

The point of the manifest is not complexity. It is indirection.

It lets the client discover which skills exist and which files belong to them, instead of hardcoding one path and hoping every site follows the same shape.

That is why "just put skill.md at the root" is not the full story.

What Usually Goes Wrong

Most skill.md path bugs are boring:

• the .well-known manifest is missing
• the manifest exists but points to the wrong file
• the hosted file is named incorrectly
• the local directory is different from what the user assumed
• someone confuses user-level skills with repo-local skills

There is also a softer failure mode: the path works, but the file is so generic that the agent gets no real value from installing it.

That is not a path problem. That is a content problem.

A Better Mental Model

If you need a practical mental model, use this one:

• llms.txt is a curated map of your docs
• skill.md is the agent-facing playbook
• the .well-known manifest is the discovery layer
• the local install directory is just where the client stores the file

Once you separate those layers, the whole standard gets easier to reason about.

The Practical Takeaway

When someone asks "where does skill.md live?", the honest answer is:

which one?

It might live:

• on your docs site under /.well-known/skills/
• as a convenience alias at /skill.md
• in a local agent-specific install directory
• or in a repo-local skills folder, depending on the tool

That sounds messy, but it is manageable once you stop expecting one universal path.

The important thing is to document discovery and installation separately. Most confusion goes away once you do that.

If you want the next layer up, read What Is skill.md? A Practical Guide for Agent-Ready Docs. If you want concrete templates, read skill.md Examples.