claude-code - 💡(How to fix) Fix [BUG] Agent SDK query() does not expand slash commands / skills — passed as literal prompt text [1 comments, 2 participants]

Description

When using the Agent SDK's query() API with a prompt that starts with a slash command (e.g., /ask ... or /jira ...), the slash command is not expanded into the skill's content. Instead, the literal string is passed through as the user prompt. This contrasts with the interactive CLI, where typing /ask auto-expands the skill content before the model sees it.

Steps to Reproduce

1. Create a skill in .claude/skills/ask/SKILL.md (or any other skill)
2. Use the Agent SDK to start a session:

   import { query } from '@anthropic-ai/claude-agent-sdk';
   
   const q = query({
     prompt: '/ask What does this function do?',
     options: {
       cwd: '/path/to/project',
       settingSources: ['user', 'project'],
       pathToClaudeCodeExecutable: '/usr/local/bin/claude',
     },
   });

3. Observe the session events

Expected Behavior

The /ask prefix should be recognized as a slash command, expanded into the skill's rendered SKILL.md content (just like the CLI does), and the expanded content should be what the model receives.

Actual Behavior

• The init event correctly discovers the skill and lists it in both skills and slash_commands arrays
• The Skill tool is available in the tools list
• But the prompt /ask What does this function do? is passed through as literal text — the model receives the raw string
• The model may or may not call the Skill tool itself to load the skill (unreliable — it often just starts working on the literal text)

Evidence from Logs

The init event shows the CLI subprocess knows about the skill:

{
  "type": "system",
  "subtype": "init",
  "slash_commands": ["ask", "jira", "push", ...],
  "skills": ["ask", "jira", "push", ...],
  "tools": ["Skill", ...]
}

But the model's first response goes straight to tool calls (Bash, Agent, etc.) without ever invoking Skill({ skill: "ask" }). In a ~7800-line session, the Skill tool was only called once (for a different skill, push), and never for the slash command in the original prompt.

Environment

• Claude Code version: 2.1.100
• Agent SDK: @anthropic-ai/claude-agent-sdk
• OS: Linux (Debian)
• Node.js subprocess via pathToClaudeCodeExecutable

Analysis

Since the SDK spawns the Claude CLI as a subprocess (pathToClaudeCodeExecutable), the CLI has all the machinery to expand slash commands — it discovers them, lists them in init, and makes the Skill tool available. The expansion logic just doesn't run for prompts provided via the SDK's query() parameter. It appears the CLI only expands slash commands in the interactive TUI input path, not in the non-interactive/SDK prompt path.

This creates a meaningful gap: skills that work reliably in the interactive CLI (via auto-expansion) become unreliable when used programmatically through the SDK (dependent on model choosing to call the Skill tool).