6 Patterns That Make Claude Code Skill Files Actually Activate

A developer on r/ClaudeAI tested 2,300+ community and self-built skill files over three months to figure out why most Claude Code skills never activate. The key finding: many skills sit in ~/.claude/skills/ and never fire because users drop them in without following activation patterns Claude actually uses. Here are the six patterns that determine if a skill loads.

Pattern 1: Specific Trigger Language in the Description

Claude reads the YAML description: field to decide when a skill is relevant. A generic description like "Helps with database stuff" never triggers. A specific one like "Use when configuring database connection pooling, choosing pool sizes, or debugging connection exhaustion" triggers reliably. The description is the skill's discoverability primitive, not flavor text.

Pattern 2: One Capability Per File, Tightly Scoped

A skill covering "all SQL stuff" loses to three separate skills covering writing migrations, fixing injection, and explaining query plans. Claude's matching uses cosine similarity between the user's prompt and each skill's description. Diluted descriptions match weakly; specific ones win.

Pattern 3: Frontmatter Conventions Matter

The fields Claude actually uses: name, description, category, difficulty. Optional but useful: tags. Custom keys are parsed but don't affect activation. Adding random metadata slows nothing but doesn't help.

Pattern 4: When-Not-to-Use Lists

Explicit "do not use this skill when..." lists make activation more accurate, not less. They give Claude negative examples that bound the trigger surface. Skipping this section is the most common mistake in community skills.

Pattern 5: Code Examples That Actually Compile

If a skill has a fenced code block with broken syntax, Claude leans away from the skill on activation because the example contradicts the description. Run every code block through a syntax checker before saving.

Pattern 6: Verification Steps in the Body

Skills that include "after running this, verify by..." sections get higher activation reliability on tasks mid-execution. The verification anchor helps Claude decide "yes, this is the skill that matches what they're trying to do."

Example Skills That Hit All 6 Patterns

• smart-commit — pattern 1 + 6
• connection-pool-setup — pattern 2
• sql-injection-fix — pattern 4
• redis-lua — pattern 5
• error-handling-audit — pattern 6
• api-documentation — pattern 1
• angular-rxjs — pattern 2
• trpc-router — pattern 5
• dockerfile-generator — pattern 4
• infrastructure-as-code — pattern 3
• custom-slash-commands — pattern 1
• placebo-detector — pattern 4

These skills are available at clskillshub.com/browse for reference, or you can write your own using the six patterns.