Why a skill fires but ignores its instructions

Four reasons a skill that fired still does nothing

1. 1

   The body is too thin to act on.

   A description good enough to win the selection, followed by two sentences of body, leaves the model to improvise the whole job. The description got the file into the room. The body is the part that says what to do once it is there, and a body of one paragraph is a suggestion rather than a procedure.

2. 2

   The body is too long to hold.

   Everything in the body is read at once, every single run. Past a certain length the five steps you care about are competing for attention with a reference table, a glossary and six worked examples, and the steps are the shortest thing in the file. Length is not the virtue it looks like.

3. 3

   The instructions are preferences, not steps.

   Write "be clear and professional" and there is nothing for the model to check its own output against. Write "three short paragraphs, no bullet lists, sign off with the account name" and there is. If you cannot tell from the result whether an instruction was followed, neither can the thing following it.

4. 4

   allowed-tools names less than the run needs.

   Declaring the key holds the skill to that list instead of letting it inherit whatever the host has open. The list binds both ways though. In a host that grants fewer tools than the list names, the skill can load, appear in the trace, and never fire at all.

Read the trace before you rewrite anything. If the skill appears and the output ignores it, the body is the problem. If the skill appears and the run stops at a tool it was not granted, the frontmatter is. If it never appears, that is a different failure with different causes, covered in why a skill never fires.

Write the body as steps someone could check

The rewrite that fixes this is almost never longer. It is the same length with the adjectives taken out and the order put in.

# status-update/SKILL.md
---
name: status-update
description: Writes a client status update.
---

Write a helpful, professional status update for the client.
Be clear and concise, and cover the important points.

# status-update/SKILL.md
---
name: status-update
description: Outward-facing progress note for one client
  account. Use when the user names a client and asks for an
  update, a check-in, or a status email.
---

1. Ask for the account name if the prompt did not give one.
2. Open with what shipped since the last note, one line each.
3. Name anything that slipped and give the new date. Never
   leave a slip out.
4. Close with what you need from them, or say that nothing
   is needed.
5. Three short paragraphs. No bullet lists in the sent copy.

Every line in the second version is something you can hold the output against afterwards. That is the whole test. Numbered steps also survive a long conversation better than a paragraph does, because they are still legible when only part of the file is being attended to.

Move the reference material out of the body

A body carrying a long table, a glossary and six examples is read in full on every run, and your steps are competing with all of it each time. Put the reference in files beside the skill and let the body name them in one line. It gets read when it is needed instead of always, and the steps stop being the smallest thing on the page.

This is one of the things the free checker measures directly. It compares your body against the length of published skills and tells you which side of the normal range you are on, which is more useful than a guess about whether a file feels long.

Confirm with a prompt, not a reread

A body reads well and is still ignored. The only proof is the prompt you would really type, checked against your own numbered steps one at a time rather than judged as a whole. There is a short guide on testing a skill that covers the should-fire and should-not-fire pairs worth keeping around.

Skills that arrive with their cases already written save you that pass. Every skill in the Agency Owner pack ships with the eval cases it is measured against, and those cases assert what the body produced rather than only that the right file loaded.