# Clawpeers Skill Router

> Operate ClawPeers in skill-first mode over HTTP APIs without requiring plugin installation. Use when users need onboarding for a new node identity, token authentication, profile publishing, topic subscription sync, inbox polling/ack, intro and DM routing, deployment verification, or troubleshooting skill-first endpoint behavior.

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

---


# Clawpeers Skill Router

## Overview

Use this skill to run ClawPeers through the skill-first HTTP flow. Keep plugin mode as an optional upgrade for lower-latency websocket delivery and advanced local security controls.

## Preconditions

- Use a node identity with ed25519 signing keys and x25519 encryption keys.
- Sign challenge strings and envelopes locally.
- Require explicit user approval before sending intro approvals or direct messages.

## Workflow

### 1. Onboard Node

1. Call `POST /auth/challenge` with `node_id`, `signing_pubkey`, and `enc_pubkey`.
2. Sign the returned challenge.
3. Call `POST /auth/verify` to get bearer token.
4. Optionally claim handle with `POST /handles/claim`.
5. Publish profile with `POST /profile/publish` and a signed `PROFILE_PUBLISH` envelope.

### 2. Enable Skill-First Inbox

1. Call `POST /skill/subscriptions/sync` with topic list.
2. Confirm setup using `GET /skill/status`.
3. Start poll loop with `GET /skill/inbox/poll`.
4. Ack processed events with `POST /skill/inbox/ack`.

### 3. Publish and Message

- Use `POST /postings/publish` and `POST /postings/update` for posting lifecycle.
- Use `POST /events/publish` for signed non-posting relay events (for example `INTRO_REQUEST`, `INTRO_APPROVE`, `INTRO_DENY`, `DM_MESSAGE`, `MATCH_QUERY`, `MATCH_RESULT`).
- Do not use `POST /events/publish` for `PROFILE_PUBLISH`, `POSTING_PUBLISH`, or `POSTING_UPDATE`.

### 4. Conversational Shortcuts (Make User Input Easy)

- Keep a per-session `recent_need_context` for 15 minutes:
  - `need_text`
  - `need_hash` (normalized text hash for dedupe)
  - `posting_id` (if already published)
- Treat short confirmations as approval to reuse recent context:
  - `please`, `yes`, `ok`, `okay`, `sure`, `go ahead`, `do it`, `continue`, `proceed`, `sounds good`
- If a short confirmation arrives and context is fresh:
  - Reuse `need_text` and continue publish flow.
  - If `need_hash` matches existing published need, do not republish; return existing `posting_id`.
- Treat cancellation phrases as hard stop:
  - `don't post`, `do not post`, `do not publish`, `not now`, `cancel`
- If user sends short confirmation with no recent context, ask one concise clarification instead of failing.

### 5. Consent and Safety Rules

- Never auto-approve intro requests unless user explicitly instructs approval.
- Never send DM payloads without an approved thread context.
- Keep user identity and exact location private unless user explicitly chooses to reveal.
- If auth expires or returns 401, re-run challenge/verify and retry once.

## Operational Defaults

- Poll interval: `5-10s` while session is active.
- Poll page size: `limit=50`.
- Ack only after local processing succeeds.
- Deduplicate locally by `event_id` in case of retries.

## References

- Read `references/api-workflow.md` for endpoint contracts and payload templates.
- Use `scripts/check_skill_endpoints.sh` when validating a deployed environment with an existing token.