One SKILL.md for Claude Code and Codex: Paths and Startup Cost

One SKILL.md showed up in both Claude Code and Codex when .agents/skills/ held the source and .claude/skills/ pointed to it with a directory symlink. By default, a list of names and descriptions enters context before the body is read; Codex also includes file paths. Longer descriptions increased estimated startup tokens in these tests.

Checked on 2026-11-01 (JST) with Claude Code 2.1.312 and codex-cli 0.163.0 on macOS (Darwin 25.6.0), using a temporary HOME and a temporary repository. Windows, WSL, and remote clones were not tested.

Key points

• Claude Code reads .claude/skills/; Codex reads .agents/skills/. Keep one as the source and symlink the other to use both.
• The startup listing holds name and description, plus file paths in Codex. A logged-out Claude invocation (exit code 1) expanded the body in the transcript. Supporting files were not expanded in this test.
• Keep description within the shared spec's 1,024 characters. Codex shortened the tested 1,025-, 1,500-, and 5,000-character descriptions to 1,024.
• With many skills, both tools kept every name and cut descriptions. The order in which skills lose descriptions was not measured.
• The numbers are /context token estimates, not billed tokens. They describe the startup listing, not every turn.

#Can both tools use the same SKILL.md?

Yes. The SKILL.md format follows the shared Agent Skills specification. Four sharing methods were tested. Claude body expansion was inspected in transcripts from logged-out invocations that exited with code 1; this does not establish a successful model run.

Git recorded A as a symlink (mode 120000), and both CLIs still listed the skill after a local clone. Copies drift, so A is the recommended layout. Whether Codex reads the body during a real turn was not verified, because no logged-in turns were run.

#Where must a skill live to be found?

Sessions were started at the repository root and in a pkg/ subdirectory. ✓ means the skill appeared in Claude's init.skills or Codex's initial input right after startup.

Right after a root start, neither tool listed skills under pkg/. Claude Code's documentation says nested skills are added once Claude works on files in that subdirectory. That delayed discovery was not measured.

#How should the frontmatter be written?

The Agent Skills specification requires two fields.

Claude Code docs treat both as optional. Without name it uses the folder name. Without description it uses the first non-empty line of the body. The missing-description fallback is a Claude Code exception; Codex left skills without a description out of its initial listing.

Eight cases, including a valid control, were placed side by side. Selected results follow.

Claude's init.skills list (the user-facing list) did not include the missing-description and no-frontmatter cases, while /context (the model-facing estimate) did. Results differ by surface. Appearing in a list does not mean a skill conforms to the spec. Even when a CLI fills gaps, keep shared skills within the spec.

---
name: release-notes
description: Drafts release notes from merged PRs. Use when preparing a version tag.
---

Make name match the folder name.

#When are the body and supporting files read?

Official docs describe reading the body when a skill is used. This test confirmed expansion in a logged-out Claude invocation transcript (exit code 1). Two skills shared one description, with 214-character and 20,059-character bodies. Claude's /context estimated both below 20 tokens, with no difference in startup estimates between these two cases.

This observes initial input only; Codex reading a body after skill selection in a real turn remains untested. In Codex's debug prompt-input, neither a plain input nor an input naming $ld-long contained the body or supporting-file markers. Invoking /ld-long in Claude put the body marker into the session transcript but not the supporting-file marker. Because the session was not logged in, the invocation exited with code 1 and there was no model response. How a model chooses to read supporting files was not tested.

#How much context does a description use?

Descriptions were built from ASCII characters at exact lengths.

Codex's shortened text was 1,024 characters including an ellipsis, and the end marker was lost. This is an observation for these versions and inputs, separate from any official overall budget. Claude Code's documentation says the combined description and when_to_use of each entry is cut at 1,536 characters by default.

#Do descriptions get cut when there are many skills?

Yes. Adding 60 skills with 989-character descriptions moved the Skills row in Claude's /context from about 4k to about 9.9k. budget-00 showed ~330, while budget-29, budget-30, and budget-59 fell below 20. All 60 names remained. Codex also kept all 60 names and shortened the budget-00 and budget-59 descriptions to 256 and 252 characters.

Per the documentation, Claude Code's listing budget is 1% of the context window, and on overflow it drops descriptions starting with the least-invoked skills. Codex's initial list defaults to 2% of the context window (8,000 characters when the window is unknown), shortens descriptions first, and may omit skills with a warning if that is not enough. No usage history was created, so frequency-based ordering was not measured.

#How do I share a skill with a symlink?

mkdir -p .agents/skills/probe .claude/skills
# create .agents/skills/probe/SKILL.md
ln -s ../../.agents/skills/probe .claude/skills/probe
git add .agents/skills/probe .claude/skills/probe
git ls-files -s .claude/skills/probe

If the last command prints 120000, Git stored a symlink. Write the target relative to .claude/skills/. Behavior on Windows and other operating systems was not verified.

#How can I check my own setup?

codex debug prompt-input
claude -p /context

The first prints the initial input Codex sends to the model. The second prints Claude Code's estimated context breakdown. In an interactive Claude session, typing /skill-name invokes that skill explicitly.

#What is still unknown?

Not tested: automatic selection accuracy, logged-in real turns, supporting-file selection, billed tokens, plugin and managed-settings environments, and Windows. Effects on search traffic or AI citations were not measured either.

#Related articles and sources

• How Claude Code discovers instruction files
• Using codex exec
• Worktrees with Claude Code and Codex
• AGENTS.md and the Downloads folder
• Reading Claude Code usage
• Claude Code docs: Skills
• Agent Skills specification
• ChatGPT and Codex docs: build skills

#FAQ

#Can Claude Code and Codex share the same SKILL.md?

Yes. With .agents/skills/ as the source and a directory symlink from .claude/skills/, the skill appeared in both Claude Code 2.1.312 and codex-cli 0.163.0. The reverse symlink, a SKILL.md-only symlink, a copy, and a local clone also worked for the listings. Windows and other platforms were not verified.

#Is the description in context on every turn?

Per the official docs, by default, skill names and descriptions enter context first, but a listing budget can omit or shorten descriptions. Codex also includes file paths in its initial list. This test measured the startup listing, not every turn. The figures are token estimates, not billed tokens. In Claude Code, disable-model-invocation: true keeps the description out of context.

#When are the body and supporting files read?

Official docs describe reading the body when a skill is used. This test confirmed expansion in a logged-out Claude invocation transcript (exit code 1). A 20,059-character body did not raise the startup estimate, and invoking /skill-name in Claude put the body into the transcript. Supporting files were not added at that point. How a model chooses supporting files was not verified.

#Are descriptions cut when there are many skills?

Yes. After adding 60 skills with 989-character descriptions, both tools kept every name and shortened some descriptions. Claude Code's documentation says the least-invoked skills lose descriptions first, but frequency ordering was not measured.

#What happens if name or description is missing?

Without name, both tools showed the folder name. Without description, Claude Code used the body's first line, while Codex left the skill out of its initial listing. For shared skills, write both fields as the spec requires.