Agent skill · writing content · jeremylongshore
clade-known-pitfalls
Common mistakes when building with the Anthropic API and how to avoid
Why this skill is useful
Provides specific patterns and best practices for avoiding common mistakes with the Anthropic API that the AI wouldn't generate reliably on its own.
What it needs
About 3k tokens when loaded. Last updated 2026-08-07. 2,604 stars on the source repository.
What this skill does
Anthropic Known Pitfalls Overview Ten common mistakes when building with the Anthropic API and how to avoid them: forgetting maxtokens (required), system prompt in messages array (wrong), non-alternating messages, unchecked stopreason, creating client per request, no 529 handling, hardcoded model IDs, expensive output tokens, no streaming, and unnecessary PII. 1. Forgetting maxtokens Unlike OpenAI, maxtokens is required. Omitting it returns a 400 error. 2. System Prompt in Messages Array Claude uses a top-level system parameter, not a system message in the array. 3. Non-Alternating Messages Messages must strictly alternate between user and assistant. 4. Not Checking stopreason If stopreason === 'maxtokens', the response was truncated. 5. Creating Client Per Request Each new Anthropic() creates a new connection pool. In serverless, this adds latency. 6. No Error Handling for 529 529 (overloaded) is common during peak hours. The SDK retries automatically, but you should handle it for critical paths. 7. Hardcoding Model IDs Model IDs change with new versions. Use environment variables. 8. Ignoring Token Costs Output tokens cost 5x more than input tokens. A 4096 maxtokens response on Opus costs ~$0.30. Use the smallest maxtokens that works. 9. No Streaming for User-Facing Apps Without streaming, users stare at a blank screen for 5-30 seconds. Always stream for interactive use. 10. Sending PII Unnecessarily Don't include user PII in prompts unless the task requires it. Redact before sending. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills jeremylongshore/clade-known-pitfalls--b18aaa