Agent skills are supposed to make an AI agent better at a specific job. A code review skill should inspect diffs with a repeatable checklist. A writing skill should apply the same voice rules every time. A deployment skill should know the commands, safety checks, and rollback steps your project needs.

When a skill fails, the problem usually is not that the model suddenly forgot how to work. More often, the agent never loaded the skill, loaded it too late, could not find the linked files, or followed instructions that were stale. Debugging skills means checking the handoff between the agent, the skill file, and the actual task.

Start with the failure mode

Do not debug every layer at once. Name what failed first.

Common failure modes:

  • The skill did not trigger at all
  • The agent mentioned the skill but did not follow it
  • The skill loaded, but supporting files were missing
  • The instructions worked in one agent but failed in another
  • The skill produced generic output instead of task-specific work
  • The skill used old commands or paths

Those are different problems. A trigger issue lives in the skill description and tags. A missing-file issue lives in the skill package. A stale-command issue lives in the runbook itself.

Check whether the skill was actually loaded

The first question is simple: did the agent read the skill before acting?

In Claude Code, Codex, Cursor, or another skill-aware agent, ask the agent to show which skill it used and where it came from. If the agent cannot name the skill file, assume it did not load it. Do not accept a vague answer like “I followed the debugging workflow.” Ask for the exact skill name.

For local skill folders, check the structure:

ls ~/.claude/skills
ls ~/.claude/skills/debugging-skill

A normal skill directory should have a SKILL.md file at the root. Optional assets belong in predictable subfolders like references/, scripts/, or templates/ depending on the agent runtime. If the main file is buried one level too deep after a clone, the agent may never see it.

Inspect the skill frontmatter

Most skills use frontmatter to tell the agent what the skill is for. The exact fields vary by runtime, but the description matters everywhere. If the description is too broad, the agent may ignore it. If it is too narrow, the skill only triggers when the user says a magic phrase.

Weak description:

description: Helps with code.

Better description:

description: Use when reviewing pull requests, inspecting git diffs, finding bugs, checking security issues, or preparing actionable code review comments.

The better version gives the agent several natural trigger paths: pull requests, diffs, bugs, security, and review comments. You are not stuffing keywords. You are naming the real situations where the skill should load.

Confirm linked files exist

Many strong skills are not just one markdown file. They include checklists, scripts, templates, or reference docs. If the skill points to a file that does not exist, the agent may fall back to generic behavior.

Look for references inside SKILL.md:

grep -n "references/\|scripts/\|templates/" ~/.claude/skills/my-skill/SKILL.md

Then confirm those files are present:

find ~/.claude/skills/my-skill -maxdepth 3 -type f

If a linked script exists, test it outside the agent. A broken helper script looks like an agent reasoning failure from the outside, but it is just a normal software bug.

python3 ~/.claude/skills/my-skill/scripts/check.py --help

Reproduce with a tiny task

A failing skill is easier to debug with a small input. If your deployment skill failed during a 40-minute release, do not rerun the release just to test the skill. Create a harmless task that should trigger the same instructions.

For a code review skill, use a small diff. For a writing skill, use three paragraphs. For a data skill, use a ten-row CSV. The goal is to see whether the agent loads the skill and follows the steps, not whether the whole production workflow succeeds.

A good test prompt is explicit:

Use the code review skill on this small diff. Tell me which checklist steps you applied before giving findings.

If the agent loads the skill only when you name it directly, your trigger description probably needs work. If it loads the skill but skips steps, the instructions may be too long, too vague, or buried under examples.

Watch for stale commands

Skills age. CLIs rename flags. APIs change auth flows. Repos move. A skill that worked six months ago can fail because one command is wrong.

Treat every command in a skill like code:

# Does the binary exist?
command -v gh
command -v uv
command -v npm

# Does the documented command still parse?
gh skill install --help
uv --help
npm --version

If a command fails, patch the skill immediately. Do not make the agent remember the correction in the chat. The next session will not have that context unless the skill file changes.

Check agent compatibility

Some skills assume a specific agent runtime. A Claude Code skill may mention slash commands, file editing flows, or permission prompts that Codex or Cursor do not share. That does not make the skill useless, but it does mean the instructions need compatibility notes.

Add a short section like this:

## Compatibility

- Claude Code: supports direct skill loading and slash-command examples.
- Codex: use the same workflow, but ask the agent to read this skill before starting.
- Cursor: use for project-level edits; verify file paths before applying changes.

This prevents the agent from trying to follow a UI flow that does not exist in its current body.

Tighten the instructions

A skill should be specific enough to change behavior. If it only says “be careful” or “write high-quality code,” it is not doing much. Replace advice with steps the agent can execute.

Weak:

Make sure the review is thorough and useful.

Better:

1. Read the diff.
2. Identify changed files by risk level.
3. Check for correctness bugs before style issues.
4. Flag security problems with severity.
5. Return only actionable findings, each with file path, line, issue, and fix.

The second version gives the agent a path. It also gives you something to test when the output is bad.

FAQ

Why did the agent ignore a skill I installed?

Usually because the trigger description did not match the task, the skill was installed in the wrong directory, or the agent session started before the skill was added. Restart the session, confirm the skill path, and test with a direct prompt naming the skill.

Should I make one big skill or several small ones?

Use smaller skills when the workflows have different success criteria. Code review, test generation, and release management are related, but they fail in different ways. Separate skills are easier to trigger and easier to debug.

Can a skill call tools or run scripts?

Yes, if the agent runtime allows it and the skill includes clear instructions. Keep scripts in the skill package, document required commands, and test each script directly before blaming the agent.

How often should skills be updated?

Any time a documented command fails, a user corrects the workflow, or the skill produces the wrong shape of output. Skills are operational memory. If they are not maintained, they turn into stale advice.