# Diagnosing Skills

Course: [Agent Skills](https://www.devtutorials.ai/learn/agent-skills) · Section: Skill Quality and Safety
Source: https://www.devtutorials.ai/learn/agent-skills/quality/skill-debugging

> 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.

**About this lesson's Skill Lab**

- The lab loads three broken skills into your DevKit.
- Each one fails at a different layer.
- Your job: find the weak layer, fix it in the **Library** tab, and press **Save**.

## The Six Layers

Watch one request pass through each layer:

Every layer worked, so the reply passed every check.

| Layer | Question it answers | Where it lives | What often goes wrong |
| --- | --- | --- | --- |
| **Discovery** | Can the agent see the skill? | The folder location | Wrong folder, or broken front matter |
| **Activation** | Does the agent pick it? | The `description` | Vague description, or two skills that overlap |
| **Instructions** | Does it do the work the right way? | The SKILL.md body | Plain text instead of steps, no output format |
| **Resources** | Does it use the right detail? | `references/`, `scripts/`, `templates/` | Files the body never mentions |
| **Verification** | Is the result checked? | Final checks, scripts, tests | No checks, or checks nobody runs |
| **Improvement** | Does it get better over time? | Feedback, tests, versions | The same mistake every week |

**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.

**The fastest check:** ask the agent, "Which skills do you have?"

Most tools also list loaded skills in a menu or with a slash command. If your skill is not listed, the problem is discovery. Fix that first.

**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:

| Level | Who checks | Example |
| --- | --- | --- |
| **Final checks in SKILL.md** | The model, before replying | "Every input line appears exactly once." |
| **Scripts** | Code the model runs | `scripts/check_notes.py` prints OK or the missing headings |
| **Tests and review** | You and your team | A small set of tests the skill must pass before each change |

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.

**Important:** do not fix a skill by adding one more paragraph each time.

- That makes SKILL.md longer and more vague.
- Instead, fix the **weakest layer** with the **smallest** change.
- Then add a test, so the same problem cannot come back unnoticed.

**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.

| What you see | Check this layer first |
| --- | --- |
| The agent does not list the skill | Discovery |
| It is listed, but never used | Activation |
| It is used for the wrong requests | Activation (add "Do not use" words) |
| It is used, but the reply looks different every time | Instructions |
| It ignores a rule from a reference file | Resources |
| It is mostly right, but small rules slip | Verification |
| The same complaint keeps coming back | Improvement |

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

| Mistake | Wrong idea | Correct idea | What goes wrong |
|---|---|---|---|
| Fixing the wrong layer | "Better steps will fix it." | Check the layers in order. | The steps improve, but the skill still never fires. |
| Thinking installed means found | "I copied the folder, so it works." | Ask the agent which skills it has. | The skill sits in the wrong folder and never loads. |
| Blaming the model | "The model is not smart enough." | Check the description first. | The real cause, a vague description, stays. |
| Hiding key rules in reference files | "All the detail goes in references." | Put rules needed every time in SKILL.md. | The agent never opens the file, so it misses the rule. |
| Skipping verification | "The model will get it right." | Add final checks and scripts. | Mistakes reach the user. |
| Changing many things at once | "I will fix everything now." | Change one thing, then test. | You cannot tell which change helped or broke something. |
| Never improving | "The skill is done." | Collect feedback and fix the top problem. | The same mistake happens every week. |

## 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.