References and assets inside a skill

Put supporting material inside the skill folder and point to it with a path relative to the skill root, such as references/checklist.md. We tested what happens when that path breaks: on Codex, the skill kept answering as if nothing were wrong, and the format validator we used passed the broken folder, because it checks frontmatter, not whether referenced files exist.

How references are supposed to work

The Agent Skills specification says file references should be relative to the skill root, recommends keeping them one level deep from SKILL.md, and treats references/, assets/, and scripts/ as organizational conventions rather than required names. Our explain-error skill uses this pattern: SKILL.md instructs the agent to read references/checklist.md and follow it.

2. Read `references/checklist.md` in this skill folder and follow it.

# Explain-error checklist

When explaining an error or stack trace, work through this checklist:

1. **Name the file and line.** ...
2. **Name the error type.** ...
3. **State the root cause in one sentence.** ...
4. **Suggest exactly one fix.** ...
5. **Do not apply the fix yourself.** ...

Copying only SKILL.md and leaving the reference file behind is a known way to break this. We tested a subtler version: what if the file exists at install time but the path inside SKILL.md stops matching it.

What we broke on purpose

In a separate Codex project (.agents/skills/ scope), we renamed references/checklist.md to references/checklist-moved.md, leaving SKILL.md’s instruction, “Read references/checklist.md”, pointing at a file that no longer existed. We then re-ran the same positive prompt (a pasted traceback) that had worked cleanly before.

What happened: Codex still said it would use the explain-error skill, successfully read SKILL.md, then tried cat .agents/skills/explain-error/references/checklist.md, which failed with No such file or directory, visible in the tool trace. Codex did not surface this to us. It answered anyway, still opening with Checked with explain-error and still giving a correct file, line, cause, and one fix, because those instructions are also stated directly in SKILL.md, and the checklist file mainly restates them.

The broken link failed silently. The trace shows the missing file. The final answer gives no indication anything was missing. Anyone watching only the reply, not the tool trace, would never know the reference was broken.

The format validator didn’t catch it either. We ran npx skills-ref validate against this same broken folder and it still reported Valid skill: .... The validator checks name and description shape; it does not check that a file SKILL.md points to actually exists. Format passing and a broken skill are not mutually exclusive.

Why this matters for scripts too

The same relative-path assumption applies to bundled scripts under scripts/, and it’s easier to get wrong there because a script’s working directory isn’t guaranteed by the Markdown path alone. The official scripts guidance assumes commands run from the skill directory, but says that execution context must be checked in the actual host and installation route. Claude Code documents a ${CLAUDE_SKILL_DIR} substitution specifically so a bundled script can resolve its own location regardless of whether it’s installed at a personal, project, or plugin path; Cursor documents script paths as relative to the skill root; neither convention is something we tested ourselves, and neither should be assumed to carry over to a host that doesn’t document it. A Codex issue reports trouble locating a bundled scripts/ directory, and a separate Codex issue reports a symlink failure; the example symlink in that report appears to point to the wrong relative location, which would explain the failure without it being a loader defect (that’s our reading of the reproduction, not a conclusion the issue itself states), so it’s worth checking the link target before assuming the host is at fault.

What we checked

Format

npx skills-ref validate ./explain-error passed both on the intact skill and on the deliberately broken copy (renamed reference file). The validator checks frontmatter shape only.

Loads, on Codex CLI 0.157.1

The intact skill reads both SKILL.md and references/checklist.md correctly (see how to test an agent skill). With the reference file renamed, the skill still activated and still produced a plausible, checklist-consistent answer, but the reference read itself failed and that failure was not surfaced. We’re recording this as failed for the specific claim “the reference file is actually read and a failure to read it is visible,” not for basic activation, which still worked.

We did not test this on Claude Code or Cursor. Claude Code’s claude -p could not authenticate from our test setup (see what an agent skill is); Cursor was not installed. We also did not test cloud or remote execution surfaces, where Cursor and Claude Code both document that local, unsynced personal skills may not be available at all, a different failure mode from the one above.

What we didn’t check

Broken-reference behavior on Claude Code and Cursor, script working-directory behavior (we tested a Markdown reference, not a bundled script), and any cloud or remote execution surface.

Common problems

Copying SKILL.md without its references is the simplest version of this break, and a common one when installing by hand rather than with a tool. Assuming a passing validator means a working skill is another mistake: it doesn’t check that referenced files exist, only that the frontmatter is shaped correctly. A third is assuming a relative command runs from the skill root. The scripts guidance assumes this but says to verify it per host and installation route; don’t copy a Claude Code path substitution into a Codex or Cursor example without testing it there.

Sources

• Agent Skills specification: file references
• Agent Skills: using scripts
• Claude Code: supporting-file behavior
• Cursor: skill resources