[BUG] Agent SDK query() does not expand slash commands / skills — passed as literal prompt text
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
- Create a skill in
.claude/skills/ask/SKILL.md(or any other skill) - Use the Agent SDK to start a session:
```typescript
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',
},
});
```
- 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
initevent correctly discovers the skill and lists it in bothskillsandslash_commandsarrays - The
Skilltool 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
Skilltool 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).
This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗