Skip to content

WalterSumbon/claude-agent-sdk-skill / skills/claude-agent-sdk-typescript

claude-agent-sdk-typescript

Flagged

Expert guidance for building AI agents with the Claude Agent SDK in TypeScript/JavaScript. Use when the user writes TypeScript or JavaScript code with the SDK, imports from "@anthropic-ai/claude-agent-sdk", uses query(), allowedTools, permissionMode, creates custom tools with createSdkMcpServer, sets up hooks, integrates MCP servers, manages sessions, or debugs SDK issues in TypeScript/Node.js. Also triggers on: "@anthropic-ai/claude-agent-sdk", "allowedTools", "permissionMode", "npm install", "for await", "AgentDefinition", or "settingSources".

FileKindSize
SKILL.mdskill md13.6 KB
references/troubleshooting.mdmarkdown3.2 KB

references/troubleshooting.md

View on GitHub
# Troubleshooting — TypeScript 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 `npm install @anthropic-ai/claude-agent-sdk`. If using a custom path:

```typescript
const options = { cliPath: "/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 `allowedTools`.

**Cause**: Missing `settingSources` configuration.

```typescript
// WRONG — Skills won't load
const options = { allowedTools: ["Skill"] };

// CORRECT — Skills loaded from filesystem
const options = {
  settingSources: ["user", "project"],
  allowedTools: ["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.

```typescript
// Restore old behavior explicitly
const options = {
  systemPrompt: { type: "preset", preset: "claude_code" },
};
```

### Subagents Not Invoked

**Symptom**: Claude ignores defined subagents.

**Cause**: Missing `"Task"` in `allowedTools`.

```typescript
// WRONG — Task tool not enabled
const options = {
  allowedTools: ["Read", "Grep"],
  agents: { reviewer: { /* ... */ } },
};

// CORRECT
const options = {
  allowedTools: ["Read", "Grep", "Task"], // Task required
  agents: { reviewer: { /* ... */ } },
};
```

### MCP Tool Name Mismatch

**Symptom**: Claude can't find your MCP tools.

**Cause**: Tool names must follow `mcp__<server-name>__<tool-name>` convention.

```typescript
// Server named "biz" with tool "search_orders"
// Correct tool name: "mcp__biz__search_orders"

// Use wildcard to allow all tools from a server:
allowedTools: ["mcp__biz"]
```

## Runtime Issues

### Agent Runs Forever

**Fix**: Set `maxTurns` to limit iterations:

```typescript
const options = { maxTurns: 50 };
```

### Permission Denied on File Edits

**Fix**: Set appropriate permission mode:

```typescript
// For automation (auto-approve edits)
const options = { permissionMode: "acceptEdits" };

// For full automation (bypass all permissions — use with caution)
const options = { permissionMode: "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)

- [ ] Update import: `@anthropic-ai/claude-code` → `@anthropic-ai/claude-agent-sdk`
- [ ] Update type name: `ClaudeCodeOptions` → `ClaudeAgentOptions`
- [ ] Review system prompt behavior — add explicit `preset: "claude_code"` if needed
- [ ] Add `settingSources` if you rely on Skills or CLAUDE.md
- [ ] Test all hooks and custom tools for compatibility
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: 471kUpdated Claude CodeCodexVerifiedInstall
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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 322kUpdated Claude CodeCodexVerifiedInstall