Twitter/X

Claude scans only the name and description of installed skills at session start…

2026-05-13 · 16:04 UTC ·@aakashgupta ·2 min read

Brief

Aakash Gupta argues that skill descriptions are the routing logic for Claude: the model reads only names and descriptions when a session starts, so long 700-line skill bodies stay dormant unless the description signals relevance. After 75 tests across 25 skills he recommends detailed, third-person descriptions with trigger phrases, a short failure-rationale table, and two helper skills (/improve-skill, /create-skill).

Why it matters

Claude scans only the name and description of installed skills at session start, leaving the rest of a 700-line skill body unloaded until the model decides the skill is relevant.

Key details

  • A recipe-planner skill described as "Suggest recipes from what's in fridge" failed 10/10 trigger tests; 37 characters of description proved insufficient for routing.
  • Gupta ran 75 tests across 25 skills (15 daily PM skills + 10 edge-case skills), found Claude often skips later steps (self-review step 6 of 7 skipped 4/5 runs), and recommends rich descriptions (three trigger phrases, one boundary), a 'What Claude might think | Why it's wrong' table, plus two helper skills: /improve-skill and /create-skill.
Source evidence

Your skill body is 700 lines of careful instructions and Claude has never read a word of it.

When a session starts, Claude scans the name and description of every installed skill. Nothing else loads. The output template, the read-first table, the worked examples. All of it sits dormant until Claude decides the skill is relevant. That decision happens off the description alone.

The recipe planner skill whose description read "Suggest recipes from what's in fridge" failed 10 out of 10 trigger tests. "What can I make tonight." "Help me use what's in my fridge." "I don't want to grocery shop." All missed. 37 characters isn't enough surface for Claude to route on.

The leverage sits in the description. What it does and when to use it, three trigger phrases a real user would type, one boundary with a pointer to the right skill. Third person, every time.

The description is routing logic. Treat it that way.

Aakash Gupta (@aakashgupta)

Most PMs are still pasting the same 800-word prompt at the top of every Claude session.

The PMs pulling ahead stopped doing that 6 months ago.

Prompts are text you have to remember to paste. Skills are reusable behavior Claude auto-loads the moment your message matches what the skill does. You install once, you stop copy-pasting, and your teammate runs the exact same version you do.

I ran 75 tests across 25 skills last week. 15 PM skills I use daily plus 10 built specifically to surface edge cases. The bad ones failed in patterns that repeated across categories.

Most people think Claude reads their full skill file every time. It doesn't. Claude scans only the name and description of every installed skill, then decides whether to load the rest. A description that reads "Suggest recipes from what's in fridge" stays invisible forever. 37 characters of surface isn't enough for Claude to route on.

The second pattern: Claude takes the shortest path to a response. A self-review pass at step 6 of 7 gets skipped 4 out of 5 runs. Adding "run the self-review pass" again doesn't fix it. Claude already read that instruction and routed around it.

What works: a table that names the rationalization before Claude generates it. "What Claude might think | Why it's wrong." Three rows is usually enough.

The full piece has 10 laws and two skills you can install today:

  • /improve-skill, which generates test prompts against your existing skills, diagnoses where the output breaks down, and rewrites the highest-leverage problem

  • /create-skill, which scaffolds new skills with all 10 laws baked in from the start

Full deep dive for paid subscribers: news.aakashg.com/p/10-laws-c…

— https://nitter.net/aakashgupta/status/2053982150958145934#m