DEV Community

Cover image for How Claude Code and Codex Decide Which Skill Descriptions the Model Reads
Mayur Agnani
Mayur Agnani

Posted on Edited on Originally published at theaicommit.com

How Claude Code and Codex Decide Which Skill Descriptions the Model Reads

Your coding agent lists every skill you install in a small, fixed slice of its memory. When too many skills compete for it, some lose the words that tell the model when to use them, and nothing warns you on screen.

Engineer's view. This is a cache that evicts the least-used entry. A key you just added has the lowest hit count, so it goes first, and it never earns the hits that would keep it. Claude Code trims its skill list the same way. A skill you installed today is the first to lose its description.

TL;DR. A coding agent shows the model only a short list of your skills, and that list has a size limit. Past the limit, descriptions get cut, and a skill the model cannot read about is a skill it rarely picks.

Explain Like I'm 5

A school has one small board by the door. Every club pins a card with its name and what it
does. Kids read the board to decide where to go after lunch.

Then too many clubs sign up. The teacher keeps every name on the board but crosses out the
descriptions of the clubs that got the fewest visitors lately. A brand-new club has had no
visitors yet, so its description is crossed out first.

A kid who loves chess walks past a card that just says "Knights". Nothing tells them it is the
chess club. So the new club stays empty, and its card stays crossed out.

The Problem

You have shipped this bug already, in a system with no model in it.

Your service wrote one log line per request. Someone added a field near the front, and the line
crossed the log shipper's size limit. The shipper did not fail. It cut each line at the limit and
sent the rest. The request ID sat at the end of the line, so searching by request ID stopped
finding anything. No alert fired, because every line still arrived.

The bug was not in any one field. It was a shared size limit, plus a rule for what gets cut when
the limit is hit. Adding something new quietly took words away from something old.

A skill in a coding agent has the same bug. A skill is a folder with a SKILL.md file: a
name, a description, and instructions for one kind of task. Coding agents that support the open
Agent Skills format do not load your skills up front. They show the model
a skill listing: each skill's name and description, and nothing else. The model reads that
listing and decides which skill fits your request.

The listing has a size limit, a fixed share of the context window, the model's working
memory for the session. Install enough skills, and the listing overflows. Each tool then cuts
it by its own rule. A skill whose description was cut can still be listed and still never be
chosen.

The fix: keep the listing under its budget, put each skill's use case in its first sentence
and its name, and check what the model actually sees.

Read the full post on The AI Commit

How Claude Code and Codex Decide Which Skill Descriptions the Model Reads carries the rest: the fix and why it works, the code to change for each role, how to tell it worked, when it is the wrong tool, and an interactive model you can play with.


Originally published at theaicommit.com, a daily AI engineering lab for software engineers. The original has an interactive version you can play with, and the full runnable code is on GitHub.

Top comments (0)