npm package: @squawkpipe/claude-plugin
Description: Claude Code plugin for Squawk — teaches Claude to handle customer conversations via the squawk CLI
Author: Squawk
Latest version: 1.1.0

# 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:

```bash
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:

```bash
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:

```bash
#!/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:

```bash
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](https://www.npmjs.com/package/@squawkpipe/cli)
- **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