Squawkpipe Claude Skill

A Claude Code skill that teaches Claude how to interact with Squawk — a conversation observation layer for AI agents. This skill is designed for AI agents and Claude users who need to read conversations, send replies, and add internal notes.

What It Does

The skill provides Claude with knowledge about:

• Fetching conversations — retrieve full context (metadata, contact details, message history) with squawk conversation <id>
• Sending replies — deliver messages to customers on their original channel with squawk reply <id> --body "..."
• Adding private notes — create internal notes visible only to supervisors with squawk note <id> --body "..."
• Understanding conversation structure — message types, contact context, channel rules
• Channel constraints — WhatsApp 24-hour messaging window, muted/paused conversation states
• Conversation state machine — active, paused, and permanently-ended conversation states

When using Claude with Squawk, this skill ensures Claude:

• Understands the conversation JSON structure
• Respects channel-specific rules and constraints
• Handles errors gracefully (e.g., 409 when conversation is paused)
• Makes informed decisions based on contact context and message history

Installation

Install via npm:

npm install -g @squawkpipe/claude-skill

This registers the /squawk command in Claude Code.

Then type /squawk in Claude Code to load the skill.

How to Use

With squawk listen --claude

This is the simplest way to use the skill. Start a listening agent:

squawk listen --claude "You are a helpful customer support agent. Read the conversation and draft a thoughtful reply."

Squawk will:

1. Poll for new conversations
2. Pass each conversation JSON to Claude on stdin
3. Claude uses the /squawk skill to understand the structure and compose a reply
4. Squawk automatically sends the reply

With squawk link

For more advanced control, use squawk link to route conversations to a custom agent script:

#!/bin/bash
# my-agent.sh
input=$(cat)
conv_id=$(echo "$input" | jq -r '.conversation.id')

# Claude reads the conversation and decides what to do
reply=$(claude -p "You are a support agent. Reply to this conversation." <<< "$input")

# Send the reply
squawk reply "$conv_id" --body "$reply"

Then start the agent:

squawk link --agent ./my-agent.sh --pipe email

Standalone in Claude Code

Load the skill manually by typing /squawk in Claude Code. This teaches Claude the Squawk command vocabulary without using the listening agent. Useful for:

• Manual one-off conversations
• Debugging
• Custom integrations

Then Claude can:

/squawk conversation conv_abc123
/squawk reply conv_abc123 "Thank you for contacting us!"
/squawk note conv_abc123 "Customer prefers email over phone"

Requirements

• Squawkpipe CLI installed and in PATH: Install from NPM
• Claude Code (web or desktop app)
• Authentication: Set SQUAWK_API_KEY and SQUAWK_TENANT_ID, or run squawk login and squawk api-key

Skill Content

The skill (in SKILL.md) teaches Claude:

1. Core Operations

   • squawk conversation <id> — fetch conversation with full context
   • squawk reply <id> --body "..." — send a message to the customer
   • squawk note <id> --body "..." — add an internal note (never visible to customer)

2. Conversation JSON Structure

   • Conversation metadata (id, channel, status, contact)
   • Contact details and supervisor notes
   • Message history with message types (message, system, note)

3. Channel Rules

   • Email threading and professional tone
   • WhatsApp 24-hour messaging window constraint
   • Brief, conversational replies for WhatsApp

4. State Machine

   • Active (agent can send)
   • Paused (supervisor hijacked; don't send)
   • Permanently ended (never respond again)
   • HTTP 409 error handling

5. Best Practices

   • Always read contact notes before replying
   • Respect muted/paused states
   • Add notes for complex reasoning
   • Handle messaging window errors gracefully