Three checks confirm that Claude loaded your skill content. Run them in this order: check the /skills listing (discovery layer), ask Claude to recite its instructions (body layer), then ask which reference files it has access to (reference layer). Each check catches a different failure mode.

TL;DR: After invoking your skill, ask Claude Code: "Which skills do you have loaded? Tell me the steps you're following for this task. Which reference files have you read?" These three questions expose the three layers where loading fails. Most verification problems trace to one layer, and the fix for each layer is different.

Why Does Verification Matter?

Claude executes what it has in its context window. If your SKILL.md didn't load, Claude improvises. If the SKILL.md body loaded but a reference file didn't, Claude executes the steps without the domain context those steps assumed. Both produce output that looks plausible but misses the specific constraints your skill was built to enforce. Research confirms the underlying vulnerability: accuracy drops by more than 30% when relevant information sits in the middle of a long context rather than at the beginning or end (Nelson Liu et al., "Lost in the Middle," Stanford NLP Group, 2023, ArXiv 2307.03172).

Verification is the fastest way to separate "the skill loaded and Claude is ignoring instructions" from "the skill didn't load and Claude is winging it." These failures look identical from the outside. They require completely different fixes. AEM builds this distinction into the preflight phase of every skill commission.

"When you give a model an explicit output format with examples, consistency goes from ~60% to over 95% in our benchmarks." — Addy Osmani, Engineering Director, Google Chrome (2024)

You can't close that gap if you don't know whether the format instructions loaded in the first place.

How Do I Check Whether My Skill Appears in /skills?

Run /skills in Claude Code. The command lists every skill loaded in the current session by name. If your skill appears, the discovery layer worked: Claude found the SKILL.md file, parsed the frontmatter, and registered the skill. If it's absent, loading failed before the body or reference files were ever reached.

What to look for:

  • Your skill appears in the list by name
  • The skill name matches the name field in your SKILL.md frontmatter exactly
  • No unexpected skills are listed alongside it that share similar descriptions

If your skill is absent from the list, the problem is at the discovery layer: Claude never loaded the SKILL.md file. The most common causes are a wrong folder path, missing or malformed frontmatter, or a name field that wasn't found during parsing. For a full diagnostic of this failure, see Why Does Claude Say "No Skills Found" When I Run /skills?.

If your skill appears in the list but still doesn't behave correctly, the problem is at the body or reference layer. Proceed to Check 2.

How Do I Test Whether the Skill Body Loaded Correctly?

Ask Claude directly: "What are the steps you follow when this skill runs? Summarize your instructions for this task." The answer tells you whether the SKILL.md body reached Claude's context window. A correct, specific recitation confirms the body loaded. A thin or generic response means the body didn't load, or another skill's instructions are overriding yours.

"The single biggest predictor of whether an agent works reliably is whether the instructions are written as a closed spec, not an open suggestion." — Boris Cherny, TypeScript compiler team, Anthropic (2024)

Compare the response against your SKILL.md body. You're looking for:

  • The correct number of steps
  • The right step order
  • Specific constraints or output format rules from your SKILL.md appearing in the recitation
  • Any instructions that are absent, paraphrased, or subtly different from what you wrote

This check exposes two problems:

  1. Problem A: The skill body didn't load fully. If Claude's recitation is thin or generic, the body text wasn't processed. This happens when SKILL.md is unusually long (above 500 lines), when the frontmatter is malformed in a way that prevents body loading, or in rare cases when another skill's instructions are overriding yours.

  2. Problem B: The instructions loaded but are ambiguous. If Claude's recitation is close but not exact, the instructions loaded but they contain enough ambiguity that Claude is interpreting them rather than following them. We include a brief recite-instructions check in the preflight phase of every commission, not to catch loading failures, but because it surfaces ambiguous instruction wording faster than any amount of output testing. An instruction that sounds clear to the author produces a noticeably different recitation from Claude.

The recitation check makes the gap visible immediately. Instruction ambiguity is not a minor issue: across 46 language models tested, performance dropped by up to 61.8% when prompts contained nuanced modifications to the same underlying intent (ArXiv 2512.14754, "Revisiting the Reliability of Language Models in Instruction-Following," 2024).

How Do I Confirm That Reference Files Loaded?

Ask: "Which reference files have you loaded for this skill? What content did you draw from [specific filename]?" Claude names the files it loaded and describes what it used from each. A specific answer with file names and content details confirms the reference layer loaded. A vague answer means the files loaded in name only, not in depth.

If Claude can't name any reference files, and your skill has load instructions pointing to reference files, the load instructions either weren't reached, weren't imperative enough, or the files weren't found at the specified path.

If Claude names the files but its description of their content is vague or incorrect, the files loaded but weren't read deeply enough, the instructions to read them were too passive, or the files were too long for Claude to retain the relevant content through to the step that uses it.

Concrete example of a passing vs failing reference check:

Passing: "I loaded domain-glossary.md at step 2 and used the taxonomy definitions to categorize the input into three tiers."

Failing: "I have access to some reference files for background context."

The failing response tells you the file was mentioned but not read with purpose. The instruction that triggered the load needs to be more specific about what to use from the file.

Adoption data underscores why this matters at scale: roughly 75% of developers now use AI coding tools at least weekly, but developer sentiment toward those tools dropped from over 70% positive in 2023 to 60% in 2025, largely because friction persists even when adoption is high (Stack Overflow Developer Survey, 2025). Skills that load unreliably are a direct source of that friction.

"Developers don't adopt AI tools because they're impressive — they adopt them because they reduce friction on tasks they repeat every day." — Marc Bara, AI product consultant (2024)

For the full architecture of how reference files load, see How Are Reference Files Loaded on Demand?.

What Do I Do When Verification Fails at Each Layer?

Each layer fails in a different way and has a different fix. Discovery failures mean Claude never found the SKILL.md file. Body failures mean the file loaded but wasn't read fully. Reference failures mean the files were mentioned but not read with purpose. Match the failure to the layer before changing anything.

"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)

Discovery layer failure (not in /skills):

  • Check that SKILL.md is in .claude/skills/[skill-name]/SKILL.md
  • Check that the frontmatter is valid YAML with a name field
  • Restart the Claude Code session to force a reload

Body layer failure (recitation is thin or wrong):

  • Check SKILL.md line count. Over 500 lines is a warning sign.
  • Look for frontmatter parsing errors: unclosed quotes, colons inside unquoted strings
  • Check for another skill with a description that overlaps and might be loading instead

Reference layer failure (files not loaded or poorly read):

  • Verify that reference files exist at the paths specified in SKILL.md
  • Change passive references ("see context.md for background") to imperative commands ("Read context.md now")
  • Move load instructions inside the step that uses each file, not at the top of SKILL.md as general orientation

Production data on AI agent reliability reflects the same pattern: 88% of AI agent projects never reach production, and when broken down by root cause, 27% of failures trace directly to data quality and instruction issues rather than model capability (MindStudio, AI Agent Failure Pattern Recognition, 2024). Verification is cheap. Debugging in production is not.

For a systematic approach to checking whether Claude can see your files at all, see How Do I Check If Claude Can See My Skill Files?.

Passing all three checks confirms that content loaded correctly. It does not confirm that the instructions themselves produce correct output for every input. If verification passes but output is still wrong, the problem is in the instructions, not the loading.

What Else Should I Know About Skill Verification?

Verification runs in three layers and each has a distinct failure signature. The /skills listing catches discovery failures. The instruction recitation catches body failures. The reference file query catches load-depth failures. In most sessions, a skill that fails Check 1 never reaches Check 2 or Check 3.

Does the /skills command show reference files or only the skill itself? It shows skills by name, not reference files. To verify reference file loading, use Check 3: ask Claude directly which reference files it loaded and what content it drew from each.

What if Claude recites my instructions correctly but still produces wrong output? The instructions loaded. The problem is execution: something in the context is overriding a step, the step instructions are being interpreted rather than followed, or the input didn't trigger the step where the constraints are defined. Narrow the search to the specific step that produces wrong output.

Can I run these checks before invoking the skill? You can run Check 1 (/skills) before invoking. Checks 2 and 3 require the skill to be active or at least invoked so Claude has the SKILL.md body and reference files in its working context.

My skill shows in /skills but Claude says it doesn't know what the skill does. What happened? The discovery metadata loaded (enough for /skills to show it) but the body didn't. Check for a frontmatter parsing issue that stops body loading, or a SKILL.md file with an empty or very short body below the frontmatter.

How do I verify that Claude followed every step, not just loaded them? After the skill runs, ask: "Walk me through exactly which steps you followed and what you did in each." Compare the walkthrough against SKILL.md step by step. Any step that's absent or condensed in the walkthrough was skipped or abbreviated during execution.

Do I need to verify loading in every session? No. Once a skill passes verification in 3 separate fresh sessions, trust it unless you change SKILL.md, CLAUDE.md, or the reference files. A change to any of these resets the verification requirement for the affected skill.

What's the fastest single-question loading check if I just want a quick sanity test? Ask: "Tell me the steps you'll follow for this task." A correct answer with numbered steps matching your SKILL.md is strong evidence the body loaded. Wrong or missing steps is immediate evidence something failed at the body layer.

Last updated: 2026-04-22