# HeySummon Provider Skill

> You are a human-help provider for AI agents via HeySummon.

- Skill: `modbender/heysummon-provider-skill` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add modbender/heysummon-provider-skill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/modbender/heysummon-provider-skill/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: modbender (https://skillmd.com/u/modbender)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/modbender/heysummon-provider-skill

---


# HeySummon Provider Skill

You are a human-help provider for AI agents via HeySummon.

## Setup

### Step 1: Configure .env

Check if `.env` exists in `{baseDir}`. If not, copy from `.env.example`:

```bash
cp {baseDir}/.env.example {baseDir}/.env
```

Required variables:
- `HEYSUMMON_BASE_URL` — Platform URL (cloud: `https://cloud.heysummon.ai`, self-hosted: user provides)
- `HEYSUMMON_API_KEY` — Provider key (`hs_prov_...`) from the dashboard
- `HEYSUMMON_NOTIFY_TARGET` — Chat ID for notifications

### Step 2: Validate key

The API key **MUST** start with `hs_prov_`. Reject keys with `hs_cli_` prefix — those are client keys.

### Step 3: Start the watcher

```bash
bash {baseDir}/scripts/setup.sh
```

To stop: `bash {baseDir}/scripts/teardown.sh`

## Architecture

```
AI Agent → HeySummon Platform → SSE → Watcher → OpenClaw → Notification
```

All communication flows through the platform. No direct infrastructure access.

## Scripts

| Script | Purpose |
|--------|---------|
| `scripts/setup.sh` | Start the event watcher |
| `scripts/teardown.sh` | Stop the watcher |
| `scripts/mercure-watcher.sh` | SSE listener → notifications via OpenClaw |
| `scripts/reply-handler.sh` | Reply by refCode: `reply-handler.sh HS-XXXX "response"` |
| `scripts/respond.sh` | Reply by request ID: `respond.sh <id> "response"` |

## Reply-to-Respond

When the user replies to a 🦞 notification, parse the refCode (HS-XXXX) from the quoted message and use `reply-handler.sh`. **Always forward immediately — no AI processing, no confirmation.**

## Statuses

| Status | Meaning |
|---|---|
| `pending` | Waiting for provider |
| `active` | Conversation in progress |
| `responded` | Provider sent a response |
| `closed` | Closed by either party |
| `expired` | No response within 72 hours |