pitfalls-websocket
WebSocket server and client patterns with heartbeat and reconnection. Use when implementing real-time features, debugging connection issues, or reviewing WebSocket code. Triggers on: WebSocket, wss, heartbeat, reconnect, real-time.
Best use case
pitfalls-websocket is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
WebSocket server and client patterns with heartbeat and reconnection. Use when implementing real-time features, debugging connection issues, or reviewing WebSocket code. Triggers on: WebSocket, wss, heartbeat, reconnect, real-time.
Teams using pitfalls-websocket 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/pitfalls-websocket/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How pitfalls-websocket Compares
| Feature / Agent | pitfalls-websocket | 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?
WebSocket server and client patterns with heartbeat and reconnection. Use when implementing real-time features, debugging connection issues, or reviewing WebSocket code. Triggers on: WebSocket, wss, heartbeat, reconnect, real-time.
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.
SKILL.md Source
# WebSocket Pitfalls
Common pitfalls and correct patterns for WebSocket implementations.
## When to Use
- Implementing WebSocket server
- Building WebSocket client with reconnection
- Debugging connection drops
- Adding heartbeat/ping-pong
- Reviewing WebSocket code
## Workflow
### Step 1: Verify Server Setup
Check WebSocket server shares HTTP port.
### Step 2: Check Heartbeat
Ensure ping/pong heartbeat is implemented.
### Step 3: Verify Client Reconnection
Confirm exponential backoff reconnection logic.
---
## Server Pattern
```typescript
const wss = new WebSocketServer({ server: httpServer }); // Same port
wss.on('connection', (ws) => {
// Heartbeat
ws.isAlive = true;
ws.on('pong', () => { ws.isAlive = true; });
ws.on('message', (data) => {
try {
const msg = JSON.parse(data.toString());
// Validate message type
} catch {
ws.send(JSON.stringify({ error: 'Invalid message' }));
}
});
});
// Heartbeat interval
setInterval(() => {
wss.clients.forEach((ws) => {
if (!ws.isAlive) return ws.terminate();
ws.isAlive = false;
ws.ping();
});
}, 30000);
```
## Client Reconnection
```typescript
// Client - reconnection logic with exponential backoff
let attempt = 0;
function connect() {
const ws = new WebSocket(url);
ws.onopen = () => {
attempt = 0; // Reset on successful connection
};
ws.onclose = () => {
const delay = Math.min(1000 * Math.pow(2, attempt), 30000);
attempt++;
setTimeout(connect, delay);
};
ws.onerror = (error) => {
console.error('WebSocket error:', error);
};
}
```
## Message Handling
```typescript
// ✅ Always validate and type messages
interface WsMessage {
type: 'subscribe' | 'unsubscribe' | 'ping';
channel?: string;
}
function handleMessage(ws: WebSocket, data: string) {
try {
const msg: WsMessage = JSON.parse(data);
switch (msg.type) {
case 'subscribe':
subscribeToChannel(ws, msg.channel);
break;
case 'ping':
ws.send(JSON.stringify({ type: 'pong' }));
break;
default:
ws.send(JSON.stringify({ error: 'Unknown message type' }));
}
} catch {
ws.send(JSON.stringify({ error: 'Invalid JSON' }));
}
}
```
## Quick Checklist
- [ ] WebSocket server uses same port as HTTP
- [ ] Heartbeat ping/pong every 30 seconds
- [ ] Client has reconnection with exponential backoff
- [ ] Messages validated before processing
- [ ] Connection errors loggedRelated Skills
websocket-handler-setup
Websocket Handler Setup - Auto-activating skill for Backend Development. Triggers on: websocket handler setup, websocket handler setup Part of the Backend Development skill category.
websocket-client-creator
Websocket Client Creator - Auto-activating skill for API Integration. Triggers on: websocket client creator, websocket client creator Part of the API Integration skill category.
exa-known-pitfalls
Identify and avoid Exa anti-patterns and common integration mistakes. Use when reviewing Exa code, onboarding new developers, or auditing existing Exa integrations for correctness. Trigger with phrases like "exa mistakes", "exa anti-patterns", "exa pitfalls", "exa what not to do", "exa code review".
customerio-known-pitfalls
Identify and avoid Customer.io anti-patterns and gotchas. Use when reviewing integrations, onboarding developers, or auditing existing Customer.io code. Trigger: "customer.io mistakes", "customer.io anti-patterns", "customer.io gotchas", "customer.io pitfalls", "customer.io code review".
cursor-known-pitfalls
Avoid common Cursor IDE pitfalls: AI feature mistakes, security gotchas, configuration errors, and team workflow issues. Triggers on "cursor pitfalls", "cursor mistakes", "cursor gotchas", "cursor issues", "cursor problems", "cursor tips".
clay-known-pitfalls
Identify and avoid the top Clay anti-patterns, gotchas, and integration mistakes. Use when reviewing Clay integrations for issues, onboarding new team members, or auditing existing Clay table configurations. Trigger with phrases like "clay mistakes", "clay anti-patterns", "clay pitfalls", "clay what not to do", "clay gotchas", "clay code review".
clade-known-pitfalls
Common mistakes when building with the Anthropic API and how to avoid them. Use when working with known-pitfalls patterns. Trigger with "anthropic mistakes", "claude pitfalls", "anthropic gotchas", "common claude errors", "anthropic anti-patterns".
canva-known-pitfalls
Identify and avoid Canva Connect API anti-patterns and common integration mistakes. Use when reviewing Canva code, onboarding developers, or auditing existing Canva integrations for best practices violations. Trigger with phrases like "canva mistakes", "canva anti-patterns", "canva pitfalls", "canva what not to do", "canva code review".
building-websocket-server
Build scalable WebSocket servers for real-time bidirectional communication. Use when enabling real-time bidirectional communication. Trigger with phrases like "build WebSocket server", "add real-time API", or "implement WebSocket".
anth-known-pitfalls
Identify and avoid common Claude API anti-patterns and integration mistakes. Use when reviewing code, onboarding developers, or debugging subtle issues with Anthropic integrations. Trigger with phrases like "anthropic pitfalls", "claude anti-patterns", "claude mistakes", "anthropic common issues", "claude gotchas".
adobe-known-pitfalls
Identify and avoid Adobe-specific anti-patterns: using deprecated JWT auth, not caching IMS tokens, ignoring Firefly content policy, missing async job polling, and leaking p8_ secrets. Real code examples with fixes. Trigger with phrases like "adobe mistakes", "adobe anti-patterns", "adobe pitfalls", "adobe what not to do", "adobe code review".
pitfalls-tanstack-query
TanStack Query v5 patterns and common pitfalls. Use when implementing data fetching, cache invalidation, or debugging stale data issues. Triggers on: useQuery, useMutation, queryKey, invalidate, TanStack, React Query.