Reference files load in the order Claude encounters the instructions that tell it to read them. The fix is mechanical: find each load instruction in SKILL.md, move it to the step where that file's content is actually needed, and test in a fresh session. This guide covers the diagnostic and repair process for Claude Code skills built on the AEM skill engineering framework, where load-order bugs are one of the top three reported issues across commissions.

TL;DR: There is no automatic sequencing. Claude reads SKILL.md top to bottom and loads each reference file when it hits the read instruction. If file B loads before file A but your skill needs A first, the load instructions in SKILL.md are in the wrong order. Swap them, make dependencies explicit, and verify in a fresh session.

Why Do Reference Files Load in the Wrong Order?

Claude doesn't scan your skill folder at startup and sequence files by name, size, or relationship. It processes SKILL.md linearly and loads each referenced file at the exact moment it encounters the load instruction. Reference files don't have opinions about when they load. Your instructions do.

The two most common causes:

  1. Cause 1: General setup blocks at the top. Many skill authors write something like "See context.md, persona.md, and rules.md for background" as an opening orientation block. This loads all three files before Claude executes a single step. If persona.md is only needed at step 5, it occupies context from step 0 onward, pushing later step instructions into the middle of the context window where attention is less reliable.
  2. Cause 2: Dependency between reference files. File B contains scoring dimensions that reference terminology defined in file A. The load instructions are written in reverse: Claude loads B first, file A's definitions arrive later, and the skill produces output that misses the relationship.

Instruction position shapes compliance regardless of content quality. Research testing serial position effects across 12 LLMs found that primacy effects dominated in 73 of 104 tested scenarios: instructions placed earlier in context were satisfied more reliably than those placed later (Zhao et al., ACL Findings 2025, ArXiv 2406.15981). A reference file loaded early occupies prime context real estate; a step instruction that arrives later competes with it for attention.

"The failure mode isn't that the model is bad at the task, it's that the task wasn't specified tightly enough. Almost every production failure traces back to an ambiguous instruction." — Simon Willison, creator of Datasette and llm CLI (2024)

Vague "see reference files below" blocks at the top of SKILL.md create exactly this ambiguity about when each file's content is relevant.

How Do I Diagnose the Actual Load Sequence?

Run this three-step check in a fresh Claude Code session before touching SKILL.md. The diagnostic works by asking Claude to narrate its own load sequence after each invoke: what it actually loaded versus what you intended. Skipping this step and editing SKILL.md blind is the single most common reason ordering fixes don't stick on the first attempt.

  1. Step 1: List all load instructions. Search SKILL.md for every reference file mention. Look for "Read [filename]," "See [filename]," "Load [filename]," and "Consult [filename] now." Write them down in the order they appear in the file.
  2. Step 2: Invoke the skill, then ask Claude. After invoking the skill on a standard test input, ask: "Which reference files have you loaded so far and in what order?" This returns the actual sequence, not what you intended.
  3. Step 3: Compare intended vs actual. If Claude names files in a different order than you expected, or loads a file before the step that needs it, the load instructions in SKILL.md don't match your intended sequence.

This diagnostic step matters. In our builds, roughly 60% of "wrong order" reports turn out to be a load instruction positioned 3 to 5 steps too early because it was written during the drafting phase, before the skill's step structure was finalized.

How Do I Fix Ordering Issues in SKILL.md?

Move each load instruction inside the step that actually needs it. Change passive pointers to imperative commands. A passive reference like "see context.md for background" loads the file before any steps run. Replacing it with "Read [context.md] now" at step 1 moves the load to the point where the content changes what Claude produces.

Before (wrong order):

See [persona.md] and [context.md] for background.
These files describe the skill's operating parameters.

## Step 1: Analyze the input
[uses context.md content]

## Step 2: Draft the output
[uses persona.md content]

After (correct order):

## Step 1: Analyze the input
Read [context.md] now. Use the parameters in that file to interpret the input.

## Step 2: Draft the output
Read [persona.md] now. Apply the voice and format rules from that file to the draft.

Three rules for the rewrite:

  1. Position inside the step. Make the read instruction the first line of the step that needs it, not a preamble block before any steps.
  2. Use imperative form. "Read [context.md] now" triggers loading reliably. "See context.md for background" is a passive reference that doesn't reliably fire as a load command. Anthropic's skill authoring best practices document this explicitly: "Write rules in imperative language and be specific" (Anthropic, Agent Skills Best Practices, 2025). The broader evidence supports the principle: explicit instructions with examples push consistency from roughly 60% to over 95% in controlled benchmarks (Addy Osmani, Engineering Director, Google Chrome, 2024).
  3. Load once. If two consecutive steps need the same file, load it at the first step. Loading the same file twice wastes tokens without benefit.

How Do I Fix Dependencies Between Reference Files?

If file B assumes content from file A, name the dependency explicitly in the load instruction for file B. Claude processes each instruction as it appears in SKILL.md. Without an explicit dependency note, it has no mechanism to infer that eval-framework.md requires domain-glossary.md to be loaded first. The note is what enforces the order:

## Step 2: Establish domain context
Read [domain-glossary.md]. This file defines all terminology used in subsequent steps.

## Step 3: Apply scoring framework
Read [eval-framework.md]. The scoring dimensions reference terms from domain-glossary.md,
so load that file before this one.

The second instruction names the dependency. Claude reads A before B, in the order the instructions prescribe. "This file references terms from X" is enough for Claude to respect the sequencing requirement.

We've seen the dependency fix resolve wrong-order behavior in 3 of 4 commissions where clients reported reference files "ignoring each other." In each case, the skill's SKILL.md had separate load instructions written at different times, with no dependency note connecting them.

For the deeper architecture behind why this works, see How Are Reference Files Loaded on Demand?.

What Happens When Files Load Too Early?

Loading a reference file before its content is needed costs tokens without return. If context.md is 200 lines and the skill has 8 steps, loading at step 0 means those tokens sit in context from the beginning. By step 7, earlier context receives less attention.

The documented effect: multi-document QA performance dropped by more than 20% when relevant information shifted from first or last position to the middle of the context window (Nelson Liu et al., Stanford NLP Group, "Lost in the Middle," ArXiv 2307.03172, 2023). Loading reference files earlier than needed pushes step instructions toward the middle while reference content occupies prime early-context space.

This degradation is not model-specific. A 2025 study testing 18 frontier models including Claude 4, GPT-4.1, and Gemini 2.5 found that every model showed "significantly higher performance on focused prompts compared to full prompts," with Claude models showing the most pronounced gap (Hong, Kelly et al., "Context Rot," Chroma Technical Report, July 2025). Unnecessary early loads are not free. They degrade the same models you're trying to use reliably.

The practical rule: load late, not early. Load each reference file at the step where it changes what Claude does, not at the start of the skill as general orientation.

This pattern works for single-domain skills where each reference file is relevant to exactly one phase. For skills where multiple reference files must be active simultaneously throughout all steps, load them all at step 1 and accept the token cost as the price of persistent context.

How Do I Confirm the Fix Worked?

Always test in a fresh session. The session where you wrote the skill holds context about the reference file structure that a fresh session does not. Testing in the same session masks ordering problems. A fresh session replicates real-user conditions: no carry-over context, no prior knowledge of which files exist, no loaded content that papers over a missing instruction.

Verification sequence:

  1. Start a fresh Claude Code session
  2. Invoke the skill on a standard test input
  3. After each step, ask: "Which reference files have you loaded?"
  4. Confirm the narrated sequence matches your intended order

If Claude reports loading a file before the step that should trigger it, the load instruction still appears too early in SKILL.md. Repeat the repositioning.

Iterative context refinement based on observed behavior produces measurable gains. Research treating agent contexts as evolving, modular systems showed +10.6% improvement on agent benchmarks and +8.6% on domain-specific tasks compared to static context configurations (He et al., "Agentic Context Engineering," ArXiv 2510.04618, 2025). The fresh-session test is your version of that feedback loop: observe what actually loaded, reposition what loaded too early, test again.

For broader guidance on testing across sessions, see Why Does My Skill Work in One Session but Fail in Another?.

FAQ

What controls reference file load order in Claude Code skills? Load order is controlled by where read instructions appear in the SKILL.md body. Claude processes instructions top to bottom and loads each reference file when it encounters the instruction to read it. There is no ordering by filename, file size, or relationship between files.

Can I tell Claude to load multiple reference files at once? Yes. "Read [file-a.md] and [file-b.md] before proceeding" loads both at that instruction point. If order between the two matters, use separate instructions with a dependency note on the second: "Read [file-b.md]. This file references content from file-a.md, which you loaded in the previous step."

What's the difference between mentioning a filename and a load instruction? Mentioning a filename doesn't load it. The instruction must be imperative: "Read [filename]," "Load [filename]," or "Consult [filename] now." Passive references like "see the reference folder for background" do not trigger loading reliably.

Does the filename or folder structure affect load order? No. Claude doesn't sort reference files alphabetically or by folder position. Only the position of the read instruction in SKILL.md determines when a file loads.

How do I debug a skill where two reference files seem to ignore each other? Ask Claude: "What content did you take from [filename] when executing step 3?" If the answer is thin, either the file loaded after it was needed, or the instructions didn't make the dependency between files explicit. Reposition the load instruction and add a dependency note.

Should every step in my skill have its own reference file? Not necessarily. A reference file earns its load at the step where its content changes what Claude produces. If two consecutive steps both need the same file, load once at the first step. One reference file per phase is a reasonable default for most skills.

My skill has six reference files and they're all loading at step 1. Is that a problem? It depends on whether all six are needed from step 1 onward. If yes, the token cost is the price of the design. If some files are only needed later, move their load instructions to the steps that need them. Loading all reference files at startup is the most common cause of context bloat in multi-reference skills.

Last updated: 2026-04-22