Claude Code Skills: Build Your Own AI Workflows · Lesson 4 of 6

Lesson 4: Testing and Debugging: Making Sure Your Skill Behaves

Learning goals:

Learn the basic ways to test a Skill

Diagnose the failures you'll actually hit

Understand the iteration loop

Know how to check whether a Skill is genuinely worth keeping

Prerequisites: << Lesson 3 | Next: Lesson 5 >>

Your first Skill won't be right

You wrote your first Skill, ran it, and noticed things like:

Some tasks weren't recognized at all
Priorities came out wrong
The output format was a mess
Or Claude never loaded the Skill in the first place

That's normal.

Skills are like code: getting it to run once is the starting line, not the finish. Every Skill that's actually useful got there through several rounds of revision.¹

This lesson gives you a repeatable way to find and fix those problems.

Testing method 1: Invoke it directly

The simplest test is a direct invocation: call it once with /skill-name and watch what comes out.²

Prepare your test cases

Before you invoke anything, write down three to five inputs.

Normal cases:

Edge cases:

Garbage cases:

Run the tests

In Claude Code, feed them in one at a time:

Watch three things:

Did Claude load the Skill at all? (If not, the problem is in the description.)
Is the output format correct? (If it's messy, the problem is in your output-format section.)
Is the content what you expected? (If the categories are wrong, the problem is in your processing steps.)

Write down what happened

A small table is enough:

Input	Expected	Actual	Problem
"Finish the quarterly report\nFix the bug tomorrow"	2 tasks; the bug is urgent	Only 1 task found	Newlines aren't being treated as separators

Testing method 2: Watch the loading behavior

Sometimes the problem isn't in the instructions at all — it's in the frontmatter.

Problem: Claude doesn't load the Skill on its own

What you see: you say "help me organize these tasks" and Claude ignores your task-organizer Skill.

Likely causes:

The description is too generic

YAML

description: Handles tasks  # Too vague — Claude has no idea when this applies

Fix: put the trigger words in.

YAML

description: Organizes to-do items and groups them by priority and due date. Use for messy task lists or meeting action items

The description doesn't contain the words you actually say

If you say "help me sort out these to-dos" but "to-do" appears nowhere in the description, Claude may never think of the Skill.³

Fix: write the words a user would plausibly say into the description.

Problem: Claude loads the wrong Skill

What you see: you wanted task-organizer, but Claude picked up something else.

Likely cause: the other Skill's description matches your input more closely.

Fix: force the call with /task-organizer, or sharpen your description so it's more specific than the competitor's.

Diagnosing common failures

Problem 1: The output format is wrong

What you see: the Skill runs, but the formatting is off.

Example:

You wanted grouped sections with emoji and headings; Claude gave you a flat text list.

Cause: the output-format section isn't specific enough, or it has no example.

Fix: put a complete example in the "Output format" section of your SKILL.md:

MARKDOWN

## Output format

Output must follow this format exactly, including the emoji, headings, and indentation:

### 🔴 Urgent (today or tomorrow)
- Fix the login bug - tomorrow

### 🟡 Important (this week)
- Review PR #234 - Friday

### ⚪ Normal
- Finish the quarterly report - no stated deadline

Say "must follow this format exactly," then show the whole thing.

Problem 2: Recognition is inaccurate

What you see: some tasks get missed, or they land in the wrong category.

Example:

Input:

Output:

### ⚪ Normal- Need to fix that bug tomorrow - no stated deadline- Get the demo ready before Friday - no stated deadline

### ⚪ Normal- Need to fix that bug tomorrow - no stated deadline- Get the demo ready before Friday - no stated deadline

Both have a clear deadline, and both were marked as having none.

Cause: the time-recognition rules in your processing steps don't cover enough cases.

Fix: fill them in.

MARKDOWN

2. **Identify time information**
   - Look for date keywords:
     * today, tonight
     * tomorrow
     * the day after tomorrow
     * this week, Monday through Sunday
     * next week, next <weekday>
     * explicit dates (2024-01-15, January 15, 1/15)
   - Look for deadline phrasing:
     * before X, by X
     * due X, deadline X
     * needs to be done by X

The point: spell out every phrasing you can think of.

Problem 3: Edge cases fall through

What you see: normal input is fine, but unusual input makes the Skill behave strangely.

Example:

Input: an empty string

Output: Claude stalls, or produces a pile of meaningless text.

Cause: your "Notes" section never said what to do with empty input.

Fix:

MARKDOWN

## Notes

- **On empty input or no valid tasks**, output "No valid tasks found — please provide a list of to-do items"
- **When no task has any time information**, put everything under "Normal" and add the note "No explicit deadlines detected"
- **When a task description runs past 100 characters**, truncate to the first 80 plus "..."
- **When the input contains completed items (`[x]`)**, skip them

The iteration loop

Good Skills aren't written once. They come out of a test-fix-test loop:¹

1. Write the first version (core behavior only)2. Run it against 3-5 test cases3. Write down what went wrong4. Edit SKILL.md5. Test again6. Repeat 3-5 until every test case passes7. Use it for real for a week8. Find new problems9. Go back to step 4

1. Write the first version (core behavior only)2. Run it against 3-5 test cases3. Write down what went wrong4. Edit SKILL.md5. Test again6. Repeat 3-5 until every test case passes7. Use it for real for a week8. Find new problems9. Go back to step 4

Don't expect version one to be right. Make it run, then make it correct, then make it good.

Is the Skill actually useful?

Once it runs correctly, there's a bigger question left: is this Skill actually saving you time?¹

A/B it

The comparison is simple: run the same task several times with and without the Skill, and time both.

Without the Skill:

Time it. You explain the process by hand, Claude executes — how long does that take on average?

With the Skill:

Time it. You invoke the Skill, Claude executes — how long on average?

If the Skill version isn't faster, or the quality is worse, the Skill still needs work.

Use it for a week

The real test is real use.⁴

Track these numbers:

How many times you invoked it
How many times the result was usable as-is, with no manual edits
How many times you had to re-run it or fix the output by hand
How much time it saved

If you invoked it fewer than three times in a week, the task probably isn't repetitive enough to justify a Skill.

Debugging cheat sheet

When a Skill won't work, start with a loading-failure check — walk the table below and rule out the file path, the frontmatter format, and the trigger keywords in that order.

Problem	How to diagnose	Where to fix
Claude doesn't auto-load the Skill	Check whether the description contains the words you actually said	Add trigger words, spell out the use case
Output format is messy	Check whether you gave a complete output example	Add the example, add "must follow this format exactly"
Recognition is inaccurate	Check whether the processing steps enumerate every case	Add rules, add more decision criteria
Edge cases misbehave	Check whether "Notes" covers that case	Add explicit handling for the special case
The Skill exists but won't invoke	Check the file path, check the frontmatter format	Confirm the `---` markers are in the right place and the YAML indentation is valid

Recap

Your first Skill won't be right — it takes a test-fix-test loop to get there
Testing methods: invoke it directly, watch the loading behavior, prepare test cases up front
Common failures: description too generic, output format under-specified, recognition rules incomplete, edge cases unhandled
Debugging flow: record expected vs. actual, diagnose, edit SKILL.md, re-test
Proving it's worth it: compare time, quality, and consistency with and against no Skill, then use it for a week and count the invocations

In the next lesson we'll walk through a complete code review Skill and see how to handle a more involved workflow.

>> Lesson 5: Case Study: Building a Code Review Skill

Claude Code skills: .NET workflows and reusable prompts — https://codewithmukesh.com/blog/skills-claude-code/ ↩ ↩² ↩³
Claude Code official docs: Extend Claude Code with skills — https://code.claude.com/docs/en/skills ↩
Building skills for Claude, hands-on: YAML frontmatter and testing — https://sjramblings.io/building-skills-for-claude-part-2/ ↩
Claude skills as self-documenting runbooks — https://zackproser.com/blog/claude-skills-internal-training ↩

Exercises

Take the Skill you built in Lesson 3 and run it through a full test pass:

Level 1: Debug your own Skill

Prepare 3 test cases (one normal, one edge, one garbage)
Record the expected and actual output for each
Find at least one concrete problem
Edit SKILL.md
Re-test and confirm the problem is gone

Done criteria · checked locally

Test cases cover normal, edge, and garbage inputExpected and actual output are both written downAt least one specific problem identified (not "it feels a bit off")A specific part of SKILL.md was changedRe-tested and the fix confirmed

Do the same task twice: once with your Skill, once by just describing what you want to Claude directly. Then compare:

Level 2: Compare against no Skill

Which was faster
Which produced better results
Which was more consistent (same output shape across repeated runs)

Done criteria · checked locally

The same task completed both waysTimings recordedQuality and consistency assessedA clear statement of where the Skill wins — or an honest admission that it doesn't

Lesson 4: Testing and Debugging: Making Sure Your Skill Behaves

Your first Skill won't be right

Testing method 1: Invoke it directly

Prepare your test cases

Run the tests

Write down what happened

Testing method 2: Watch the loading behavior

Problem: Claude doesn't load the Skill on its own

Problem: Claude loads the wrong Skill

Diagnosing common failures

Problem 1: The output format is wrong

Problem 2: Recognition is inaccurate

Problem 3: Edge cases fall through

The iteration loop

Is the Skill actually useful?

A/B it

Use it for a week

Debugging cheat sheet

Recap

Footnotes

Exercises

Take the Skill you built in Lesson 3 and run it through a full test pass:

Do the same task twice: once with your Skill, once by just describing what you want to Claude directly. Then compare: