Diagnosing Skills

By the Syncfusion DevTutorials team · Last updated October 22, 2026

Find why a skill does not work: the six layers every request passes through, how to find the first broken one, skills that fire for the wrong request, and changing one thing at a time.

Every Skill Goes Through Six Layers

Diagnosing a skill = finding out why it does not work. In this lesson, you will learn the six layers every skill passes through. You will also learn to find the broken one and fix only that.

A skill can look perfect and still fail.

That is because every request passes through six layers.

If one layer breaks, the whole skill fails.

The six layers are:

• Discovery: the agent can see the skill.
• Activation: the agent picks the skill.
• Instructions: the agent follows its steps.
• Resources: the agent opens extra files when needed.
• Verification: the result is checked.
• Improvement: the skill gets better from real use.

Simple lesson: when a skill does not work, find the first weak layer. Fix only that layer.

A Real-World Example

You look for a book in a library.

• First, the book must be in the catalog.
• Then you pick it by its title.
• You read it, and check the appendix when you need a table.

If the book is not in the catalog, a great book is still useless. Skills work the same way.

What You Will Learn

In this lesson, you will learn:

1. Discovery: how an agent finds the skills that are installed.
2. Activation: how it decides which skill to use.
3. Instructions: how the body guides the work.
4. Resources: how extra files load only when needed.
5. Verification: how results are checked.
6. Improvement: how real use makes a skill better.
7. How to find which layer is broken.
8. How to fix a skill that fires for the wrong request.
9. How to change one thing at a time, then test.

The Six Layers

Watch one request pass through each layer:

Every layer worked, so the reply passed every check.

Simple lesson: a request meets the layers in order. A break early on stops everything after it.

Discovery

Discovery = the agent finding out which skills exist.

At start-up, the coding tool looks in its skills folders.

• It finds every folder with a SKILL.md.
• It reads the front matter of each one.
• The result is the catalog: a short list of names and descriptions.

Discovery fails quietly. The agent does not warn you. It simply does not know the skill exists.

Common causes:

• The skill is in the wrong folder.
• The file is named skill.md instead of SKILL.md.
• The closing --- of the front matter is missing.

Simple lesson: if the agent cannot see a skill, nothing else about it matters.

Activation

Activation = the agent choosing a skill for the current request.

The model reads the catalog next to your request and decides. In many tools, you can also call a skill by name.

Everything depends on the description.

• It must say what the skill does.
• It must say when to use it.
• It must use the words people really type.

Example:

• Too vague: "Helps with docs."
• Clear: "Writes API reference docs for a function or endpoint. Use when someone asks to document an API, endpoint or function."

Click the button and open the Activation tab.

• The request is about documentation.
• docs-helper scores almost nothing, because its description has only three words.
• The fix: open it in the Library, write a proper description, press Save, and try again.

Watch the same fix, step by step:

With three words, another skill fired. With a clear description, docs-helper fired.

Simple lesson: a skill fires only when its description matches the request.

Instructions

Instructions = the body of the skill. It tells the agent how to do the task.

Strong instructions have:

• Inputs the agent should gather first.
• A numbered workflow, with one action per step.
• An output format with exact headings.
• Final checks to run before replying.

Weak instructions are one paragraph of good intentions, like "write up what changed in a helpful way". The model fills the gaps differently every time.

Click the button and open the Library tab.

• The checker flags the missing sections.
• Add a ## Workflow with numbered steps.
• Add an ## Output format, for example ## Added, ## Changed, ## Removed and ## Deprecated.
• Then press Save.

Simple lesson: numbered steps and a fixed output format make every reply look the same.

Resources

Resources = the extra files in a skill folder.

They include:

• reference documents
• scripts
• templates
• examples

Resources load only when needed. The agent opens a file only when a step or a final check tells it to.

That is good, because it keeps the context small.

But it also means a file the body never mentions is never opened.

The fix is one line in the right step, like "Check every table against references/index-rules.md."

Click the button and open the Library tab.

• The rule file references/index-rules.md is in the folder.
• No step tells the agent to open it.
• Add one line to the workflow that names the file.

Simple lesson: every extra file must be named in SKILL.md, or the agent never reads it.

Verification

Verification = checking the result before the user sees it.

It can happen at three levels:

Each level catches different mistakes:

• Final checks are quick to add. They catch many common mistakes.
• Scripts catch exact rules a model may get wrong, like counting.
• Tests catch a skill that worked last month but broke after an edit.

The next lesson covers testing in depth.

Click the button and open the Contract check tab.

• The reply was written without the skill.
• The check shows which of the five headings are missing.

Simple lesson: a check catches what the model missed, before the user sees it.

Improvement

Improvement = making the skill better from real use.

People often skip this layer. But a skill is never finished on day one. Real requests show cases you did not imagine.

The loop is simple:

1. Collect problems from real use.
2. Count which problem happens most.
3. Fix that one, with a clearer step, a new example or a script.
4. Test that the fix works and did not break anything else.
5. Version the change, so you can undo it.

Simple lesson: fix the most common problem first, with the smallest change.

Finding the Broken Layer

When a skill does not work, check the layers in order.

Fix the first broken layer before you look at the next one. For example, better instructions will not help if the skill never fires.

Watch the three broken skills from this lesson get checked, layer by layer:

Each skill broke at a different layer. So each one needs a different fix.

Click the button and open the Run tab.

• No skill: none of the six layers is there.
• Auto: switch the Skill menu to Auto and run again. All six layers work together.

Simple lesson: check the layers in order, and fix the first one that is broken.

Fires for the Wrong Request

Sometimes a skill fires when it should not.

This is still an activation problem.

Usually, two skills share the same words in their descriptions. So the wrong one can win.

The fix:

1. Look at which words matched in the Activation tab.
2. Remove words that belong to another skill.
3. Add a "Do not use for ..." line.
4. Test both skills again, not just the one you changed.

Example: pr-review says "Do not use for dedicated security audits". So security requests go to security-review.

Click the button and open the Activation tab.

• ui-review should win, because the request says "CSS" and "markup".
• pr-review scores lower, because those words are not in its description.
• Try it: remove "markup" and "CSS" from ui-review in the Library. Watch the winner change. Then press Reset.

Simple lesson: when a skill fires wrongly, narrow its description and add "Do not use" words.

Change One Thing, Then Test

Before you change a skill, check what really loaded.

Ask the agent: "Which skill did you use, and which files did you open?"

Then fix one thing.

If you change the description, the steps and a script at the same time, you will not know which change helped.

Every fix should end with a test. That way, the same problem cannot come back unnoticed.

Click the button and open the Evals tab.

• Each row is one request with the skill that should fire.
• A red row means a fix broke something else.

Simple lesson: make one small change, then run the tests again.

TL;DR

1. Diagnosing a skill = finding out why it does not work.

2. It has six layers:

   • Discovery = the agent can see the skill.
   • Activation = the agent picks it.
   • Instructions = the agent follows its steps.
   • Resources = the agent opens extra files when needed.
   • Verification = the result is checked.
   • Improvement = the skill gets better from real use.
3. Discovery needs the right folder and valid front matter.
4. Activation depends on the description.
5. Every extra file must be named in SKILL.md.
6. To fix a skill, find the first weak layer and make the smallest change.
7. A skill that fires wrongly needs a narrower description and "Do not use" words.
8. Change one thing at a time, then run the tests again.

Common Mistakes

Check Your Understanding

Exercises

These exercises help you practise finding and fixing a broken layer.

Press Check when you are ready. Use Show Hint if you get stuck.

What to Remember

• Every skill passes through six layers: discovery, activation, instructions, resources, verification and improvement.
• Discovery needs the right folder and valid front matter.
• Activation depends on the description.
• Instructions need inputs, numbered steps, an output format and final checks.
• Every extra file must be named in SKILL.md.
• Verification uses final checks, scripts and tests.
• Improvement is a loop: collect, count, fix, test, version.
• To fix a skill, find the first weak layer and make the smallest change.
• A skill that fires wrongly needs "Do not use" words.
• Change one thing at a time, and end every fix with a test.

Next: Skill Evaluation. You will build a set of tests that proves your skills work.