Your Agent Skill Is Not Triggering: What to Check First
Separate Skill discovery, selection, loading, and execution. Use a minimal weekly-report example and a documented Claude Code setup to locate the failure.
You created SKILL.md, asked for a weekly report, and received a generic answer. It is tempting to rewrite the instructions immediately. But instructions cannot help if the client never discovered the file, or if the assistant never loaded it.
Check four stages in order: discovery means the client lists the package as available; selection means the assistant chooses it for the request; loading means it reads the full instructions; execution means it follows them while doing the task. A failure at the last stage may look like “not triggering” even though loading worked.
First check the setup your client actually supports
The Agent Skills format requires a Skill folder with SKILL.md, including name and description metadata. It does not mandate one installation directory for every client. The client-integration guide distinguishes discovering a catalog from loading a full file when it is relevant.
For a concrete example, Claude Code's current Skill documentation, checked October 13, 2026, documents project Skills under .claude/skills/<skill-name>/SKILL.md and personal Skills under ~/.claude/skills/<skill-name>/SKILL.md. This article uses those paths only for that client; check your own client's documentation before copying them elsewhere.
An illustrative project file is:
.claude/skills/weekly-report/SKILL.md
With this minimal content:
---
name: weekly-report
description: Draft a weekly status report from supplied work notes. Use when the user asks to summarize completed work, waiting items, and next work for the week.
---
# Weekly report
Ask for notes if none were supplied. Return Completed, Waiting, and Next work sections. Keep plans separate from completed work. Do not invent owners, approvals, dates, or results. Return a draft only. Do not send it.
Inspect the real filename, not just the editor label: SKILL.md.txt is a different file. Check the YAML between the two --- lines, the matching folder and name, and any client-specific flags controlling invocation. A valid format still needs to be in a directory the client scans and accessible to the current session.
Compare an explicit request with an ordinary request
Supply these invented notes: “Budget draft completed. Waiting for Lee's review. Invitations planned after approval; date not agreed.”
First try the client's documented explicit invocation. In Claude Code the sample name can be invoked as /weekly-report, followed by the notes. Then use a fresh session and ask: “Turn these notes into a weekly status report,” without naming the Skill. Inspect the available trace or session information in both runs.
| Observation | Likely next investigation |
|---|---|
| The package is not listed or explicit invocation is unavailable | Installation scope, filename, metadata, client support, and session discovery |
| Explicit invocation loads it, ordinary request does not | Description relevance and selection behavior |
| Full file is read, but output invents an approval | Execution rules and factual checks |
| Full file is read, but a referenced template cannot be opened | Resource path and access, after activation |
These are troubleshooting leads, not a universal diagnosis. Naming a Skill in ordinary prose also does not guarantee that every client will treat it as an explicit invocation.
Make the description match a real task
“Helps with reports” leaves out the kind of report and when to use the package. The sample description names work notes and the weekly status task. Add relevant task wording when it is missing; do not expand it to cover emails, spreadsheets, and every form of writing just to increase activation.
Claude Code also documents settings such as disable-model-invocation that affect automatic selection. Check whether the package intentionally opts out before trying to optimize its description. Keep the underlying reporting rules stable while investigating selection, so you do not mix two changes in one experiment.
Save the client version, installation location, exact request, and observed loading event or error. “The assistant said it used the Skill” is weak evidence; a visible read of the full SKILL.md or a client invocation record is more useful. If no such information is available, mark loading unverified rather than concluding that it succeeded or failed.
Once loading is confirmed, test the report against several inputs. An assistant can load a package and still produce an unsupported result. The installation check ends at access; the output check begins with the facts in your notes.
References
- Agent Skills specification: folder and metadata requirements.
- Adding Skills support: discovery and loading stages.
- Claude Code Skills: client-specific locations, invocation, and invocation controls.
