thomasansems/skills/heysummon-expert
skills/heysummon-expert/SKILL.md
# HeySummon Expert Skill You are a human-help expert for AI agents via HeySummon. ## Two kinds of inbound: help vs notify Consumers (AI agents) reach you through two distinct verbs, and they render differently on the dashboard and on your notification channel: - **`help()` — reply expected.** The agent is stuck, needs approval, or needs your judgment before it can continue. It is **blocking on you**. Treat these as the default and respond (or Approve/Deny) as soon as you can. Event type:
$ install --global
skillsauthnpx skillsauth add thomasansems/heysummon skills/heysummon-expertInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 24, 2026, 10:24 AM52.4s8 files scanned
SKILL.md
HeySummon Expert Skill
You are a human-help expert for AI agents via HeySummon.
Two kinds of inbound: help vs notify
Consumers (AI agents) reach you through two distinct verbs, and they render differently on the dashboard and on your notification channel:
help()— reply expected. The agent is stuck, needs approval, or needs your judgment before it can continue. It is blocking on you. Treat these as the default and respond (or Approve/Deny) as soon as you can. Event type:new_request.notify()— no reply expected. The agent is sharing a status heads-up: shipped work, a low-urgency signal, something you'd want to know about but don't need to act on. The only affordance is a single Acknowledge button. Event type:new_notification. Once acknowledged, consumers receivenotification_acknowledged. Unacknowledged notifications auto-expire after 7 days (notification_expired).
Do not reply to a notification — messages against a notification-mode request return a
409 NO_RESPONSE_REQUIRED error. Just Acknowledge and move on. Reserve written replies
for help requests.
Setup
Step 1: Configure .env
Check if .env exists in {baseDir}. If not, copy from .env.example:
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— Expert key (hs_exp_...) from the dashboardHEYSUMMON_NOTIFY_TARGET— Chat ID for notifications
Step 2: Validate key
The API key MUST start with hs_exp_. Reject keys with hs_cli_ prefix — those are client keys.
Step 3: Start the watcher
bash {baseDir}/scripts/setup.sh
To stop: bash {baseDir}/scripts/teardown.sh
Architecture
AI Agent → HeySummon Platform → Polling → 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/polling-watcher.sh | Polling 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.
Approve/Deny Requests
When requiresApproval: true, the watcher sends a Telegram message with native Approve / Deny inline buttons.
callback_data format: hs:approve:HS-XXXX or hs:deny:HS-XXXX (using refCode).
When a button callback arrives (callback_data starts with hs:):
- Parse:
[_, decision, refCode] = callback_data.split(":") - Call
reply-handler.sh <refCode> <decision>— e.g.:bash scripts/reply-handler.sh HS-XXXX approved bash scripts/reply-handler.sh HS-XXXX denied - reply-handler.sh detects "approved"/"denied" and sends
approvalDecisionviaPOST /api/v1/message/[id] - Confirm to user: "Approved for HS-XXXX" or "Denied for HS-XXXX"
The consumer polling endpoint returns approvalDecision so the client skill can continue its workflow.
Statuses
| Status | Applies to | Meaning |
|---|---|---|
| pending | help, notify | Waiting for expert |
| active | help | Conversation in progress |
| responded | help | Expert sent a response |
| closed | help | Closed by either party |
| acknowledged | notify | Expert acknowledged the notification |
| expired | help, notify | help: no response within 72 hours. notify: not acknowledged within 7 days. |
Expert API Endpoints
All endpoints require x-api-key: hs_exp_... header.
Client Management
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/v1/expert/clients | List all client keys |
| POST | /api/v1/expert/clients | Create new client key |
| DELETE | /api/v1/expert/clients/:id | Revoke client key |
Message Monitoring
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/v1/expert/stats | Pending count, open requests, total messages |
| GET | /api/v1/expert/requests?status=pending | List pending requests |
Expert Management
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/v1/expert/profile | Get expert profile |
| PATCH | /api/v1/expert/profile | Update profile settings |
Related Skills
thomasansems/summon
tools
VerifiedTrustedCommunity
Ask a human expert for help via HeySummon. Use when you need approval, are stuck, or need human judgment. Sends the question and blocks until the expert replies.
3SKILL.mdUpdated May 7, 2026
thomasansems/skills/openclaw/heysummon
data-ai
VerifiedTrustedCommunity
# HeySummon -- Human in the Loop HeySummon has two distinct verbs. Pick the one that matches your intent: - **Use `help()` when:** the agent is stuck, needs approval, or needs human judgment before continuing. The script **blocks** until the expert replies. - **Use `notify()` when:** the human doesn't need to act — shipped-work notices, status heads-ups, low-urgency signals. The call returns immediately; the expert acknowledges later on their own time. If you're not sure: are you waiting on a
3SKILL.mdUpdated Apr 15, 2026
thomasansems/skills/openclaw/heysummon-expert
development
VerifiedTrustedCommunity
# HeySummon Expert Skill You are a human-help expert 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` — Expert key (`hs_exp_...`) from the dashboard - `HEYSUMMON_NOTIFY_TARGET` — Chat ID for notifications
3SKILL.mdUpdated Apr 15, 2026
thomasansems/heysummon
tools
VerifiedTrustedCommunity
Loop a human expert into your workflow via HeySummon. Use `help` when you need approval, are stuck, or need human judgment (blocking); use `notify` to send a status heads-up that needs no reply (fire-and-forget). Triggers on "hey summon <name>", "heysummon <name> <question>", or "notify <name> <message>".
3SKILL.mdUpdated Apr 15, 2026