| Symptom | Most likely cause | What to change |
|---|---|---|
| The skill never activates, even on the task it was written for. | The description is written in the author's vocabulary, so it does not match how the request is actually phrased. | Rewrite the description with the words a colleague would use, and add the when clause explicitly. Test by asking for the task in someone else's phrasing, not your own. |
| It activates on tasks it has nothing to do with. | The description is broad or generic, so it matches far more than it should. | Narrow the description to the specific artifact or situation. Name the format, the system or the document type instead of the general activity. |
| It loads, but the agent follows only the first part. | The body is long, and the instructions that matter are buried behind background the model does not need. | Cut the background. Move detail into references/ and keep the body to procedure, decision points and the shape of the output. |
| Behaviour changes between sessions with no change to your skill. | Another installed skill instructs the agent on the same decision, and which one wins is not stable. | Check the compatibility map and remove one of the two. Two methodologies for one job is a conflict, not redundancy. |
| Sessions feel heavier since you installed a set of skills. | Every installed skill pays for its metadata at startup, and oversized bodies pay again on activation. | Delete the skills nobody triggers, and split the ones over roughly 500 lines. The cost is per session, so it compounds. |
| It works for you and not for a colleague. | Either the skill is not installed on their side, or it depends on something in your environment that the skill never declares. | State real environment requirements in compatibility, and check whether the skill assumes tools, paths or credentials that only you have. |
| The validator passes but nothing happens at all. | Validation checks the file, not the wiring. The folder name may not match the name field, or the skill may not be in a location the agent loads from. | Confirm the folder name matches name exactly, then confirm the skill is installed where your agent actually reads skills from. |
Why all of this fails silently
A skill that does not match is not an error. From the agent's side, nothing happened: the metadata was read, it did not match the task, and the run continued normally. That is why these problems survive for weeks and why the description is where you should look first, every time.
The order to check things in
Working top down costs minutes. Working bottom up, by rewriting the body first, is how people lose an afternoon.
- Is the skill installed where the agent reads from, and does the folder name match the name field?
- Does the description contain the words someone else would use for this task?
- Does the description say when to use it, not only what it does?
- Is another skill instructing the same decision?
- Is the body short enough that the important part is not buried?