How to Test and Debug Agent Skills [Verification Guide]

Created a skill but it doesn't work as expected?

This article explains how to test and debug Agent Skills. We'll cover techniques for efficiently identifying and fixing problems.

Basic Testing Procedure

1. Test Minimal Configuration

First, verify the skill is recognized with minimal content.

Copy---
name: test-skill
description: Test skill
---

## Instructions

Output "Test successful".

If /test-skill works, basic setup is correct.

2. Add Features Incrementally

Building complex skills all at once makes problem isolation difficult.

CopyStep 1: Verify minimal config works ✓
Step 2: Add basic instructions
Step 3: Define output format
Step 4: Add references/
Step 5: Add scripts/ (if needed)

Verify at each step to quickly identify issues.

3. Test with Different Inputs

Same skill may behave differently based on input:

Copy# Normal case
/code-review
Review src/index.ts

# Edge case
/code-review
(no file specified)

# Error case
/code-review
Review nonexistent.ts

Debugging Procedure

Skill Not Recognized

Checklist:

1. Directory structure

Copyls -la ~/.claude/skills/my-skill/
# Verify SKILL.md exists

1. Filename

Copy✓ SKILL.md (uppercase)
✗ skill.md (lowercase)
✗ Skill.md (mixed case)

1. Frontmatter

Copy# ✓ Correct
---
name: my-skill
description: Skill description
---

# ✗ Wrong (no space after colon)
---
name:my-skill
description:Skill description
---

1. Encoding

Copyfile ~/.claude/skills/my-skill/SKILL.md
# Verify UTF-8

Skill Not Auto-Applied

Checklist:

1. Description specificity

Copy# ✗ Vague
description: Check code

# ✓ Specific
description: Review TypeScript PRs for security and performance

1. Conflicts with other skills

Copy/skills
# Check for skills with similar descriptions

1. Test with explicit invocation

Copy/my-skill
# Verify direct invocation works

Output Doesn't Match Expectations

Checklist:

1. Instruction clarity

Copy# ✗ Vague
Review please.

# ✓ Clear
Review from these perspectives:
1. Security (SQL injection, XSS)
2. Performance (N+1 queries)
3. Type safety (any type usage)

1. Add output examples

Copy## Output Example

```json
{
  "issues": [
    {
      "file": "src/index.ts",
      "line": 42,
      "severity": "high",
      "message": "Potential SQL injection"
    }
  ]
}

Copy
3. **Explicit constraints**
```markdown
## Constraints

- Output in English
- Under 100 characters
- JSON format

Debugging Tools

/skills Command

Check currently active skills:

Copy/skills

If skill doesn't appear, there's a placement or format issue.

Check Detailed Logs

Increase log level in Claude Code settings to see skill loading status.

Diff Testing

When problems occur, compare with working version:

Copydiff working-skill/SKILL.md broken-skill/SKILL.md

Common Errors and Solutions

YAML Parse Error

Cause: Frontmatter syntax error

Copy# ✗ No space after colon
name:my-skill

# ✗ Quote mismatch
description: "description text'

# ✓ Correct
name: my-skill
description: "description text"

Character Encoding Issues

Cause: Encoding problem

Solution: Re-save as UTF-8 (no BOM)

scripts/ Not Executing

Causes:

• No execution permission
• Tool doesn't support scripts/

Solution:

Copychmod +x scripts/my-script.sh

Or provide fallback that works without scripts.

Test Automation

Document Test Cases

Copy## Test Cases

### TC-1: Basic Operation
- Input: `/code-review src/index.ts`
- Expected: Review results in JSON format

### TC-2: No File Specified
- Input: `/code-review`
- Expected: Error "Please specify a file"

### TC-3: Nonexistent File
- Input: `/code-review nonexistent.ts`
- Expected: Error "File not found"

Regression Testing

After updating skills, re-test previously working cases.

Summary

Key points for testing and debugging Agent Skills:

1. Start with minimal config
2. Add features incrementally
3. Test with different inputs
4. Use logs
5. Document test cases

When problems occur, go through this article's checklist.

Related Articles

• How to Create Your Own Skills - Skill creation basics
• Troubleshooting Agent Skills - Common problems and solutions
• Advanced Techniques - Using references/ and scripts/
• 7 Tips for Better Productivity - Efficient development methods