anthropics / anthropics/claude-agent-sdk-typescript
Background Agents Cannot Access Skill Tool
- Dominant language
- Shell
- Stars
- 1.8k
- Forks
- 226
- PR merge metrics
- No merged PRs in 30d
Description
## Environment
- **Claude Agent SDK Version:** 0.1.67
- **Claude Code Version:** 2.0.67
## Summary
Background/asynchronous agents spawned with `run_in_background: true` do not have access to the `Skill` tool, even when explicitly specified in the agent definition.
## Description
When using the Claude Agent SDK to spawn agents programmatically, there is an inconsistency in tool availability between synchronous and asynchronous agents:
- **Synchronous agents**: Have access to the `Skill` tool as expected
- **Asynchronous agents** (background): Do NOT have access to the `Skill` tool, despite having access to other tools like `Read`, `Write`, and `Bash`
This prevents background agents from loading and executing skills, limiting their functionality compared to synchronous agents.
### Code Example
```typescript
const messages = query({
prompt: "Use the my-agent agent in the background to write a fun fact about cats.",
options: {
settingSources: ["project"],
plugins: [{ type: "local", path: "./plugins" }],
},
});
```
## Attempted Workarounds
The following approaches were tested without success:
1. **Frontmatter specification**: Listing the `Skill` tool in the agent definition markdown file frontmatter
```yaml
---
name: my-agent
tools: Skill,Read,Write,Bash
---
```
2. **Agent definition object**: Setting tools in the `AgentDefinition` object passed to the query function
```typescript
definition.tools = ["Skill", "Read", "Write", "Bash"];
agents["my-agent"] = definition;
```
None of these approaches successfully granted the `Skill` tool access to background agents.
## Expected Behavior
Background agents should have access to the `Skill` tool when it is:
- Explicitly listed in the agent definition's `tools` property
- Specified in the agent markdown file frontmatter
The `Skill` tool should be available to background agents in the same way it is available to synchronous agents, allowing them to load and execute skills as needed.
## Actual Behavior
Background agents do not have access to the `Skill` tool, regardless of how it is specified in the configuration. Other tools (e.g., `Read`, `Write`, `Bash`) are accessible to background agents as expected.
## Additional Context
The issue appears to be specific to the `Skill` tool and does not affect other tools, suggesting there may be special handling of the `Skill` tool that doesn't account for background agent execution contexts.
Available tools were determined by inspecting the requests to the LiteLLM proxy.
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.