WalterSumbon/claude-agent-sdk-skill / skills/claude-agent-sdk-typescript
claude-agent-sdk-typescript
FlaggedExpert 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".
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 13.6 KB |
| references/troubleshooting.md | markdown | 3.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
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: 471k | 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 |