Run /skills in your Claude Code session. If your skill appears in the list, Claude can see it. If it does not appear, you have a file location problem, a frontmatter error, or a character budget issue. Each has a distinct fix. At AEM, diagnosing skill visibility is the first step in every skill audit we run: the four checks below cover every case we have encountered in production skill libraries.

TL;DR: Claude Code discovers skills by reading SKILL.md files in .claude/skills/ at the project or user level. Run /skills to list loaded skills. If yours is missing, one of four causes is responsible: wrong file location, invalid YAML frontmatter, description over the character limit, or total skill budget exceeded. Each has a distinct fix.

How does Claude Code discover skill files?

Claude Code reads SKILL.md files from two locations at session startup: your project's .claude/skills/ directory and your user-level ~/.claude/skills/ directory. Each skill occupies its own named folder inside one of those locations. At startup, only the YAML frontmatter description is loaded into context.

The two locations are:

  • Project-level: .claude/skills/[skill-name]/SKILL.md inside your project directory
  • User-level: ~/.claude/skills/[skill-name]/SKILL.md in your home directory

The folder name becomes the skill's reference identifier. A skill at .claude/skills/code-review/SKILL.md is invocable as /code-review.

This two-phase loading is how Claude Code stays performant with large skill libraries: startup reads only descriptions, which are short; full skill bodies load only when needed (Claude Code documentation, 2025).

If Claude cannot see a skill, the failure is almost always in one of four places: file location, frontmatter validity, description syntax, or total character budget.

What is the fastest way to check skill visibility?

Type /skills in your Claude Code session. This command lists all currently loaded skills and their source locations (project-level vs. user-level). If your skill appears in the list, Claude has found the file and parsed the description successfully. If it does not appear, something in the four-step chain below has failed.

If your skill is missing from the list, check these four things in order:

  1. Is the file in the right location? The SKILL.md file must be inside a named folder inside .claude/skills/. A file at .claude/skills/SKILL.md (no subfolder) is not loaded. A file at .claude/SKILL.md is not loaded. The structure must be .claude/skills/[your-skill-name]/SKILL.md exactly (Claude Code documentation, 2025).
  2. Is the YAML frontmatter valid? The description field must be on a single line. Multi-line descriptions cause YAML parse failures that prevent the skill from loading silently, with no error message and the skill simply absent from the list. The parseFrontmatter() call is wrapped in a bare catch with no warning to the user when a malformed skill is dropped (anthropics/claude-code issue #11322, 2025). Open the file and verify the description is one continuous line, not wrapped or broken by a code formatter.
  3. Is the description within the character limit? The combined description and when_to_use text is capped at 1,536 characters in the skill listing. Anything beyond that is truncated, stripping the trigger keywords Claude needs to match your request (Claude Code documentation, 2025). A separate constraint limits each description to 250 characters in the /skills output itself, so the trigger words that matter most must appear in the first 250 characters of your description field (Claude Code changelog v2.1.86, 2025).
  4. Is the total skill budget exceeded? Claude Code loads skill descriptions into a system prompt character budget that scales at 1% of the context window, with a fallback of 8,000 characters. Once the budget is full, skills added most recently may be silently dropped. Count total description characters across all skills and verify the sum stays within budget (Claude Code documentation, 2025). After context compaction, Claude Code re-attaches invoked skills within a combined budget of 25,000 tokens, keeping the first 5,000 tokens of each skill. Older or less-recently-invoked skills may be dropped entirely if the budget is exceeded (Claude Code documentation, 2025).

What do I do if the file location is correct but the skill still doesn't appear?

Check the YAML frontmatter directly. The two fields Claude Code requires are name and description. The name must match the folder exactly, including case. The description must sit on one line in double quotes. One malformed character in either field silently prevents the skill from loading, with no error logged to the user.

Open the SKILL.md file and verify the frontmatter manually:

---
name: your-skill-name
description: "One-line description that explains what this skill does and when to invoke it."
---

The name field must match the folder name exactly (case-sensitive on macOS/Linux) and is limited to 64 characters, using lowercase letters, numbers, and hyphens only (Claude Code documentation, 2025). The description field must be in double quotes on a single line. Any deviation can cause a silent parse failure.

Common frontmatter errors that silently prevent skill loading:

  • Description wraps to a second line (the most common cause of missing skills — Prettier and other formatters do this automatically)
  • Indented description value
  • Missing closing --- delimiter
  • Colon inside the description value without quoting the entire value

If the frontmatter looks correct and the skill still does not appear, start a new Claude Code session. Skills are loaded at session startup — changes made after a session starts are not reflected until the next session.

What tools help diagnose skill loading issues beyond /skills?

Three diagnostic approaches give you a deeper view when /skills is not enough. Ask Claude to read the file directly to confirm the path exists. Ask Claude to describe each loaded skill to surface parsing gaps. Ask Claude to count description characters to check whether you have hit the system prompt budget.

  1. Read the skill file directly. Ask Claude: "Can you read .claude/skills/code-review/SKILL.md and show me its contents?" If Claude can read the file, it exists and is accessible. If Claude says the file does not exist, the path is wrong.
  2. Ask Claude to describe its loaded skills. Ask: "What skills do you currently have loaded? Please list each by name and describe what each does." This forces Claude to articulate its understanding of each skill, which reveals whether a skill description was parsed correctly or partially.
  3. Check the character count explicitly. In a Claude Code session, ask: "Can you count the total characters in the description fields of all your loaded skills?" If the total approaches the budget ceiling (which scales at 1% of the context window, with a fallback of 8,000 characters), you have a budget problem. The fix is shortening descriptions in the skills you use least frequently (Claude Code documentation, 2025).

For a systematic approach to diagnosing skill failures across all layers, see How Do You Diagnose Whether a Skill Failure Is a Description Problem, Instruction Problem, or Reference Loading Problem.

What if the skill appears in /skills but Claude never uses it?

The skill is visible but not activating. This is a description problem, not a file visibility problem. Claude sees the skill and has decided it is not relevant to the current task. In our AEM skill audits, activation failure is the most common issue we find in libraries that pass all four visibility checks: file fine, description broken.

This is the most common misdiagnosis: developers check file visibility when activation is the real problem. The fix is rewriting the description to be more directive and to explicitly name the trigger conditions.

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

The same principle applies to skill descriptions. A description that reduces Claude's friction in recognizing when to activate the skill gets used. A description that is technically correct but requires inference does not.

For the specific fix, see My Skill Produces Great Output But Never Activates Automatically.

Frequently asked questions

The most common skill visibility failures share a single root cause: a silent parse error drops the skill at load time, leaving no error message. Code formatters, case-sensitive filenames, and duplicate skill names across project and user levels each trigger this silently. The questions below address the specific edge cases that catch most developers.

Why does my skill disappear from /skills after I restart Claude Code?

Most commonly: a code formatter (Prettier, ESLint) is reformatting your SKILL.md file and breaking the description onto multiple lines. In projects with pre-commit hooks that enforce Prettier, skills become invisible to Claude after every commit (anthropics/claude-code issue #9817, 2025). The fix is adding .md files to your formatter's ignore list, or wrapping the frontmatter between <!-- prettier-ignore --> comments. Check the file after each restart to confirm it has not been reformatted.

Can I have two skills with the same name at project-level and user-level?

Yes, but the project-level skill takes precedence. If you have .claude/skills/code-review/SKILL.md at both levels, Claude loads the project-level version. User-level skills load only if no project-level skill of the same name exists. Priority order across all levels is: enterprise > personal > project (Claude Code documentation, 2025).

Does the SKILL.md file name matter, or just the folder name?

The file must be named SKILL.md exactly — uppercase, with the .md extension. A file named skill.md or Skill.md does not load on case-sensitive filesystems. A file named skill-instructions.md is not recognized as a skill file regardless of contents. The official documentation does not explicitly warn about this case-sensitivity requirement, making it a common silent failure on Linux (anthropics/skills issue #314, 2025).

How do I check if a skill is installed at project level vs user level?

The /skills output includes the source path for each skill. Project-level skills show a path starting with your project directory. User-level skills show a path starting with ~/.claude/skills/. If you are unsure which is loading, check the path in the /skills output.

What happens if two skills have descriptions that are nearly identical?

Claude loads both skills successfully. The near-identical descriptions may cause activation ambiguity — Claude may trigger the wrong skill on certain prompts. The fix is distinguishing the descriptions: make each skill's scope, trigger conditions, and exclusions explicit enough that Claude can differentiate them without ambiguity.

Last updated: 2026-04-20