Claude Skills Guide

Why Does Claude Code Not Recognize My Custom Skill Name?

You’ve created a custom skill, placed it in the right directory, but when you try to invoke it with /skill-name, Claude Code gives you a confused response. Your skill isn’t loading. This is a common issue with several potential causes. Let’s walk through why this happens and how to fix it.

Where Claude Looks for Skills

Claude Code searches for skills in specific locations depending on your setup. The most common locations are:

If your skill file isn’t in one of these locations, Claude simply won’t find it. The skill must also be in a directory that Claude is configured to scan.

File Naming Matters

The skill filename directly determines the skill name Claude recognizes. If your file is named my-custom-skill.md, you invoke it with /my-custom-skill. However, there are nuances:

The YAML Front Matter Requirement

Every skill file must begin with valid YAML front matter. This metadata tells Claude Code how to handle your skill. Without it, the skill won’t load:

---
name: frontend-design
description: Helps with frontend design decisions and code generation
---

If your front matter is malformed—missing dashes, incorrect indentation, or invalid YAML—Claude skips the entire file. Common mistakes include:

Directory Structure Problems

Claude expects a flat directory structure or a specific organizational pattern. Common issues include:

Nested directories: If you place your skill in ~/.claude/skills/categories/frontend-design.md, you might expect to invoke it as /categories/frontend-design. Instead, Claude flattens the structure or ignores nested files entirely.

Wrong parent directory: Skills must be in the root of the skills directory, not in subfolders (unless your specific setup uses a different configuration).

Skill Name Conflicts

Sometimes your skill exists but gets overshadowed by a built-in skill or another custom skill with the same name. Built-in skills like pdf, pptx, docx, xlsx, tdd, and supermemory take precedence. If you create a skill named pdf expecting it to override the built-in, you may encounter unexpected behavior.

To check for conflicts, list all available skills in your directory:

ls -la ~/.claude/skills/

If you see duplicate names, rename one of them.

Cache and Refresh Issues

Claude Code caches skill metadata. After creating a new skill or making changes, you may need to restart your Claude session or explicitly trigger a refresh. The exact refresh mechanism depends on your interface:

Simply editing the skill file isn’t always enough—Claude needs to re-scan the directory.

Checking for Syntax Errors in Your Skill

Even if the skill loads, syntax errors in the skill body can prevent proper execution. A skill file is essentially a system prompt, so any confusing instructions or broken formatting can cause Claude to ignore or misinterpret the skill.

Validate your skill by:

  1. Keeping the description clear and concise
  2. Avoiding nested bullet points that break YAML parsing
  3. Using consistent formatting throughout

Example: Fixing a Skill That Won’t Load

Let’s say you created ~/.claude/skills/frontend-design.md but /frontend-design doesn’t work. Here’s how to troubleshoot:

  1. Check the file exists: ls ~/.claude/skills/frontend-design.md
  2. Verify front matter: Open the file and ensure it starts with --- and ends with ---
  3. Test the name: Try invoking with the exact filename minus extension
  4. Restart Claude: Close and reopen your session

A working skill file looks like this:

---
name: frontend-design
description: Assists with React components, CSS styling, and design patterns
---
# Frontend Design Skill

You are a frontend design expert. When asked about UI components:

1. Suggest modern CSS solutions before frameworks
2. Recommend accessible HTML patterns
3. Provide working code examples

Always consider performance and browser compatibility.

Special Characters and Encoding

Avoid special characters in skill names. Stick to alphanumeric characters and hyphens. Characters like underscores, ampersands, or parentheses can cause recognition issues in certain environments.

How Claude Loads Skills: Progressive Disclosure

Understanding the loading model helps explain why a skill that “exists” still won’t work. Claude Code uses a three-level progressive disclosure approach:

  1. Level 1 (Metadata): At startup, Claude Code loads only skill names and descriptions.
  2. Level 2 (Full Content): The complete skill guidance loads only when you explicitly request it using get_skill(skill_name).
  3. Level 3 (Resources): Additional files and scripts referenced by the skill are loaded as needed.

This design keeps startup fast while allowing complex, resource-heavy skills to load on demand.

Not Explicitly Calling the Skill

A common misunderstanding: having a skill file in the right place does not automatically activate it for relevant tasks. You must explicitly invoke it:

get_skill("your-skill-name")

Without that call, Claude Code only has access to Level 1 metadata—the name and description—not the full skill guidance. If your skill isn’t running its instructions, this is the most likely cause.

Here’s what an explicit skill invocation looks like in practice:

I need help processing a large CSV file. Let me load the data processing skill first.
get_skill("data-processing")

Now can you help me clean this dataset?

Best Practices for Reliable Skills

Write specific descriptions. The Level 1 description is what Claude Code uses to decide whether a skill is relevant. “Helps with programming” is too broad. “Creates and edits Python scripts for data analysis, including pandas operations and matplotlib visualizations” is specific enough to be useful.

Keep skills focused. Rather than one broad skill, consider breaking it into smaller, focused skills. Focused skills are more discoverable and more reliably invoked.

Document required resources. If your skill depends on external files, scripts, or tools, document these in the skill file with setup instructions and prerequisites.

Test after creating. After writing a skill:

  1. Call get_skill("your-skill-name")
  2. Ask a question relevant to the skill
  3. Verify you get the expected guidance

Additional Debugging Checks

If the steps above haven’t resolved the issue, also check:

Conclusion

If Claude Code doesn’t recognize your custom skill name, systematically check: file location, filename format, front matter validity, directory structure, and potential name conflicts. Most issues stem from these common pitfalls rather than complex configuration problems.

With your skill properly configured, you can invoke it with /skill-name and Claude will respond with your custom guidance. Skills like frontend-design, pdf, tdd, and supermemory demonstrate how powerful well-registered skills can be for specialized tasks.

Built by theluckystrike — More at zovo.one

Explore Our Developer Guides

© 2026 theluckystrike Developer Guides