AI how-to notes · 2026-09-28 · docs reviewed 2026-09-28 · 한국어 원문

Claude Code skills not working? Check the file, trigger, and scope

Start with the symptom

You saved a skill, asked Claude to do the job, and got an ordinary answer. Before rewriting the whole file, identify what failed: discovery, selection, or the instructions themselves. Each needs a different check.

This is a reference guide based on official documentation reviewed on September 28, 2026. We have not reproduced these steps in a running Claude Code installation for this article. The examples below are suggested reader checks, with expected criteria rather than recorded outputs.

Keep the original file before changing it. Adjust one thing at a time, then repeat the same request. Otherwise, an improvement will not tell you which change mattered.

Check the file and where it belongs

Project path: .claude/skills/invoice-review/SKILL.md. Personal path: ~/.claude/skills/invoice-review/SKILL.md. These local personal files do not load in Cowork or cloud sessions. See skill locations.

Confirm the actual filename in your editor. A useful check is to copy the complete path into your notes, including the final extension. Also check that the repository you opened is the one containing the file.

The Agent Skills specification defines a skill directory containing SKILL.md, with YAML metadata followed by Markdown instructions. Its portable format requires name and description; the name matches the folder and uses lowercase letters, numbers, and hyphens. Keep both fields even if your particular client accepts less metadata.

The following original example reviews text pasted into chat. Its workflow needs no scripts, external connection, or invoice file. Save the entire block as the project file above.

---
name: invoice-review
description: Review pasted invoice text for missing invoice number, supplier, issue date, currency, and total. Use when asked to check invoice completeness before an internal review. Do not use for general writing.
---

## Task

Review only the invoice text supplied in the conversation.
If no invoice text is supplied, ask the user to paste it.

## Review

List these fields: invoice number, supplier, issue date, currency, total.
For each field, show its supplied value or write "Missing".
Do not invent values or infer currency from an ambiguous symbol.
Finish with the missing fields that need clarification.
Do not claim the invoice is approved for payment.

Here, “complete” means containing five requested fields. It says nothing about whether an invoice is authentic, payable, or compliant with an accounting policy. Decide the intended output before expanding a skill to handle real business decisions.

Check who can invoke it

Other controls keep their defaults. Automatic selection remains request-dependent. See invocation controls.

For this example, leave both controls unset. Do not add tool permissions as an attempt to make the skill easier to discover. First establish that the intended instructions are being selected.

Separate the name from the description

The official extension overview explains that descriptions guide skill selection. Broad, overlapping descriptions can make that choice less reliable. A direct /invoice-review request helps isolate selection from the review instructions.

Use a description that names the input and the job. For our example, “review pasted invoice text for missing fields” gives a clearer boundary than “help with business.” Keep the excluded task specific too: ordinary writing should not produce an invoice checklist.

If you edited the project file but see older instructions, inspect other copies before changing the description again. For equal skill names, managed definitions take priority over personal definitions, and personal definitions over project definitions. Plugin skills have names such as /plugin-name:skill-name. These rules are also covered in the extension overview.

Try two small reader checks

Use separate fresh conversations so earlier instructions do not make the second check appear successful.

Example 1: request the skill explicitly

/invoice-review
Invoice number: INV-104
Supplier: Example Studio
Issue date: 2026-09-28
Total: 120

Look for five fields with currency marked missing. If the response supplies USD or approves payment, record that as a failure of this example's instructions. A neat table alone is not enough.

Example 2: compare relevant and unrelated requests

In one fresh conversation, ask for an invoice completeness check using the same fictional text without the slash command. In another, ask for a one-sentence meeting reminder. Record whether the invoice skill was selected and whether the reminder received an unwanted checklist. Do not infer skill selection solely from a polished answer.

Keep a useful troubleshooting record

Write down the Claude Code version, local or cloud environment, skill path, request, changed setting, and observed response. If it still fails, that short record is more useful than “skills are broken.” The official best practices recommend concrete context and observable verification criteria.

This guide does not guarantee automatic selection or correct results. Use the small checks to decide whether to investigate loading, naming, or instructions next. Recheck current documentation when updating Claude Code.

Sources and scope

• Claude Code skills documentation: locations and invocation controls.
• Agent Skills specification: file format and portable metadata.
• Claude Code extension overview: selection and name priority.
• Claude Code best practices: context and verification.