You can give a coding agent a folder full of good instructions and still get a surprising result. Ask it to explain a test, and it starts planning a rewrite. Ask it to plan a change, and it edits the code before you've agreed on the approach.

Agent skills make engineering procedures reusable. A skill can explain how to plan a change, investigate a failure, or review a patch. Before any of that guidance can help, though, the agent has to choose an appropriate skill for the request.

That's the part I want to make easier to inspect. We'll build a small planning skill, give it a clear scope, and design a test that checks both which instructions the agent reads and what it does next.

What does the agent see before choosing a skill?

A skill is a directory with a SKILL.md file. Its metadata includes a name and description; the rest of the file contains instructions. Supporting scripts and references can sit alongside it. That's the structure defined by the Agent Skills specification.

The client implementation guide describes progressive disclosure: the client presents a catalog, loads a selected skill's instructions, and retrieves supporting files as needed.

An installed folder, an available catalog entry, and a skill the agent actually reads aren't interchangeable. If a skill isn't appearing, check discovery before rewriting its instructions.

A request is compared with the skill catalog. A relevant skill is loaded, its actions are checked, and unrelated requests continue without it.

Inspect the request, the loaded instructions, and the resulting actions separately. This diagram describes a workflow to check; it doesn't report a measured selection rate.

How do you describe the work a skill owns?

Start with the task, rather than a promise to “help with code.” Here's a deliberately narrow example. Save it in a plan-expiry-change/SKILL.md directory your client discovers:

--- name: plan-expiry-change description: "Plan a token-expiry bug fix before implementation. Use when asked for an implementation plan. Explaining existing code alone is outside this skill." --- # Plan an expiry change  Read the expiry function and its requirements. Identify behavior before, at, and after the expiry timestamp. List the smallest change and the tests that'll verify it. Don't edit source files during a planning-only request. 

The description helps the agent choose. The body tells it how to perform the selected work. Putting every instruction into the description makes the catalog harder to scan without replacing the need to read the procedure.

Notice the boundary: planning doesn't grant implementation authority. A skill should preserve the user's requested scope even when it knows how to do more.

Which prompts make a useful selection test?

Use requests that resemble actual work, including requests with similar vocabulary but different intent. Decide the expected scope before running them.

Request Expected work
“Plan a fix for tokens accepted at their expiry time.” Read the planning skill; produce a plan
“Explain what this expiry comparison does.” Explain the code; no planning procedure needed
“Use plan-expiry-change to plan the fix.” Check explicit invocation separately
“Correct the typo in the expiry documentation.” Make the authorized documentation change

These are proposed test cases, rather than observed model results. Run each in a fresh session against the same repository snapshot. Record the client and model, enabled skills, prompt, and tool trace. Repeat the cases because one response doesn't describe every future response.

The official description guidance is useful when building this prompt set. Keep some realistic wording variations aside while editing, so the final check includes requests you haven't optimized against.

What counts as successful use?

Look for the actual SKILL.md read or the client's equivalent activation event. The agent saying “I'll use the planning skill” isn't enough evidence that it loaded the instructions.

Next, inspect behavior. Did it read the expiry requirement? Did it identify the equality boundary? Did it stop after planning? A selected skill followed by unauthorized source edits fails this workflow even if the proposed fix is correct.

For an explanation-only request, judge the response against that request. Don't require a planning artifact just because your catalog contains a planning skill. Useful selection means bringing in the procedure the work needs without expanding every small request.

Keep these observations in separate columns: selected file, requested scope preserved, required actions completed, final answer correct. That makes a failure easier to diagnose.

What should you change when the wrong skill is chosen?

Start at the first failed step. An absent catalog entry calls for an installation or discovery fix. Overlapping descriptions call for clearer ownership. A loaded skill followed incorrectly calls for examining the instructions and surrounding task context.

Revise one part, rerun the same cases, and compare the results. If a broader description catches more planning requests, check whether it also attracts explanations and typo fixes.

My recommendation is to treat skill selection as a small engineering interface. Give it recognizable inputs, define the work it should initiate, and inspect its effects. That gives you a practical way to improve the skill without guessing which sentence caused the agent's behavior.