When a skill file isn't working as expected — agents misapply it, users give negative feedback, or the skill produces incorrect results — you need a systematic debugging approach. This skill covers diagnosing and fixing the most common skill file issues: from formatting problems that break parsing to subtle instruction ambiguities that lead agents astray.

## Key Points

1. "Agent ignores the skill entirely"
2. "Agent applies the skill to wrong situations"
3. "Agent follows instructions but produces wrong output"
4. "Agent only partially follows the skill"
5. "Agent adds things not in the skill"
1. Identify the specific failure
2. Isolate the skill
3. Test the exact version
4. Document the reproduction steps
1. Make the minimum change that fixes the issue
2. Test the fix against the reproduction case
3. Test for regressions

## Quick Example

```
Issue: Code block not parsed as code
Cause: Missing or mismatched backticks
Fix: Ensure three backticks on own line, with language:
```

Debugging Skill Files

Purpose

When a skill file isn't working as expected — agents misapply it, users give negative feedback, or the skill produces incorrect results — you need a systematic debugging approach. This skill covers diagnosing and fixing the most common skill file issues: from formatting problems that break parsing to subtle instruction ambiguities that lead agents astray.

Symptom-Based Diagnosis

Common Symptoms and Causes

Symptom → Likely Causes → Fixes

1. "Agent ignores the skill entirely"
   Causes:
   ├── Purpose section doesn't match the task description
   ├── Title/tags don't match search terms
   ├── Skill not indexed in the discovery system
   └── Another skill is a better match and gets selected instead
   Fixes:
   ├── Rewrite Purpose with task-oriented language
   ├── Add synonyms and alternative terms to tags
   ├── Verify skill is in the indexed directory
   └── Review competing skills for overlap

2. "Agent applies the skill to wrong situations"
   Causes:
   ├── Purpose/tags are too broad
   ├── Missing "When NOT to Apply" section
   ├── Tags overlap with unrelated skills
   └── Title is generic
   Fixes:
   ├── Narrow the Purpose statement
   ├── Add explicit scope boundaries
   ├── Remove overly broad tags
   └── Make title more specific

3. "Agent follows instructions but produces wrong output"
   Causes:
   ├── Code examples have bugs
   ├── Instructions are ambiguous
   ├── Missing steps in the procedure
   ├── Assumed context not stated
   └── Version mismatch (skill is outdated)
   Fixes:
   ├── Test all code examples independently
   ├── Rewrite ambiguous instructions (see below)
   ├── Walk through steps from scratch (fresh-eyes test)
   ├── Add prerequisites section
   └── Update for current technology versions

4. "Agent only partially follows the skill"
   Causes:
   ├── Skill is too long (exceeds useful context)
   ├── Later sections contradict earlier ones
   ├── Instructions are buried in prose
   ├── Some steps are phrased as suggestions, not instructions
   └── Agent prioritizes more recent/prominent instructions
   Fixes:
   ├── Trim to essential content (target 200-400 lines)
   ├── Resolve contradictions (choose one approach)
   ├── Use numbered steps and clear formatting
   ├── Use imperative mood: "Do X" not "You might want to X"
   └── Front-load the most important instructions

5. "Agent adds things not in the skill"
   Causes:
   ├── Skill is incomplete (gaps the agent fills with hallucination)
   ├── Instructions are too high-level (agent improvises details)
   ├── Missing constraints (agent doesn't know what NOT to do)
   └── Agent's base knowledge overrides skill instructions
   Fixes:
   ├── Fill in the gaps with specific instructions
   ├── Add detail to high-level steps
   ├── Add explicit constraints (MUST NOT list)
   └── Add "Follow these instructions exactly" framing

Debugging Process

Step 1: Reproduce the Issue

Reproduction Protocol:
1. Identify the specific failure
   └── What task was attempted?
   └── What was the expected outcome?
   └── What actually happened?

2. Isolate the skill
   └── Test with ONLY the skill file as context
   └── No other skills, no additional instructions
   └── Provide a clear task that should trigger this skill

3. Test the exact version
   └── Same skill file version
   └── Same agent/model version
   └── Same input task description

4. Document the reproduction steps
   └── "Given skill file version X, task Y, agent Z produced output W"
   └── This becomes your test case for verifying the fix

Step 2: Identify the Root Cause

Root Cause Analysis Framework:

Layer 1: Is the skill findable?
├── Search for the skill using terms a user would use
├── Check if title and tags match common search queries
├── Check if the skill is in the correct category/directory
└── If not findable → Discovery problem (see Discovery skill)

Layer 2: Is the skill selected correctly?
├── Give the agent the task and see which skill it selects
├── If it selects a different skill → Purpose is too weak or too similar
├── If it selects nothing → Purpose/tags don't match the task
└── Review "When to Apply" for accuracy

Layer 3: Are the instructions parseable?
├── Read the skill as if you're an AI (literally, word by word)
├── Look for ambiguous pronouns ("it", "this", "that")
├── Look for unspecified references ("the file", "the function")
├── Look for implicit knowledge (unstated assumptions)
└── If issues found → Clarity problem (see Instructions skill)

Layer 4: Are the instructions correct?
├── Execute every code block independently
├── Follow every procedure step by step
├── Verify every stated output/result
├── Check for version-specific changes
└── If issues found → Accuracy problem (fix the content)

Layer 5: Are the instructions complete?
├── Attempt the full task using ONLY the skill
├── Note every point where you need outside knowledge
├── Note every point where the skill assumes something
├── Note every point where a step is missing
└── If issues found → Completeness problem (add missing content)

Step 3: Fix and Verify

Fix Methodology:
1. Make the minimum change that fixes the issue
   └── Don't rewrite the whole skill for one bug
2. Test the fix against the reproduction case
   └── Same task, same setup, verify correct output
3. Test for regressions
   └── Other tasks that previously worked still work
4. Document the fix
   └── What was wrong, what was changed, why
5. Increment version
   └── PATCH for bug fixes, MINOR for content additions

Common Issues and Fixes

Formatting Issues

Issue: Code block not parsed as code
Cause: Missing or mismatched backticks
Fix: Ensure three backticks on own line, with language:
     ```python
     code here
     ```

Issue: YAML frontmatter causes parse error
Cause: Unescaped special characters in title
Fix: Quote strings containing colons or special chars:
     title: "React: Server Components" (not React: Server Components)

Issue: Nested list loses formatting
Cause: Inconsistent indentation (mixing tabs and spaces)
Fix: Use exactly 2 or 4 spaces for each nesting level, consistently

Issue: Table renders as plain text
Cause: Missing alignment row or inconsistent column count
Fix: Ensure header row, alignment row (---|---|---), and data rows
     all have the same number of pipes

Issue: ASCII diagram misaligned
Cause: Non-monospace characters or wrong character width
Fix: Use only ASCII or basic box-drawing characters
     Test in a plain text editor with monospace font

Ambiguity Issues

Issue: "Configure the server" — which server? how?
Fix: "In `server.ts`, set the `PORT` environment variable to 3000:
     `const port = process.env.PORT || 3000;`"

Issue: "Use the appropriate method" — which method?
Fix: "Use `Array.prototype.filter()` to select matching items,
     then `Array.prototype.map()` to transform them."

Issue: "Handle errors" — what errors? how?
Fix: "Wrap the fetch call in try/catch:
     - On network error (TypeError): retry up to 3 times
     - On 4xx response: log error and return null
     - On 5xx response: retry once, then throw"

Issue: "After setting up the database" — what constitutes "set up"?
Fix: "After the database is running and the schema is applied
     (you should be able to run `SELECT 1` successfully):"

Issue: "Similar to the previous approach" — which approach?
Fix: Name approaches explicitly and reference by name:
     "Using the Repository Pattern (described in the section above):"

Completeness Issues

Issue: Missing prerequisite step
Symptom: Instructions fail because something wasn't set up
Fix: Add Prerequisites section listing required state

Issue: Missing error handling in example
Symptom: Code works for happy path but fails on edge cases
Fix: Add error handling to code examples, or add separate
     "Error Handling" subsection

Issue: Missing verification step
Symptom: User doesn't know if they did it correctly
Fix: After each significant step, add:
     "Verify: [command] should output [expected result]"

Issue: Missing cleanup/teardown
Symptom: Resources left running after skill application
Fix: Add "Cleanup" section at the end:
     "When done, remove temporary resources:
     docker rm -f test-db
     rm -rf /tmp/test-project"

Issue: Missing "what to do next"
Symptom: User completes skill but doesn't know where to go
Fix: Add cross-references to logical next skills in
     "When to Apply" or a "Next Steps" section

Outdated Content

Issue: Library API has changed
Symptom: Code examples throw "method not found" errors
Fix: Update code for current API version
     Add note about version: "Tested with Express 4.x"
     Consider adding migration note from previous version

Issue: Tool no longer exists or is renamed
Symptom: Installation commands fail
Fix: Replace with current tool/package name
     Note if migration from old tool is needed

Issue: Recommended practice has changed
Symptom: Skill teaches an approach now considered anti-pattern
Fix: Update to current best practice
     Briefly note the old approach and why it changed
     Bump MAJOR version if the change is significant

Issue: External links are broken
Symptom: 404 errors when following links
Fix: Find current URLs for the same resources
     If resource no longer exists, find alternative or remove link

Prevention

Preventing Skill Issues:
├── Before publishing:
│   ├── Run through the Quality Checklist skill
│   ├── Test all code examples on a clean environment
│   ├── Have someone else follow the instructions
│   └── Test with an AI agent in isolation
├── Ongoing:
│   ├── Monitor for user feedback/reports
│   ├── Schedule periodic reviews (every 3-6 months)
│   ├── Track library/tool version releases
│   └── Automate link checking and format validation
└── When updating:
    ├── Test the update against known reproduction cases
    ├── Check for regressions in related skills
    ├── Update cross-references if structure changed
    └── Increment version appropriately

When to Apply This Skill

Use this skill when:

• A skill file is producing unexpected agent behavior
• Users report that a skill's instructions don't work
• Reviewing a skill that hasn't been updated in months
• Investigating why an AI agent misapplied a skill
• Performing a systematic quality audit of a skill pack
• Diagnosing formatting issues that break skill rendering