Troubleshooting Common Agent Skill Issues

Agent Skills are simple by design: a Markdown file with instructions. But simplicity does not mean problems never happen. This guide covers the most common issues people encounter and how to fix each one.

Problem: The Agent Does Not Use the Skill

You installed a skill, but when you ask the agent to do something related, it ignores the skill and improvises.

Check 1: Is the skill in the right directory?

Skills must live in the agent's skills directory:

# Claude Code
ls ~/.claude/skills/

# OpenAI Codex CLI
ls ~/.codex/skills/

If the skill directory is elsewhere, move it. The agent only discovers skills in its designated directory.

Check 2: Does the SKILL.md have a "When to activate" section?

The agent needs to know when to use a skill. If the SKILL.md lacks explicit activation criteria, the agent may never trigger it. Open the SKILL.md and look for a section like:

## When to activate
The user asks for release notes, changelog, or "what changed."

If this section is missing or vague, add it.

Check 3: Is your request specific enough?

"I need help with my project" does not match any skill. "Generate release notes for the last 2 weeks" does. Skills activate on specific triggers, not general requests.

Problem: The Skill Activates But Output Is Wrong

The agent uses the skill but the output does not match what you expect.

Fix 1: Check the output format instructions

Most output problems come from ambiguous formatting instructions. Instead of:

Output the results in a nice format.

Write:

Output format:
## New Features
- Description of change (`commit-hash`)
## Bug Fixes
- Description of fix (`commit-hash`)

Exact formats produce exact results.

Fix 2: Add constraints

If the agent adds information you do not want, add explicit constraints:

## Important rules
- Do not include author names
- Do not include dates unless requested
- Do not fabricate information

Negative instructions ("do not") are often more effective than positive ones for preventing unwanted output.

Fix 3: Provide examples

Add a concrete example of expected input and output:

## Example

Input: git log shows "feat: add search" and "fix: login bug"

Output:
## New Features
- add search (`abc1234`)

## Bug Fixes
- login bug (`def5678`)

One example prevents more misinterpretation than ten rules.

Problem: The Skill Makes the Agent Slow

The agent takes much longer to respond when a skill is loaded.

Cause: Large reference files

Some skills include large reference documents in a references/ directory. These get loaded into the agent's context window, increasing processing time.

Fix: Trim references to essentials

Only include reference content that the agent needs for every invocation. Move rarely-needed references to a URL the agent can fetch on demand:

## References
- Full API documentation: https://example.com/api-docs (fetch when user asks about specific endpoints)
- Quick reference card: references/quick-ref.md (always loaded)

Problem: Multiple Skills Conflict

You have two skills that cover similar tasks. The agent picks the wrong one or tries to use both.

Fix: Make activation conditions mutually exclusive

In each skill's "When to activate" section, be explicit about boundaries:

## When to activate
The user asks for release notes or changelog.
Do NOT activate for: git commit messages, PR descriptions, deployment notes.

## When to activate
The user asks to write a commit message for staged changes.
Do NOT activate for: release notes, changelogs, or general git history.

Overlap is the enemy. If two skills genuinely cover the same task, pick one and delete the other.

Problem: Skills Work Locally But Not After Publishing

You created a skill, tested it locally, published to GitHub, but others report it does not work.

Check 1: File paths are absolute, not relative

If your skill references scripts or files, use paths relative to the skill directory:

# Wrong (your local path)
/Users/you/.claude/skills/my-skill/scripts/run.sh

# Right (relative)
scripts/run.sh

Check 2: Script permissions

Scripts need execute permissions:

chmod +x scripts/run.sh
git add scripts/run.sh
git commit -m "fix: add execute permission to script"

Check 3: Platform-specific assumptions

If your skill runs shell commands, test on both macOS and Linux. Common issues:

• sed syntax differs between GNU and BSD
• date flags differ between platforms
• realpath is not available on older macOS

Problem: Context Window Fills Up

Loading multiple skills consumes context tokens, leaving less room for actual work.

Fix: Load only what you need

Do not install 50 skills at once. Install the ones you use daily and add others as needed. You can check what is loaded:

ls ~/.claude/skills/

If you have more than 10-15 skills installed, remove the ones you have not used in the past week. You can always reinstall them later.

The General Troubleshooting Pattern

1. Check the SKILL.md first. Most problems are instruction problems, not platform bugs.
2. Be specific. Vague instructions produce vague output.
3. Add examples. One concrete example beats ten abstract rules.
4. Test incrementally. Change one thing, test, repeat.
5. Read the agent's reasoning. Most AI agents show which skills they activated and why. If the reasoning is wrong, fix the activation conditions.

Having trouble with a specific skill? Check the SkillMap leaderboard for alternatives, or review our getting-started guide.