Claude Code Skills Don't Activate Themselves: The Trigger Table Fix

Claude Code reads skill files from .claude/skills/ or .agent/skills/, one folder per skill, each with its own SKILL.md describing what the skill does and when to use it. Cursor has an equivalent. Gemini-based agents have their own version. The convention is everywhere.

What is not everywhere is reliable activation. A skill file sitting in a folder is invisible to the agent unless something in the agent's actual working memory tells it that file is relevant right now. A clear, well-written description at the top of the SKILL.md helps, but in practice it is not enough on its own — the agent still has to decide, mid-conversation, that this particular phrase warrants opening that particular file, and it often decides wrong.

I hit this repeatedly across two different agents: Claude Code and Gemini. Same skill folders, same problem. The agent would answer a question it had already answered for itself in a skill file, just without reading the file.

There are two separate layers here, and conflating them is the source of most of the confusion.

Layer 1 — skill-level description triggering

Anthropic's own skill-creator tooling optimizes the description field inside a SKILL.md so that Claude's internal skill-matching is more likely to fire for the right query. This is a real mechanism, and it helps. It is also probabilistic — it improves the odds, it does not guarantee the file gets opened on a specific phrase every time.

Layer 2 — project-level config activation

This is the layer this article is about. CLAUDE.md, AGENTS.md, .cursorrules, or a system prompt is loaded into context automatically, in full, at the start of every session — not probabilistically, deterministically. Anything written inside that file is an instruction the agent is already holding when it reads the next user message.

A trigger table lives in layer 2. It does not replace layer 1 — a well-described skill file is still worth writing. It closes the gap layer 1 leaves open: the moment-to-moment decision of which file to open for which exact phrase.

The table maps the exact phrases a user types, not abstract task categories, to the exact skill file:

• "write a report" → .agent/skills/report-writer/SKILL.md
• "deploy to prod" → .agent/skills/deploy/SKILL.md
• "check the traffic" → .agent/skills/analytics/SKILL.md

Since the config file is already loaded into context every session, the agent follows the table instead of guessing what exists on disk. There is no separate search step, no retrieval call — it is the same mechanism as any other instruction the agent is holding while it reads your message.

This holds whether it is a single Claude Code session in an IDE or several agent instances passing work between each other in a pipeline. Each instance still needs its own access to the config file — a sub-agent spawned without that file in its context cannot follow a table it never sees. But the logic does not change: map real phrases to real files, put the map where it is guaranteed to load.

More agents in a chain means more places the activation can silently fail, not fewer. A trigger table does not make that risk disappear, but it replaces a probabilistic guess with an explicit, auditable rule at every hop.

I packaged the exact prompt I use, a compatibility table, and working examples for Claude Code and Cursor into a small public repository. No package, no install step — it is a system prompt you hand to your own agent, and it scans your skills folder and writes the trigger table for you.