Why Is Claude Code Not Finding or Loading Your Skill?
Claude Code fails to find or load skills when the CLI cannot discover the SKILL.md entrypoint, parse its YAML metadata, or match the description trigger against your task. When a skill fails silently, Claude Code defaults to generic reasoning rather than applying your custom constraints.
According to the official Anthropic Claude Code documentation, skills are defined by "a SKILL.md file containing YAML frontmatter with name and description fields followed by markdown instructions." When the CLI initializes a session, it parses only top-level skill folders in defined scopes.
| Symptom | Root Cause | CLI Verification | Fix Action |
|---|---|---|---|
| CLI ignores skill completely | Misnamed entrypoint (skill.md vs SKILL.md) or nested subfolder. | ls ~/.claude/skills/[skill-name]/ | Rename to uppercase SKILL.md at root of skill folder. |
| YAML parsing error on launch | Tab characters or unquoted colons in description frontmatter. | head -n 8 SKILL.md | Wrap description in double quotes; replace tabs with 2 spaces. |
| Claude finds skill but acts generic | Frontmatter description is too vague or lacks explicit trigger terms. | Check model intent routing | Rewrite description with concrete input keywords and use conditions. |
| Skill works in repo A but not repo B | Installed in local .claude/skills/ instead of global ~/.claude/skills/. | pwd && ls -d .claude/skills/* | Move to ~/.claude/skills/ or use a synchronized skill library. |
| Referenced template or script fails | Only SKILL.md was copied, leaving supporting assets behind. | tree ~/.claude/skills/[skill-name]/ | Copy entire multi-file folder bundle including subdirectories. |
Claude Code parses only the SKILL.md entrypoint at launch, ignoring subdirectories until the primary skill description is matched to user intent. To understand folder structure, consult our guide on Claude skills across projects and folders.
The Sprawl Moment: When Skills Disappear Between Machines
A software engineer spends four hours on a Friday afternoon perfecting a specialized database migration skill with detailed schema checks and zero-downtime rollback assertions in ~/.claude/skills/db-migrate/SKILL.md on their desktop workstation. The following Tuesday, while troubleshooting an urgent production release issue from their laptop at an airport terminal, they invoke the migration command in Claude Code—only to receive a generic, hallucinated SQL script that misses critical safety checks. The custom skill was never synced to the secondary machine, forcing the engineer to pause the deployment and rewrite instructions from scratch.
Prompttly is a skill manager for AI agents — one library for your skills and prompts that syncs into Claude Code, Codex, ChatGPT, and Claude and is one hotkey away on your Mac, so your setup follows you across every machine, repo, and tool.
Where Should Personal and Project Skills Be Placed?
Personal skills must be placed in ~/.claude/skills/[skill-name]/SKILL.md, while project-specific skills belong in .claude/skills/[skill-name]/SKILL.md at the root of your Git repository. Mixing up these paths causes skills to disappear when you navigate across directories.
Claude Code implements a strict path precedence model:
# 1. Personal Scope (Available in every directory and terminal session)
~/.claude/skills/
└── code-review/
├── SKILL.md
└── rubrics/
└── style-guide.md
# 2. Project Scope (Available ONLY within this Git repository)
/Users/username/projects/my-api/
└── .claude/skills/
└── deploy-staging/
└── SKILL.mdA skill stored in .claude/skills overrides an identical skill name stored in ~/.claude/skills when Claude Code runs inside that specific repository. If you work across multiple projects, read our deep dive on using Claude Skills across projects.
How Do You Diagnose Invalid SKILL.md YAML Frontmatter?
You diagnose invalid frontmatter by inspecting the opening lines of SKILL.md for syntax errors according to the YAML 1.2 Specification. A single unescaped colon or invalid indentation character will cause Claude Code to fail silent parsing of the skill metadata.
YAML frontmatter in SKILL.md requires strict UTF-8 encoding and 2-space indentation without tab characters to prevent silent CLI parser failures. Keep the description field under 1,024 characters to ensure optimal prompt routing and context preservation.
Invalid Frontmatter (Fails to Load)
---
name: pr review
description: Review code: checks diffs,
finds bugs and security issues.
---- • Spaces in name (use kebab-case:
pr-review) - • Unquoted colon in description string
- • Tab character used for indentation
Valid Frontmatter (Loads Correctly)
---
name: pr-review
description: "Review pull requests for security vulnerabilities, race conditions, and test coverage."
---- • Clean alphanumeric kebab-case name under 64 characters
- • Double-quoted description containing clear trigger criteria
- • Standard 2-space indentation compliant with YAML parsers
For complete syntax rules and frontmatter schema options, see our agent skills and SKILL.md guide.
What Causes Skills to Work on One Machine but Break on Another?
Skills break across machines due to missing supporting files, inconsistent home directory paths, or uncommitted local dotfiles. When developers copy only a single SKILL.md file via Slack or email, referenced templates, checklists, or scripts remain trapped on the original machine.
To ensure multi-machine reliability:
- Package Multi-File Folders: If a skill references scripts or rubrics, the entire folder structure must be preserved. Review our guide on multi-file Claude Skills for directory packaging best practices.
- Avoid Hardcoded Absolute Paths: Never write absolute paths like
/Users/alice/.claude/skills/inside instruction text. Use relative paths within the skill folder or standard environment variables. - Set Execution Permissions: If your skill executes local bash scripts via tool calls or the Model Context Protocol (MCP), verify script execution permissions with
chmod +x ./scripts/*.sh.
Prompttly's two-way sync on Mac writes validated skills directly to ~/.claude/skills so that changes propagate instantly across local development environments without manual file transfers.
How Do You Verify and Test Skill Invocation?
You verify skill invocation by running a targeted prompt in Claude Code that explicitly tests your skill's trigger boundaries and output constraints. Testing with generic queries like "help me code" makes it impossible to tell whether the skill loaded or Claude is relying on baseline model capabilities.
# Step 1: Check if skill folder is recognized
ls -la ~/.claude/skills/code-reviewer/SKILL.md
# Step 2: Trigger with explicit intent matching the frontmatter description
claude "Use the code-reviewer skill to audit the unstaged changes in src/auth.ts for JWT expiration edge cases."If Claude Code formats the output with the specific sections, markdown tables, or verification commands specified in your SKILL.md, the skill is active and functioning. If output remains generic, review our walkthrough on how to install and use Claude Skills.
When Should You Rebuild a Skill vs Fixing Its Structure?
You should fix the folder structure and YAML frontmatter when the underlying workflow logic is sound but Claude Code fails to trigger it. You should rebuild the skill from scratch when Claude triggers the skill reliably but repeatedly produces hallucinated outputs, misses critical constraints, or ignores formatting rules.
If your skill has accumulated dozens of contradictory instructions over months of edits, converting the workflow back to a clean template is faster than micro-editing broken markdown. Follow our step-by-step tutorial on how to convert prompts to skills or use the free Claude Skill Creator to generate clean, validated frontmatter.
Frequently Asked Questions
Why is Claude Code not finding or loading my skill?
Claude Code fails to load skills when the skill folder is outside the recognized search paths (~/.claude/skills/ or .claude/skills/), the entrypoint file is not named exactly SKILL.md with uppercase letters, the YAML frontmatter has syntax errors such as tab characters, or file permissions prevent the CLI from reading the directory.
Where does Claude Code look for skill folders?
Claude Code searches two primary filesystem locations: personal skills in ~/.claude/skills/[skill-name]/SKILL.md (accessible globally across all sessions) and project skills in [repo-root]/.claude/skills/[skill-name]/SKILL.md (accessible only when running Claude Code within that specific repository).
How do you fix invalid YAML frontmatter in SKILL.md?
Ensure the frontmatter begins and ends with triple dashes (---) on their own lines, uses standard 2-space indentation with no tabs, encloses descriptions containing colons or quotes in double quotes, and defines the mandatory name and description keys.
Why does a Claude Skill work in one project but fail in another?
A skill stored in a project-scoped folder (.claude/skills/) is isolated to that specific Git repository. To make a skill available across all projects, move the skill folder to ~/.claude/skills/ or manage your skills in a cloud-synced library like Prompttly.
How do you verify that Claude Code has loaded a skill?
Test skill loading by triggering a task that directly matches the skill description or by invoking its designated slash command in the CLI. If Claude Code responds with the specific constraints and output format defined in SKILL.md rather than generic text, the skill loaded successfully.
Related Resources
For additional guidance on building and maintaining robust AI skills, read our guide on Claude skills across projects and directory scopes, review the agent skills and SKILL.md guide, and learn how to sync Claude Skills across multiple computers. To compare tool configurations across ecosystems, check Claude Skills vs Cursor Rules and Codex Skills. Explore more resources from the Prompttly resources hub.
Related Prompt Resources
Fix broken skills and make your library portable
Use Prompttly to manage verified skills, sync instructions across Claude Code and Codex, and access your entire prompt library instantly from any Mac app.