Fix Claude Skill Not Triggering (2026)

Last updated: April 17, 2026

You typed /tdd or /pdf in a Claude Code session and nothing happened. or Claude responded as if the skill did not exist. This is one of the most-reported issues with Claude skills, and it is almost always a configuration or file-placement problem. This guide walks through every known cause and gives you a fix for each one.

How Skill Invocation Works

When you type /skill-name in Claude Code, the runtime looks for a matching .md file in two locations (checked in this order):

.claude/skills/ inside your current project directory
~/.claude/skills/ in your home directory (global skills)

The filename must match the invocation name exactly. /tdd looks for tdd.md, not TDD.md, not tdd.txt. If the file is found and readable, its YAML front matter and body are loaded into the session context. If not found, the invocation is silently dropped.

There is no automatic context-based triggering in 2026. you must invoke skills explicitly.

Step 1: Confirm the Skill File Exists

Check global skills
ls ~/.claude/skills/
Check project-local skills
ls .claude/skills/ 2>/dev/null || echo "No project-local skills directory"

If the file is missing, install it:

Install globally
cp path/to/tdd.md ~/.claude/skills/tdd.md
Install project-local
mkdir -p .claude/skills/
cp path/to/tdd.md .claude/skills/tdd.md

Step 2: Verify Filename Case and Hyphens

Skill filenames are case-sensitive on Linux and case-preserving on macOS. Hyphens must match exactly.

Invocation	Required filename
`/tdd`	`tdd.md`
`/pdf`	`pdf.md`
`/docx`	`docx.md`
`/supermemory`	`supermemory.md`
`/frontend-design`	`frontend-design.md`

Rename if case is wrong
mv ~/.claude/skills/TDD.md ~/.claude/skills/tdd.md

Step 3: Check File Permissions

Claude Code must be able to read the skill file. Restrictive permissions cause silent failures:

ls -la ~/.claude/skills/
Skill files should show -rw-r--r-- (644) or -rw-rw-r-- (664)
Fix if needed
chmod 644 ~/.claude/skills/*.md
chmod 755 ~/.claude/skills/

Step 4: Validate the YAML Front Matter

A malformed YAML block at the top of the skill file can cause issues. Verify the front matter is valid YAML with only supported fields. Claude Code skills recognize name and description in front matter:

---
name: tdd
description: "Fix Claude skills that fail to trigger automatically. Check invocation syntax, file location, permissions, and YAML frontmatter in under 5 minutes."
---

tools: is not a recognized front matter field and has no effect. Common YAML mistakes:

Missing closing ---
Tabs instead of spaces in the YAML block
Unquoted string values containing colons (e.g., title: Fix: the bug breaks YAML)

Test it:

python3 -c "
import sys
content = open('$HOME/.claude/skills/tdd.md').read()
front = content.split('---')[1]
import yaml; yaml.safe_load(front)
print('YAML OK')
"

Step 5: Confirm You Are in Claude Code CLI

The /skill-name syntax is a Claude Code CLI feature. It does not work on claude.ai in the browser, in the API, or in third-party Claude integrations. Confirm you are running the CLI:

which claude
claude --version

If claude is not found, install it:

npm install -g @anthropic-ai/claude-code

Step 6: Check for CLAUDE.md Auto-Invocation Config

Some workflows configure skills to load automatically via CLAUDE.md. If you expected automatic triggering (not manual /skill-name invocation), you may need to add the skill to your CLAUDE.md:

<!-- CLAUDE.md in project root -->
Project Instructions
Load the following skills at session start:
- /supermemory
- /tdd

Without this, supermemory and tdd skills need explicit invocation every session.

Step 7: Debug With an Explicit Confirmation Prompt

After invoking a skill, immediately ask Claude to confirm it loaded:

/tdd
You have just loaded the tdd skill. Confirm this and summarize its instructions in one sentence.

If the skill loaded, Claude will describe it accurately. If it did not load, Claude will respond generically. which tells you the file was not read.

Step 8: Check for Conflicting Project and Global Skill Names

If you have a tdd.md in both .claude/skills/ and ~/.claude/skills/, the project-local version takes priority. If the project-local version is outdated or broken, the global one never loads.

See both versions
diff .claude/skills/tdd.md ~/.claude/skills/tdd.md 2>/dev/null || echo "Only one version found"

Step 9: Restart the Claude Code Session

Claude Code reads skill files when the session starts, not on every invocation. If you added or modified a skill file while a session was already running, you need to restart:

Exit the current session
exit
Start a new session
claude

Then invoke your skill again.

Checking the pdf and docx Skills Specifically

The pdf skill and docx skills have an additional dependency. the underlying tools they call must be installed. If /pdf triggers but then fails immediately, the skill loaded but its tool dependencies are missing:

Check if pdftotext is available (used by the pdf skill)
which pdftotext || brew install poppler
Check pandoc (used by docx skill)
which pandoc || brew install pandoc

The frontend-design Skill Not Applying Conventions

If the frontend-design skill loads but ignores your project’s design system, the skill file likely lacks project-specific context. The skill itself is generic. you need to customise it:

cat >> ~/.claude/skills/frontend-design.md << 'EOF'
Project Conventions
- Use Tailwind CSS only. no inline styles
- Import components from `@/components/ui/`
- Color tokens defined in `src/tokens/colors.ts`
EOF

Summary Checklist

File exists in ~/.claude/skills/ or .claude/skills/
Filename matches invocation exactly (case-sensitive)
File permissions are 644 or more permissive
YAML front matter is valid (no tabs, closing --- present)
You are using Claude Code CLI, not claude.ai browser
Session was restarted after adding the skill file

Try it: Paste your error into our Error Diagnostic for an instant fix.

This site was built by 5 autonomous agents running in tmux while I was in Bali. 2,500 articles. Zero manual work. 100% quality gate pass rate. The orchestration configs, sprint templates, and quality gates that made that possible are in the Zovo Lifetime bundle. Along with 16 CLAUDE.md templates and 80 tested prompts. **[See how the pipeline works →](https://zovo.one/lifetime?utm_source=ccg&utm_medium=cta-skills&utm_campaign=claude-skill-not-triggering-automatically-troubleshoot)** $99 once. I'm a solo dev in Da Nang. This is how I scale.