How to Properly Activate a Claude Code Skill (and Fix One That Won't Trigger)

You properly activate a Claude Code skill by giving it a description with the words users say. Confirm it appears in the skill list, then run /skill-name to prove it loads. A Claude Code skill is an Agent Skill folder with a SKILL.md file that Claude Code loads on demand. Every activation failure breaks one of two paths: Claude matching your request, or you typing the name. This page starts after installation, so set up skills in Claude Code first when no skill folder exists yet.

Sources: Claude Code skills docs and errors reference, and Anthropic's enterprise skills guide, all checked on 2026-10-21.

How do you properly activate a Claude Code skill?

You properly activate a Claude Code skill by giving it a description with the words users say. Confirm it appears in the skill list, then run /skill-name to prove it loads. Measure triggering before you rewrite it.

Anthropic's Claude Code docs list 5 troubleshooting steps for a skill that won't trigger:

1. Put the keywords users say in the description. Lead with the key use case, since the listing caps the combined description at 1,536 characters.
2. Ask Claude "What skills are available?" and confirm the skill appears.
3. Rephrase your request so it matches the description more closely.
4. Invoke the skill directly with /skill-name.
5. Check whether Claude Code refused the skill's name when /skill-name is not recognised.

The reference for every SKILL.md frontmatter field explains description, when_to_use and the invocation fields. For a new skill, our guide shows how to build and test a skill end to end.

Rewrite the description so it matches requests

A matching description states what the skill does and when to use it. Anthropic's best-practices page and its Complete Guide both ask for that pair, written in the third person. Vague descriptions give Claude nothing to match. Compare a vague description with a specific one.

# Before: never triggers on "write a commit message"
description: Helps with git

# After: names the task and the trigger phrases
description: "Writes conventional commit messages. Use when the user asks to commit, write a commit message or open a PR."

The Complete Guide offers a debug prompt for this step. Ask Claude "When would you use the [skill name] skill?" and compare its answer with your intent. Quoting the value protects it once a description contains a colon.

Invoke the skill directly

Direct invocation runs a skill by name at the start of a message, as in /skill-name args. A skill name typed mid-sentence runs nothing. The docs say it only gives Claude permission to use the skill. One message at the terminal prompt stacks up to six skills, per the commands reference.

Force a skill check with a hook

A hook is a command that Claude Code runs on a set event, outside Claude's choices. Scott Spence tested four hook types on Claude Haiku 4.5, with 5 prompts run 10 times each. His simple instruction hook reached 20% activation. His LLM-eval hook reached 80%, and his forced-eval hook reached 84%. Each forced-eval test cost $0.0067 and took 7.2 seconds. He published the results on 2025-11-16. Nobody else has reproduced these figures. The Claude Code docs confirm that skill frontmatter accepts its own hooks field.

Measure how often it triggers

Trigger measurement turns one-off checks into a repeatable rate. The Agent Skills guide on optimizing descriptions uses about 20 queries. Half of them, 8 to 10, are positive requests, and 8 to 10 are near misses. Each query runs 3 times, and a 0.5 trigger rate counts as a pass. The Complete Guide sets a target of 90% of relevant queries. Plugin skills get a tool_used: Skill grader through claude plugin eval.

Check a skill-creator tool's own numbers before you trust them. The trigger-eval measurement validity measure scores 15 in our Skill Creator verdict. At commit 8a1541c, four issue reports in anthropics/skills show its detector at precision 100% and recall 0%. A skill that fires too often needs the opposite fix. Narrow the description, add negative triggers, or set disable-model-invocation: true for manual-only use.

Why is my Claude Code skill not activating?

A Claude Code skill is not activating for one of five reasons. Its description misses your words, it never loaded, or its frontmatter broke. The listing dropped its description, or too many skills compete.

The five causes split into matching problems and loading problems:

1. Description mismatch: Claude finds no overlap between your request and the description. The five activation fixes cover it.
2. Missed load: the folder sits outside a skill location, or the name was refused. See the Unknown command causes.
3. Broken frontmatter: the YAML did not parse, so the description is empty. See the YAML repair steps.
4. Dropped description: the listing budget cut it. See the missing skills checks.
5. Crowded listing: Anthropic's enterprise guide warns "With too many Skills active, Claude may fail to select the right Skill". The Complete Guide flags 20 to 50 enabled skills as a risk.

Two tests from the docs show which half is broken. First, ask Claude "What skills are available?" A listed skill points to a matching problem. Second, type /skill-name. A skill that runs by name loads correctly, so only auto-triggering fails. Simple one-step tasks skip skills by design, per the Agent Skills guide. For skills that pass these checks, see Claude Code skills ranked by verdict.

Why isn't Claude Code finding skills?

Claude Code fails to find a skill for four documented reasons. The folder is in the wrong place, or the name was refused. A nested skill has not loaded yet, or bare mode skipped discovery. Each cause and its fix sit in the Unknown command table below.

Where do you put a skill so Claude Code finds it?

Claude Code finds personal and project skills in two folders. Personal skills live at ~/.claude/skills/<name>/SKILL.md, and project skills live at .claude/skills/<name>/SKILL.md. The setup guide covers both paths in detail.

How does skill triggering work in Claude Code?

Skill triggering in Claude Code works from a listing of every skill's name and description. Claude loads the full SKILL.md only when your request matches a description. Typing /skill-name triggers a skill directly.

The automatic path has four stages. Claude Code lists each skill, Claude matches the request, Claude loads SKILL.md, and the instructions run. The manual path skips matching. Two frontmatter fields change who can trigger a skill:

A skill with disable-model-invocation: true never auto-triggers, because its description never reaches Claude. The paths field narrows triggering further. With paths set, Claude loads the skill automatically only for files that match its glob patterns.

Anthropic's platform docs put the cost of this design at about 100 tokens of metadata per skill. The SKILL.md body stays under 5,000 tokens and loads only on trigger. Our explainer on how Claude decides which skill to load walks through the same model in plain language. The open specification behind the Agent Skills standard uses this split too: metadata first, body on activation.

Why does Claude Code say a skill is unknown or not found?

Claude Code says Unknown command when no loaded skill or command matches the name you typed. Common causes are a typo, a folder outside a skill location, a refused name, or a missing plugin.

The debug log names every refused skill. Start Claude Code with claude --debug, then search the log for [names].

The current errors reference documents Unknown command, not "Unknown skill". The message appears only in interactive terminal sessions. Since v2.1.274, non-interactive sessions send an unmatched /name to Claude with a note instead. These sessions include -p runs, the desktop Code tab, the VS Code chat panel and cloud sessions.

How do you fix malformed YAML frontmatter in SKILL.md?

You fix malformed YAML frontmatter in SKILL.md by starting the file with --- and closing the block. Quote values that contain colons. Then run claude plugin validate to confirm the file parses.

Claude Code reads frontmatter only when --- is the file's first line. Unparsable YAML still loads the skill, but with no fields. So /skill-name works and auto-triggering fails, because Claude has no description to match. Run the validator on personal or project skills, which needs Claude Code v2.1.233 or later:

claude plugin validate ~/.claude/skills
claude plugin validate .claude/skills
claude --debug

The Complete Guide lists the matching upload errors for Claude, such as missing delimiters and unclosed quotes ("Invalid frontmatter"). The fix guide on chion.ai names five failure modes, checked on 2026-10-21:

• Missing closing --- after the fields.
• Text placed before the first ---.
• UTF-8 byte order mark at the start of the file.
• Code fence wrapped around the block.
• Unquoted colon inside a value.

The broken file below fails on the colon after "Use". The fixed file quotes the value.

# Broken: unquoted colon inside the value
---
name: release-notes
description: Drafts release notes. Use: when the user asks for a changelog
---

# Fixed: value quoted
---
name: release-notes
description: "Drafts release notes. Use when the user asks for a changelog."
---

Our field reference lists the frontmatter that must parse with each field's rules. Two Anthropic sources disagree on the filename. The Complete Guide says SKILL.md is case-sensitive. The Help Center article on custom skills writes skill.md. Use SKILL.md in Claude Code, where the docs use that spelling.

Which name and description limits apply?

Five sources set different limits on the name and description fields.

A skill meant for every surface fits the tightest limits. That means 64 characters for the name and 200 for the description.

Why are Claude Code skills not showing up or disappeared?

Claude Code skills stop showing up for five documented reasons. The listing dropped descriptions, skillOverrides turned them off, or Claude Code moved them to .trash. Sync removed them, or bare mode skipped discovery.

1. Check the listing budget. The listing keeps every name but drops descriptions to fit 1% of the context window, least-invoked skills first. Raise skillListingBudgetFraction, set low-priority skills to "name-only", or tune skillListingMaxDescChars.
2. Check skillOverrides. A value of "off" hides the skill from Claude and the / menu. Open /skills and cycle the skill back on.
3. Check ~/.claude/skills/.trash/. Before v2.1.280, a manifest.json bug moved listed folders there. Move each folder back before the 30-day sweep deletes it.
4. Check sync. Synced skills disappear when they are turned off on claude.ai, or when the organization turns Skills off. Setting syncClaudeAiSkills to false removes them too.
5. Check the launch mode. The --bare flag and safe mode skip skill discovery.

Plugin skills carry a namespace, so /skills groups them under their plugin. Users who install the Frontend Design skill through a plugin find it under that group. The setup guide shows how to install and list skills in Claude Code.

Find heavy or unused skills with /skill-doctor

/skill-doctor is a Claude Code command that reports each skill's context cost and usage. It flags listed skills that were never invoked. It needs Claude Code v2.1.252 or later and does not work over Remote Control. Run /doctor for an estimate of the whole listing's cost.

Why does Claude Code ignore a skill's instructions?

Claude Code reads a skill's content once, when it is invoked, and does not re-read the file later. Rules that must always hold belong in a hook. After compaction, only the first 5,000 tokens survive.

The Claude Code docs give three fixes for a skill that loads but fades:

• Hard rules belong in a hook. Claude Code runs the hook on every matching event. The skill's own hooks field keeps the hook with the skill.
• Judgment guidance belongs in standing wording. "Run the tests after every edit" holds across a task, while "Run the tests" reads as one step.
• Compacted skills need a fresh invocation. Re-attached skills share a 25,000-token budget, filled from the most recent first.

The Complete Guide adds two causes: instructions that are too verbose and rules buried low in the file. Put critical rules at the top of SKILL.md. Prefer a script for checks that must never be skipped.

Those fixes cover Claude Code. Two questions remain: the Claude app, and skills that under-trigger by design.

Why are skills not working in the Claude app?

Skills are not working in the Claude app when code execution is off or the skill is toggled off. A vague description is the third common cause. Name the skill in your request to force it.

The Help Center troubleshooting list covers five problems:

Claude's thinking shows whether a skill loaded. Anthropic Academy describes the label as "Reading [skill]", while the Help Center writes "Using [skill name]". Enterprise skill scanning blocks a skill that fails, and nobody can override a fail. If Claude skills seem down, check status.claude.com before any other fix. The app walkthrough shows how to turn on and upload skills in the Claude app.

Which Claude Code skills have known trigger problems?

Some of our verdicts score how reliably a skill triggers. Examples among Claude Code skills include UI/UX Pro Max, Doc Co-Authoring and Claude API, each with documented misses.

The table is sorted by measure score. All 7 skills were reviewed on 2026-09-30.

The last row is the contrast case. A tight description scores 76 on trigger discrimination, with zero false positives in 120 negatives. Our hub lists every verified Claude Code skill, and the methodology explains how we score each measure.

Common questions

Why do skills not stack in claude -p?

Claude Code loads only the first stacked skill in -p mode. Run each skill in its own -p call.

What does "Unknown skill: claude-code-guide" mean?

The name claude-code-guide belongs to a built-in Claude Code subagent, not a skill. The sub-agents doc listed it on 2026-10-20.

Is there a /buddy skill in Claude Code?

No. The Claude Code commands reference listed no /buddy command when checked on 2026-10-21.

Do Claude Code skills hot-reload?

Yes. Claude Code picks up added or edited skills without a restart, except in bare mode.

Does a lower-case skill.md file fail?

Anthropic's sources disagree. The Complete Guide says SKILL.md is case-sensitive, while the Help Center writes skill.md.

Are Claude skills down right now?

Check Anthropic's status page at status.claude.com first. An outage there explains failures that no skill fix solves.