[BUG] Skills not invoked on first turn despite matching description — Opus acknowledges miss when prompted
Preflight Checklist
- [x] I have searched existing issues and this hasn't been reported yet
- [x] This is a single bug report (please file separate reports for different bugs)
- [x] I am using the latest version of Claude Code
What's Wrong?
User skills are loaded and visible via /skills (4 total: 2 user + 2 plugin), but they are never invoked on the first turn even when the prompt clearly matches the skill description.
For example, I have a helm skill whose description matches helm chart operations. When I ask "upgrade me the jobset helm chart to 0.11.1", Claude proceeds with Search → Read → Edit and never calls Skill(helm).
When I then ask "why don't you use my skills?", Claude responds "You're right, I should use the helm skill" and immediately calls Skill(helm) successfully.
What Should Happen?
When the prompt matches a skill description, the Skill tool should be invoked on the first turn without the user having to remind Claude.
Error Messages/Logs
Sending 15 skills via attachment (initial, 15 total sent)
Tool search disabled for model 'claude-haiku-4-5-20251001': model does not support tool_reference blocks. This feature is only available on Claude Sonnet 4+, Opus 4+, and newer models.
ToolSearchTool: selected Glob, Read, Edit
# Second turn (after user asks about skills):
ToolSearchTool: selected Skill
Steps to Reproduce
- Create a user skill in
~/.claude/skills/helm/SKILL.mdwith a description matching helm chart operations - Start Claude Code:
claude -d --verbose - Verify skills are loaded:
/skillsshows 4 skills - Ask: "upgrade me the jobset helm chart to 0.11.1"
- Observe: Claude uses Search → Read → Edit, never calls Skill(helm)
- Ask: "why don't you use my skills?"
- Observe: Claude says "You're right" and calls Skill(helm) successfully
Claude Model
Opus
Is this a regression?
I don't know
Last Working Version
_No response_
Claude Code Version
2.1.83
Platform
Anthropic API
Operating System
macOS
Terminal/Shell
Terminal.app (macOS)
Additional Information
My theory (from analyzing the debug log): a Haiku-based ToolSearch pre-filter runs before the main Opus call to decide which deferred tools to include. Since Haiku doesn't support tool_reference blocks, it never selects the Skill tool on the first turn. Opus then doesn't get the opportunity to use skills because they weren't in its tool set.
Full debug log attached (from ~/.claude/debug/09eb03a8-dd4a-405a-ba59-5aa36debe19f.txt).
This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗