Claude Code's Skills Are Kinda Broken—Use Them Anyway

An honest look at Claude Code skills—what works, what doesn't, and how to actually use them reliably in practice

Claude Code’s skills documentation says that:

Claude automatically applies relevant Skills when your request matches their description.

That’s utter horseshit. And it’s not the only broken promise with skills.

After converting my entire workflow to skills and testing every several approaches to improving invocation rates, I can tell you auto-invocation never works consistently. You’ll either manually invoke every skill (defeating the purpose) or write aggressive workarounds to force the behavior Anthropic promises out of the box.

I still love skills and think they’re the next evolution of agent tooling. The specification is elegant and mixing scripts with prompts is powerful. But there are several broken promises with skills—and you need to know what works and what doesn’t before you spend days converting your workflow like I did.

Auto-Invocation

The writing on the box for skills says:

Skills are model-invoked: Claude decides which Skills to use based on your request. You don’t need to explicitly call a Skill.

This is a lie. In practice, Claude Code will not invoke skills related to a task most of the time. I’ve experimented with a few different approaches to try and improve this.

• Skill description optimization: The Superpowers repository has a Claude Search Optimization guide to help increase the hit rate of descriptions. The gist is that the description should state when the skill should be used, not what it does. This helps, but still isn’t enough to get Claude Code to take initiative.

• Using Superpowers: The Superpowers repo also includes a using-superpowers skill that gives strict instructions to agents to always invoke a skill. This didn’t help—Claude Code still ignored skills.

• CLAUDE.md instructions: I also experimented with writing instructions similar to Using Superpowers and directly reading that file from my CLAUDE.md file via an @ reference. This seems to work better, and has the bonus of not requiring an extra skill invocation, but it’s not perfect.

For now, I’ve decided I’d rather invoke skills manually. It’s a pain, but at least I know that they’ll run when I need them.

Slash Commands

Claude Code recently consolidated Skills and commands, which makes a lot of sense—they’re both forms of pre-written prompts, but skills have more capabilities. Even better, skills now show up as custom slash commands, making them easy to invoke with /my-awesome-skill. So auto-invocation not working isn’t that big of a deal, right?

Well, not quite. There are several quirky issues with how skills show up as slash commands that can easily bite you.

• Marketplace skills don’t show up in slash command autocompletion. This makes it difficult to distribute skills, especially if you’re trying to share them with a development team.

• Skills don’t work with subdirectories or parent directories. This can make organizing skills more complicated in more complex setups, such as monorepos.

• The name field in skills is finicky. It has strange interactions with slash commands, stripping out the namespace sometimes depending on how they’re loaded. The current fix is to leave it out entirely — Claude Code falls back to the directory name.

None of these are insurmountable, but it’s better to be aware of them before you spend a bunch of time debugging. I’m hoping that Anthropic fixes these soon. However, the Claude Code Issues page is a haunted graveyard of bugs, so who knows?

Script Paths

Slash commands aside, there’s another problem with how Claude Code handles skills.

The Agent Skills specification says that skill paths should be relative to the SKILL.md file itself—reference files like references/example.md or scripts like scripts/example.ts directly.

And yet Claude Code seems clueless when trying to find these files. Here’s an example of the agent struggling to find a script file from my planning skill:

⏺ Bash(scripts/generate-plan-template.ts --help)
  ⎿  Error: Exit code 127
     (eval):1: no such file or directory: scripts/generate-plan-template.ts

⏺ Bash(bun scripts/generate-plan-template.ts --help)
  ⎿  Error: Exit code 1
     error: Module not found "scripts/generate-plan-template.ts"

⏺ Search(pattern: "scripts/**/*")
  ⎿  Found 0 files

⏺ Bash(ls -la)
  ⎿  (No content)

⏺ Since the scripts/generate-plan-template.ts doesn't exist in this project, I'll create the plan file directly.

Odd, right? Claude Code doesn’t follow its own specification for skill paths.

I worked around this by adding the following to my CLAUDE.md file:

Scripts in skills are always relative to the SKILL.md file. For example, if a SKILL.md file references scripts/generate-plan-template.ts and is located at skills/writing-skill/SKILL.md, then the script’s path would be skills/writing-skill/scripts/generate-plan-template.ts.

Testing Skills

Out of the box, if you ask Claude Code to write a skill for you, it probably won’t do a good job. The agent likely won’t get what you’re trying to do—it’ll skip steps, leave out important criteria, or miss edge cases you care about.

This is because you’re missing one of the key ideas for getting agents to perform well: give the agent a way to check its work.

One of my favorite tricks I learned from the Superpowers writing-skills skill is to test skills using subagents. Run a subagent with your skill and watch exactly what breaks—what it skips, what it gets wrong, what rationalizations it makes. Then update the skill and repeat. Keep testing with fresh subagents and tightening the skill until it stops making mistakes.

To simplify this process, I’d highly, highly recommend using a skill to write skills. I started with the writing-skills skill from Superpowers and reworked it to match my own preferences.

Conclusion

With all of these problems, are skills worth it? Hell yeah! The skills specification is so simple and elegant—it feels like taking a weed whacker to an MCP server. With a few minutes, you can easily extend agent behavior and add new abilities your agent never had.

The bugs are real and a pain, but the productivity gains you’ll get are worth it. And things will get better as more agents expand their support for them. Skills will change the way you work with agents, so jump in—it’s worth it.