clade-advanced-troubleshooting
Debug complex Claude issues — inconsistent outputs, tool use failures, Use when working with advanced-troubleshooting patterns. streaming problems, and edge cases. Trigger with "claude inconsistent", "anthropic advanced debug", "claude tool use broken", "anthropic streaming issues".
Best use case
clade-advanced-troubleshooting is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Debug complex Claude issues — inconsistent outputs, tool use failures, Use when working with advanced-troubleshooting patterns. streaming problems, and edge cases. Trigger with "claude inconsistent", "anthropic advanced debug", "claude tool use broken", "anthropic streaming issues".
Teams using clade-advanced-troubleshooting should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/clade-advanced-troubleshooting/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How clade-advanced-troubleshooting Compares
| Feature / Agent | clade-advanced-troubleshooting | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Debug complex Claude issues — inconsistent outputs, tool use failures, Use when working with advanced-troubleshooting patterns. streaming problems, and edge cases. Trigger with "claude inconsistent", "anthropic advanced debug", "claude tool use broken", "anthropic streaming issues".
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
Related Guides
AI Agents for Coding
Browse AI agent skills for coding, debugging, testing, refactoring, code review, and developer workflows across Claude, Cursor, and Codex.
Best AI Skills for Claude
Explore the best AI skills for Claude and Claude Code across coding, research, workflow automation, documentation, and agent operations.
ChatGPT vs Claude for Agent Skills
Compare ChatGPT and Claude for AI agent skills across coding, writing, research, and reusable workflow execution.
SKILL.md Source
# Anthropic Advanced Troubleshooting
## Overview
Debug complex Claude integration issues that go beyond basic error handling — inconsistent outputs, tool use failures where Claude calls nonexistent tools, streaming connection drops, max_tokens truncation, and image/vision format problems.
## Inconsistent Outputs
**Symptom:** Same prompt gives different answers each time.
**Cause:** `temperature` defaults to 1.0 (maximum randomness).
```typescript
// Fix: Set temperature to 0 for deterministic outputs
const message = await client.messages.create({
model: 'claude-sonnet-4-20250514',
max_tokens: 1024,
temperature: 0, // Deterministic
messages,
});
```
## Tool Use Failures
**Symptom:** Claude calls a tool that doesn't exist or sends wrong parameters.
```typescript
// Always validate tool calls before executing
const toolUse = response.content.find(b => b.type === 'tool_use');
if (toolUse) {
const validTools = tools.map(t => t.name);
if (!validTools.includes(toolUse.name)) {
console.error(`Claude requested unknown tool: ${toolUse.name}`);
// Send error back as tool_result
messages.push({ role: 'assistant', content: response.content });
messages.push({ role: 'user', content: [{
type: 'tool_result',
tool_use_id: toolUse.id,
is_error: true,
content: `Tool "${toolUse.name}" does not exist. Available: ${validTools.join(', ')}`,
}]});
}
}
```
## Streaming Connection Drops
**Symptom:** Stream stops mid-response without `message_stop` event.
```typescript
// Detect incomplete streams
const stream = client.messages.stream({ ... });
let gotStop = false;
for await (const event of stream) {
if (event.type === 'message_stop') gotStop = true;
// ... process events
}
if (!gotStop) {
console.error('Stream ended without message_stop — connection dropped');
// Retry the request
}
```
## `max_tokens` Truncation
**Symptom:** Response cuts off mid-sentence.
```typescript
const message = await client.messages.create({ ... });
if (message.stop_reason === 'max_tokens') {
console.warn('Response truncated — increase max_tokens or ask for shorter output');
// Option 1: Increase max_tokens
// Option 2: Add "Be concise" to system prompt
// Option 3: Continue the response with another call
}
```
## Image/Vision Issues
**Symptom:** Claude says it can't see the image.
- Max image size: 5MB
- Supported: PNG, JPEG, GIF, WebP
- Max 20 images per request
- Base64 encoding must be correct (no data URI prefix in the `data` field)
```typescript
// Correct image format
{
type: 'image',
source: {
type: 'base64',
media_type: 'image/png', // Must match actual format
data: buffer.toString('base64'), // Raw base64, no "data:image/png;base64," prefix
},
}
```
## Output
- Inconsistent outputs fixed via temperature control
- Tool use validated against defined tool names before execution
- Streaming connection drops detected and retried
- Truncated responses identified via `stop_reason` check
- Image format issues resolved (correct media_type, raw base64, size limits)
## Error Handling
| Error | Cause | Solution |
|-------|-------|----------|
| API Error | Check error type and status code | See `clade-common-errors` |
## Examples
See Inconsistent Outputs (temperature fix), Tool Use Failures (validation), Streaming Connection Drops (detection), max_tokens Truncation (stop_reason check), and Image/Vision Issues (correct format) above.
## Resources
- [Error Types](https://docs.anthropic.com/en/api/errors)
- [Tool Use Guide](https://docs.anthropic.com/en/docs/build-with-claude/tool-use)
- [Vision Docs](https://docs.anthropic.com/en/docs/build-with-claude/vision)
## Next Steps
See `clade-debug-bundle` for collecting support evidence.
## Prerequisites
- Completed `clade-common-errors` for basic error handling
- Familiarity with Claude API response structure
- Access to application logs with full request/response data
## Instructions
### Step 1: Review the patterns below
Each section contains production-ready code examples. Copy and adapt them to your use case.
### Step 2: Apply to your codebase
Integrate the patterns that match your requirements. Test each change individually.
### Step 3: Verify
Run your test suite to confirm the integration works correctly.Related Skills
windsurf-advanced-troubleshooting
Advanced Windsurf debugging for hard-to-diagnose IDE, Cascade, and indexing issues. Use when standard troubleshooting fails, Cascade produces consistently wrong output, or investigating deep configuration problems. Trigger with phrases like "windsurf deep debug", "windsurf mystery error", "windsurf impossible to fix", "cascade keeps failing", "windsurf advanced debug".
vercel-advanced-troubleshooting
Advanced debugging for hard-to-diagnose Vercel issues including cold starts, edge errors, and function tracing. Use when standard troubleshooting fails, investigating intermittent failures, or preparing evidence for Vercel support escalation. Trigger with phrases like "vercel hard bug", "vercel mystery error", "vercel intermittent failure", "difficult vercel issue", "vercel deep debug".
supabase-advanced-troubleshooting
Deep Supabase diagnostics: pg_stat_statements for slow queries, lock debugging with pg_locks, connection leak detection, RLS policy conflicts, Edge Function cold starts, and Realtime connection drop analysis. Use when standard troubleshooting fails, investigating performance regressions, debugging race conditions, or building evidence for Supabase support escalation. Trigger: "supabase deep debug", "supabase slow query", "supabase lock contention", "supabase connection leak", "supabase RLS conflict", "supabase cold start".
snowflake-advanced-troubleshooting
Apply advanced Snowflake debugging with query profiling, spill analysis, lock contention, and performance deep-dives using ACCOUNT_USAGE views. Use when standard troubleshooting fails, investigating slow queries, or diagnosing warehouse performance issues. Trigger with phrases like "snowflake hard bug", "snowflake slow query debug", "snowflake query profile", "snowflake spilling", "snowflake deep debug".
shopify-advanced-troubleshooting
Debug complex Shopify API issues using cost analysis, request tracing, webhook delivery inspection, and GraphQL introspection. Trigger with phrases like "shopify hard bug", "shopify mystery error", "shopify deep debug", "difficult shopify issue", "shopify intermittent failure".
sentry-advanced-troubleshooting
Advanced Sentry troubleshooting for complex SDK issues, silent event drops, source map failures, distributed tracing gaps, and SDK conflicts. Use when events silently disappear, source maps fail to resolve, traces break across service boundaries, or the SDK conflicts with other libraries like OpenTelemetry or winston. Trigger with phrases like "sentry events missing", "sentry source maps broken", "sentry debug", "sentry not capturing errors", "sentry tracing gaps", "sentry memory leak", "sentry sdk conflict".
salesforce-advanced-troubleshooting
Apply Salesforce advanced debugging with debug logs, SOQL query plans, and EventLogFile analysis. Use when standard troubleshooting fails, investigating SOQL performance issues, or analyzing Apex governor limit violations. Trigger with phrases like "salesforce hard bug", "salesforce debug log", "salesforce governor limit", "salesforce query plan", "salesforce deep debug", "SOQL slow".
retellai-advanced-troubleshooting
Retell AI advanced troubleshooting — AI voice agent and phone call automation. Use when working with Retell AI for voice agents, phone calls, or telephony. Trigger with phrases like "retell advanced troubleshooting", "retellai-advanced-troubleshooting", "voice agent".
replit-advanced-troubleshooting
Debug hard Replit issues: container lifecycle, Nix build failures, deployment crashes, and memory leaks. Use when standard troubleshooting fails, investigating intermittent failures, or diagnosing complex Replit platform behavior. Trigger with phrases like "replit hard bug", "replit mystery error", "replit impossible to debug", "replit intermittent", "replit deep debug".
perplexity-advanced-troubleshooting
Apply advanced debugging techniques for hard-to-diagnose Perplexity Sonar API issues. Use when standard troubleshooting fails, investigating inconsistent citations, or preparing evidence for support escalation. Trigger with phrases like "perplexity hard bug", "perplexity mystery error", "perplexity inconsistent results", "difficult perplexity issue", "perplexity deep debug".
notion-advanced-troubleshooting
Deep debugging for Notion API: response inspection, permission chain tracing, property type mismatches, pagination edge cases, and block nesting limits. Use when standard troubleshooting fails or investigating intermittent errors. Trigger with phrases like "notion deep debug", "notion permission trace", "notion property mismatch", "notion pagination bug", "notion nesting limit".
hubspot-advanced-troubleshooting
Debug complex HubSpot API issues with systematic isolation and evidence collection. Use when standard troubleshooting fails, investigating intermittent CRM errors, or preparing evidence bundles for HubSpot support escalation. Trigger with phrases like "hubspot hard bug", "hubspot mystery error", "hubspot intermittent failure", "hubspot deep debug", "hubspot support ticket".