WalterSumbon/claude-agent-sdk-skill / skills/claude-agent-sdk-python
claude-agent-sdk-python
FlaggedExpert guidance for building AI agents with the Claude Agent SDK in Python. Use when the user writes Python code with the SDK, imports claude_agent_sdk, uses query(), ClaudeSDKClient, ClaudeAgentOptions, AgentDefinition, creates custom @tool functions, sets up hooks, integrates MCP servers, manages sessions, or debugs SDK issues in Python. Also triggers on: "claude_agent_sdk", "ClaudeAgentOptions", "from claude_agent_sdk import", "pip install claude-agent-sdk", "asyncio.run", or "async for message in query".
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 14.0 KB |
| references/troubleshooting.md | markdown | 3.2 KB |
references/troubleshooting.md
View on GitHub# Troubleshooting — Python SDK
## Installation Issues
### CLINotFoundError
The SDK requires the Claude Code CLI bundled within the package. If you see this error:
```
CLINotFoundError: Claude Code CLI not found
```
**Fix**: The CLI is auto-bundled with `pip install claude-agent-sdk`. If using a custom path:
```python
options = ClaudeAgentOptions(cli_path="/path/to/claude")
```
Or install CLI separately: `curl -fsSL https://claude.ai/install.sh | bash`
### Node.js Required
The Claude Code CLI requires Node.js >= 18. Ensure it's installed:
```bash
node --version # Should be >= 18
```
## Configuration Mistakes
### Skills Not Loading
**Symptom**: Claude doesn't discover or invoke Skills even though `"Skill"` is in `allowed_tools`.
**Cause**: Missing `setting_sources` configuration.
```python
# WRONG — Skills won't load
options = ClaudeAgentOptions(allowed_tools=["Skill"])
# CORRECT — Skills loaded from filesystem
options = ClaudeAgentOptions(
setting_sources=["user", "project"],
allowed_tools=["Skill"],
)
```
### System Prompt Surprise (v0.1.0+)
**Symptom**: Agent behaves differently after upgrading from v0.0.x.
**Cause**: v0.1.0 no longer loads Claude Code's system prompt by default.
```python
# Restore old behavior explicitly
options = ClaudeAgentOptions(
system_prompt={"type": "preset", "preset": "claude_code"}
)
```
### Subagents Not Invoked
**Symptom**: Claude ignores defined subagents.
**Cause**: Missing `"Task"` in `allowed_tools`.
```python
# WRONG — Task tool not enabled
options = ClaudeAgentOptions(
allowed_tools=["Read", "Grep"],
agents={"reviewer": AgentDefinition(...)},
)
# CORRECT
options = ClaudeAgentOptions(
allowed_tools=["Read", "Grep", "Task"], # Task required
agents={"reviewer": AgentDefinition(...)},
)
```
### MCP Tool Name Mismatch
**Symptom**: Claude can't find your MCP tools.
**Cause**: Tool names must follow `mcp__<server-name>__<tool-name>` convention.
```python
# Server named "biz" with tool "search_orders"
# Correct tool name: "mcp__biz__search_orders"
# Use wildcard to allow all tools from a server:
allowed_tools=["mcp__biz"]
```
## Runtime Issues
### Agent Runs Forever
**Fix**: Set `max_turns` to limit iterations:
```python
options = ClaudeAgentOptions(max_turns=50)
```
### Permission Denied on File Edits
**Fix**: Set appropriate permission mode:
```python
# For automation (auto-approve edits)
options = ClaudeAgentOptions(permission_mode="acceptEdits")
# For full automation (bypass all permissions — use with caution)
options = ClaudeAgentOptions(permission_mode="bypassPermissions")
```
### Context Window Exhaustion
The SDK has built-in compaction (automatic summarization when context limit approaches).
If you still hit limits in very long sessions, consider:
1. Breaking tasks into smaller `query()` calls
2. Using subagents to isolate context per task
3. Using `ClaudeSDKClient` and starting new conversations when appropriate
## Migration Checklist (v0.0.x → v0.1.0)
- [ ] Replace `ClaudeCodeOptions` with `ClaudeAgentOptions`
- [ ] Review system prompt behavior — add explicit `preset: "claude_code"` if needed
- [ ] Add `setting_sources` if you rely on Skills or CLAUDE.md
- [ ] Test all hooks and custom tools for compatibility
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 470k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |