Claude Code Skill References: When to Move Back to Skill MD

Updated 6 November 2026 · Standard formula, shown below

This article explains when Claude Code skill references should be moved back into a skill’s main markdown file (skill.md) rather than kept as separate reference files. In short, move a reference back into skill.md when the content is short, used by every invocation of the skill, or central to the skill’s core behavior; keep it separate only when it’s lengthy, optional, or used infrequently.

Background: How Claude Code Skills and References Work

Claude Code is Anthropic’s command-line tool for AI-assisted coding. A “skill� is a folder containing a SKILL.md file (often called skill.md) that gives Claude instructions and context for a specific task, plus optional supporting files. Skills are stored in a .claude/skills directory (or a plugin’s skills folder) and are loaded when relevant.

References are separate files inside the skill folder that Claude can read on demand. They are typically used for large datasets, detailed guides, or rarely needed information. The skill.md file itself should contain the core instructions and a summary of what each reference contains, so Claude knows when to read them.

The decision to keep a reference separate or move it back into skill.md is about balancing prompt size, loading speed, and clarity.

When to Move a Reference Back into Skill.md

Consider moving a reference back into the main skill file when any of these apply:

It’s short. If the reference is under a few hundred words, it likely adds little overhead and can be inlined without bloating the prompt.
It’s used in every run. If Claude always needs that information to execute the skill, keeping it separate forces an extra file read every time.
It defines core behavior. If the reference contains rules, steps, or examples that are central to the skill’s purpose, it belongs in skill.md.
It’s rarely changed. Static content that doesn’t need frequent updates is safe to inline.
It’s small enough to fit comfortably in the context window. Claude’s context is limited, but a few KB of text is usually fine.

For example, a skill that formats code might have a reference with style rules. If those rules are 10 bullet points, they should be in skill.md. If they are a 50-page style guide, keep them separate and tell Claude when to read them.

When to Keep a Reference Separate

References should stay separate when:

It’s long. Large files can bloat the prompt and slow down every interaction.
It’s optional. If the information is only needed for specific subtasks, keep it out of the main file.
It’s rarely used. For example, a list of legacy error codes might only be needed for old projects.
It’s structured data. CSV files, JSON schemas, or large tables are better kept as separate files that Claude can query.
It’s versioned or generated. If the reference is auto-generated or updated frequently, keeping it separate avoids editing skill.md every time.

A good rule of thumb: if the content is more than a screen of text and isn’t needed for every invocation, leave it as a reference.

How to Decide: A Simple Checklist

Before moving a reference, ask these questions:

How often does Claude need this information? (Always → inline; sometimes → separate)
How long is it? (Under ~500 words → inline; over ~2000 words → separate)
Is it essential for the skill’s main function? (Yes → inline; no → separate)
Does it change frequently? (No → inline; yes → separate)
Is it structured data? (Yes → separate; no → consider inline)

If most answers point to “inline,� move it back into skill.md. Otherwise, keep it separate and make sure skill.md clearly references it (e.g., “See references/error-codes.md for a full list�).

Common Problems and Misconceptions

One common mistake is leaving a reference separate because “it’s cleaner,� even when Claude reads it every single time. That adds latency and uses context unnecessarily. Another is inlining huge content, which can cause the prompt to exceed limits or degrade performance.

A frequent misconception is that references are automatically loaded. They are not – Claude must be told to read them, usually via a line in skill.md. If you move content back, you must remove the reference instruction, or Claude might still try to read a file that no longer exists.

Also, note that skill.md itself is always loaded when the skill is triggered. So any content there is “always on.� Use that space wisely.

Best Practices for Organizing Skill Content

Keep skill.md focused on the “when� and “how� – trigger conditions, steps, and decision rules.
Use references for “what� – detailed data, examples, or background.
Always include a clear list of references in skill.md with a one-line description of each.
If a reference is used often, consider moving its key points into skill.md and keeping the full version separate.
Review your skills periodically – what was once optional may become essential as the skill evolves.

Frequently Asked Questions

Q: Can I have both a reference and inline content for the same topic?
A: Yes. You can put a short summary in skill.md and point to a detailed reference for edge cases. This is often the best approach.

Q: Does moving a reference back into skill.md affect performance?
A: It can, if the content is large. Inlining increases the prompt size every time the skill runs, which may slow response time. For small content, the impact is negligible.

Q: How do I tell Claude to read a reference?
A: In skill.md, write something like “When the user asks about error codes, read references/error-codes.md.� Claude will then read that file when needed.

Q: What if my skill.md gets too long?
A: If it exceeds a few thousand words, consider moving non-essential sections to references. Aim for skill.md to be a concise guide, not a full manual.

Q: Are there limits on the number of references?
A: No hard limit, but too many references can make the skill hard to maintain and slow to load. Keep only what’s necessary.

Q: Can I use subdirectories in the skill folder?
A: Yes, the skill folder can have subfolders. Just make sure paths in skill.md are relative and correct.

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.